Improve/skill review optimization

.github/workflows/skill-review.yml

@@ -0,0 +1,13 @@
+name: Skill Review
+on:
+  pull_request:
+    paths: ['**/SKILL.md']
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: tesslio/skill-review@22e928dd837202b2b1d1397e0114c92e0fae5ead # main

plugins/app/skills/swift-testing/SKILL.md

@@ -1,19 +1,18 @@
 ---
 name: swift-testing
-description: WHEN writing tests in Swift with the Swift Testing framework; NOT XCTest.
+description: "WHEN writing tests in Swift with the Swift Testing framework; NOT for XCTest or Objective-C tests; creates @Test-annotated functions, writes #expect and #require assertions, validates thrown errors with #expect(throws:), structures test suites with @Suite, and applies macro-driven testing patterns."
 ---
 
 # Swift Testing Framework: Basics
 
-Guidance for starting with Swift Testing (Testing framework) and writing clear, macro-driven tests.
+Guidance for writing clear, macro-driven tests with Swift Testing.
 
 ## Core Concepts
 
 - Import `Testing` to unlock macros; tests are plain functions annotated with `@Test`.
 - Name tests freely; use `@Test("Display Name")` to set the navigator title.
 - `#expect` is the primary assertion; pass a boolean expression to assert truthy outcomes.
 - Async/throwing tests are supported via `async`/`throws` on the test function.
-- Works alongside XCTest in the same project.
 
 ## Example: Simple Test
 

plugins/core/skills/commit-messages/SKILL.md

@@ -1,25 +1,11 @@
 ---
 name: commit-messages
-description: WHEN writing git/conventional commits; NOT for PR text; returns concise, why-first commit lines with proper type/scope.
+description: "WHEN writing git/conventional commits; NOT for PR text; analyzes diffs, formats type(scope): subject lines, assesses commit scope for splitting, and returns concise why-first messages with proper conventional commit structure."
 ---
 
 # Commit Messages
 
-Use this skill to generate clear, conventional commit messages that explain the "why" not just the "what". Follow this guide when writing commit messages or helping users structure their commits.
-
-## When to Use
-
-- User asks for help writing a commit message
-- User wants to understand conventional commit format
-- User needs to split a large commit into smaller ones
-- User asks about commit best practices
-
-## Philosophy
-
-- **Why > What** - The diff shows what changed; the message explains why
-- **Atomic commits** - One logical change per commit
-- **Future readers** - Write for someone debugging at 2am in 6 months
-- **Searchable** - Make it easy to find with `git log --grep`
+Generate clear, conventional commit messages that explain the "why" not just the "what".
 
 ## Format
 

plugins/typescript/skills/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: typescript
-description: WHEN writing TypeScript, defining types/schemas, or building type-safe apps; outputs strict, schema-first, production-ready code.
+description: "WHEN writing TypeScript, defining types/schemas in .ts/.tsx files, or building type-safe apps with Zod; NOT for plain JavaScript without types; generates schema-first validation with z.infer, creates discriminated unions and branded types, defines strict interfaces and type guards, and enforces immutable patterns with readonly."
 ---
 
 # TypeScript Best Practices
@@ -25,60 +25,26 @@ Production-grade TypeScript development with schema-first design, strict type sa
 | Branded types, utility types, code smells reference                    | [utilities.md](references/utilities.md)               |
 | Common TypeScript patterns with examples                               | [patterns.md](references/patterns.md)                 |
 
-## When to Use Each Guide
+## Inline Example: Schema-First Pattern
 
-### Schemas
+```typescript
+import { z } from "zod";
 
-Use [schemas.md](references/schemas.md) when you need:
+// 1. Define schema at trust boundary
+const UserSchema = z.object({
+  id: z.string().brand<"UserId">(),
+  email: z.string().email(),
+  role: z.enum(["admin", "member"]),
+});
 
-- Schema-first development patterns
-- Decision framework: when schema is required vs optional
-- Trust boundary identification
-- Test data factory patterns with schema validation
-- Examples of schema usage (API responses, business validation)
+// 2. Derive type from schema
+type User = z.infer<typeof UserSchema>;
 
-### Types and Interfaces
-
-Use [types-interfaces.md](references/types-interfaces.md) when you need:
-
-- Type vs interface guidance
-- The any vs unknown decision
-- Type assertion best practices
-- Strict mode configuration
-- tsconfig.json settings
-
-### Immutability
-
-Use [immutability.md](references/immutability.md) when you need:
-
-- Immutability patterns (spread operators)
-- Readonly modifiers
-- Forbidden array methods reference
-- Options objects vs positional parameters
-- Boolean parameter anti-patterns
-- Result types for error handling
-- Early return patterns
-
-### Utilities
-
-Use [utilities.md](references/utilities.md) when you need:
-
-- Branded types for domain concepts
-- Built-in utility types (Pick, Omit, Partial, etc.)
-- Custom utility types
-- Code smell reference tables
-
-### Patterns
-
-Use [patterns.md](references/patterns.md) when you need:
-
-- Schema-first examples at trust boundaries
-- Internal type examples without schemas
-- Schema with test factory patterns
-- Result type for error handling
-- Branded types for domain safety
-- Immutable array operations
-- Options object pattern
+// 3. Validate at boundary, trust internally
+function parseUser(raw: unknown): User {
+  return UserSchema.parse(raw);
+}
+```
 
 ## Quick Reference: Decision Trees
 

plugins/web/skills/react/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: react
-description: WHEN building React components/pages/apps; enforces scalable architecture, state management, API layer, performance patterns.
+description: "WHEN building React components, pages, or apps with JSX/TSX; NOT for non-React frontends or server-only code; creates feature-based folder structures, implements hooks and state management with React Query/Zustand, builds API integration layers, applies code splitting and memoization, and enforces component composition patterns."
 ---
 
 # React Best Practices
@@ -29,86 +29,34 @@ Production-grade React development with feature-based architecture, type-safe st
 | Testing pyramid and strategy         | [testing-strategy.md](./references/testing-strategy.md)       |
 | Project tooling standards            | [project-standards.md](./references/project-standards.md)     |
 
-## When to Use Each Guide
+## Canonical Feature Module
 
-### Project Structure
-
-Use [project-structure.md](./references/project-structure.md) when you need:
-
-- Directory organization (app, features, components)
-- Feature module structure
-- Import architecture (unidirectional flow)
-- ESLint boundary enforcement
-- File naming conventions
-
-### Component Patterns
-
-Use [component-patterns.md](./references/component-patterns.md) when you need:
-
-- Colocation principles
-- Composition over props patterns
-- Wrapping third-party components
-- Avoiding nested render functions
-
-### Compound Components
-
-Use [compound-components.md](./references/compound-components.md) when you need:
-
-- Multi-part components (Card, Accordion, etc.)
-- Flexible composition patterns
-- Semantic component structure
-
-### State Management
-
-Use [state-management.md](./references/state-management.md) when you need:
-
-- State category decisions (component, application, server cache)
-- useState vs useReducer guidance
-- Server cache with React Query
-- State placement guidelines
-
-### API Layer
-
-Use [api-layer.md](./references/api-layer.md) when you need:
-
-- API client configuration
-- Request structure (schema, fetcher, hook)
-- Error handling (interceptors, boundaries)
-- Security patterns (auth, sanitization, authorization)
-
-### Performance
-
-Use [performance.md](./references/performance.md) when you need:
-
-- Code splitting strategies
-- State optimization
-- Children optimization patterns
-- Styling performance
-- Image optimization
-
-### useEffect
-
-Use [useeffect.md](./references/useeffect.md) when you need:
-
-- When NOT to use useEffect (most cases)
-- When useEffect IS appropriate (external systems)
-- Dependency array rules
-- Alternatives to useEffect
-
-### Testing Strategy
-
-Use [testing-strategy.md](./references/testing-strategy.md) when you need:
+```
+src/features/auth/
+├── components/
+│   └── LoginForm.tsx      # Feature-scoped component
+├── hooks/
+│   └── useAuth.ts         # Custom hook wrapping React Query
+├── api/
+│   └── auth.ts            # Schema → fetcher → hook
+└── index.ts               # Public API (barrel export)
+```
 
-- Testing pyramid (prioritize integration over unit)
-- What to test at each level (unit, integration, E2E)
-- Testing Library principles (query by accessible names)
+```tsx
+// src/features/auth/api/auth.ts — schema-first API pattern
+import { z } from "zod";
+import { useQuery } from "@tanstack/react-query";
+import { api } from "@/lib/api-client";
 
-### Project Standards
+const UserSchema = z.object({ id: z.string(), email: z.string() });
+type User = z.infer<typeof UserSchema>;
 
-Use [project-standards.md](./references/project-standards.md) when you need:
+const getUser = async (id: string): Promise<User> =>
+  api.get(`/users/${id}`).then((r) => UserSchema.parse(r.data));
 
-- Required tooling (ESLint, Prettier, TypeScript, Husky)
-- Pre-commit hook configuration
+export const useUser = (id: string) =>
+  useQuery({ queryKey: ["user", id], queryFn: () => getUser(id) });
+```
 
 ## Quick Reference: Decision Trees
 

plugins/web/skills/tdd/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tdd
-description: WHEN working in TDD Red-Green-Refactor; NOT ad-hoc coding; write tests first, add minimal code to green, then assess refactoring.
+description: "WHEN working in test-driven development with Red-Green-Refactor; NOT for ad-hoc coding or retrofitting tests; writes failing test cases first, implements minimal passing code, assesses refactoring opportunities, uses factory functions for test data, and enforces behavior-focused testing through public APIs."
 ---
 
 # TDD Best Practices
@@ -59,49 +59,23 @@ With tests green, assess whether refactoring would add value.
 | Critical violations, high priority issues, style improvements    | [violations.md](references/violations.md)               |
 | Behavior testing patterns, test naming, and organization         | [patterns.md](references/patterns.md)                   |
 
-## When to Use Each Guide
+## Inline Example: One TDD Cycle
 
-### Workflow Examples
+```typescript
+// RED — describe desired behavior
+test("applies 10% discount for orders over $100", () => {
+  const order = createOrder({ items: [{ price: 150 }] });
+  expect(calculateTotal(order)).toBe(135);
+});
 
-Use [workflow-examples.md](references/workflow-examples.md) when you need:
+// GREEN — minimal implementation
+function calculateTotal(order: Order): number {
+  const subtotal = order.items.reduce((sum, i) => sum + i.price, 0);
+  return subtotal > 100 ? subtotal * 0.9 : subtotal;
+}
 
-- Complete TDD workflow examples (free shipping, payment validation)
-- Step-by-step RED-GREEN-REFACTOR cycles
-- When to refactor vs when to move on
-- Refactoring assessment criteria
-- Refactoring rules (commit first, preserve API, etc.)
-
-### Test Factories
-
-Use [test-factories.md](references/test-factories.md) when you need:
-
-- Factory function patterns with overrides
-- Why factories beat let/beforeEach
-- Composing factories for complex data
-- Test organization by behavior
-- No 1:1 mapping between tests and implementation
-- Achieving 100% coverage through behavior testing
-
-### Violations
-
-Use [violations.md](references/violations.md) when you need:
-
-- Critical violations reference (production code without test, etc.)
-- High priority issues (let/beforeEach, testing privates, etc.)
-- Style issues (large files, duplication, magic values)
-- Behavior vs implementation examples
-- Quality gates checklist
-
-### Patterns
-
-Use [patterns.md](references/patterns.md) when you need:
-
-- Behavior-focused testing examples
-- Testing through public APIs only
-- Factory patterns with schema validation
-- Composing factories for complex data
-- Descriptive test naming patterns
-- Test organization by business behavior
+// REFACTOR — extract threshold/rate if needed, commit first
+```
 
 ## Quick Reference: Decision Trees