refactor(claude): apply skill authoring guidelines to existing skills

2026-08-14 09:59:44 +00:00 · 2026-01-26 18:48:25 +11:00
parent 33628a9d24
commit c83f3d58b4
8 changed files with 65 additions and 91 deletions
@@ -2,6 +2,24 @@

 Patterns for designing and using state management in TypeScript libraries.

+## Contents
+
+- [Mental Models](#mental-models) — Zustand, Jotai, XState, Valtio
+- [Core Subscription Interface](#core-subscription-interface)
+- [Middleware as Higher-Order Functions](#middleware-as-higher-order-functions)
+- [Slice Pattern](#slice-pattern)
+- [Atomic Composition](#atomic-composition-jotai-pattern)
+- [Selector Pattern](#selector-pattern)
+- [Split Stores When Truly Isolated](#split-stores-when-truly-isolated)
+- [Cross-Store Access](#cross-store-access)
+- [Derived State Patterns](#derived-state-patterns)
+- [Optimistic Updates](#optimistic-updates)
+- [State Initialization](#state-initialization)
+- [Request State Pattern](#request-state-pattern)
+- [Proxy-Based Reactivity](#proxy-based-reactivity-valtio)
+- [Presets as Transparent Collections](#presets-as-transparent-collections)
+- [Dev Tools Integration](#dev-tools-integration)
+
 ## Mental Models

 Daishi Kato created Zustand, Jotai, and Valtio with intentionally different architectures because **different problems need different mental models**.
@@ -2,6 +2,14 @@

 Roles, states, properties, labeling strategies, and live regions.

+## Contents
+
+- [First Rule of ARIA](#first-rule-of-aria) — Use native HTML when possible
+- [Roles by Component](#roles-by-component) — Buttons, menus, dialogs, lists, tabs, sliders
+- [Required Attributes by Role](#required-attributes-by-role)
+- [State Attributes](#state-attributes) — pressed, expanded, selected, checked, current
+- [Labeling](#labeling) — Priority order, aria-label vs aria-labelledby
+
 ---

 ## First Rule of ARIA
@@ -2,6 +2,16 @@

 Accessibility patterns specific to video and audio players. Covers controls, keyboard shortcuts, captions, and screen reader support.

+## Contents
+
+- [Player Container](#player-container) — Root element identification
+- [Keyboard Shortcuts](#keyboard-shortcuts) — Standard media keys, key scope
+- [Control Bar](#control-bar) — Toolbar pattern
+- [Control Components](#control-components) — Play, mute, time slider, volume, fullscreen, captions
+- [Settings Menu](#settings-menu) — Structure, keyboard navigation
+- [Live Announcements](#live-announcements) — Announcer component, events to announce
+- [Captions](#captions) — CVAA compliance requirements
+
 ---

 ## Player Container
@@ -2,6 +2,16 @@

 React-specific patterns for accessibility. Covers hook architecture, ref management, and framework considerations.

+## Contents
+
+- [Hook Architecture](#hook-architecture) — Layer separation, behavior hooks
+- [Focus Management Hooks](#focus-management-hooks) — Scope, ring detection, roving tabindex
+- [Ref Patterns](#ref-patterns) — Merging refs, callback refs
+- [Event Handling](#event-handling) — Keyboard normalization, press events
+- [Announcements](#announcements) — Live regions, status messages
+- [SSR Considerations](#ssr-considerations) — ID generation, hydration
+- [Portal Accessibility](#portal-accessibility)
+
 ---

 ## Hook Architecture
@@ -1,6 +1,8 @@
 ---
 name: claude-update
-description: Update CLAUDE.md and skills when introducing new patterns or conventions
+description: >-
+  Update CLAUDE.md and skills when introducing new patterns or conventions.
+  Triggers: "update claude", "update skills", "new pattern", "add convention".
 context: fork
 disable-model-invocation: true
 ---
@@ -5,6 +5,7 @@ description: >-
  Use when creating component libraries, design systems, or reusable UI primitives.
  Handles compound components, state management, accessibility, styling hooks, and API design.
  Includes Lit (controllers, ReactiveElement) and React (hooks, context) patterns.
+  Triggers: "create component", "component pattern", "compound component", "headless component".
 ---

 # Component Architecture Patterns
@@ -2,6 +2,12 @@

 Patterns from Zustand, Jotai, XState, Vite, Vitest, esbuild, Biome.

+## Contents
+
+- [State Management Documentation](#state-management-documentation) — Zustand, Jotai, XState patterns
+- [Configuration Documentation](#configuration-documentation) — Vite, esbuild patterns
+- [Testing Documentation](#testing-documentation-vitest) — Test examples, mocking media
+
 ## State Management Documentation

 ### Zustand Pattern: Minimal Getting Started
@@ -75,97 +75,18 @@ For deeper domain-specific review, load the relevant skill:

 Skip this step for quick reviews using the inline checklists below.

-### Step 4: Apply Skill-Based Review Checklists
+### Step 4: Apply Skill-Based Review

-Based on detected categories, apply the relevant quick checklists:
+Based on detected categories, load the relevant skill's review checklist:

---
+| Category      | Load Checklist                     |
+| ------------- | ---------------------------------- |
+| API/Code      | `api/review/checklist.md`          |
+| UI Components | `component/review/checklist.md`    |
+| Accessibility | `aria/review/checklist.md`         |
+| Documentation | `docs/review/workflow.md`          |

-#### API/Code Changes Checklist (from `api` skill)
-
-**Types & Inference:**
-
- [ ] Types infer without manual annotation
- [ ] Generics infer from arguments, not explicit type params
- [ ] No unnecessary `as` casts
- [ ] Explicit context narrowing where needed
-
-**API Surface:**
-
- [ ] Config objects for 3+ parameters (no long param lists)
- [ ] No function overloads (use config objects instead)
- [ ] Flat returns for independent values
- [ ] Consistent naming with existing codebase
-
-**Composition & Extensibility:**
-
- [ ] Extension through composition, not inheritance
- [ ] Tree-shakeable exports
- [ ] Framework-agnostic where appropriate
-
-**Patterns:**
-
- [ ] Uses existing utilities from `@videojs/utils` where applicable
- [ ] Follows Symbol identification pattern for cross-realm objects
- [ ] Subscribe pattern returns unsubscribe function
- [ ] Destroy pattern guards re-entry
-
---
-
-#### UI Component Changes Checklist (from `component` and `aria` skills)
-
-**Component Architecture:**
-
- [ ] Compound component pattern where appropriate
- [ ] Render props over implicit requirements
- [ ] Controlled and uncontrolled modes supported
- [ ] Context properly scoped for nesting
-
-**Styling:**
-
- [ ] Data attributes for state-based styling (`data-*`)
- [ ] CSS variables for customization
- [ ] No inline animation JS (prefer CSS transitions)
-
-**Accessibility:**
-
- [ ] Proper ARIA roles and attributes
- [ ] Keyboard navigation supported
- [ ] Focus management correct (trap, restore, roving)
- [ ] Screen reader announcements where needed
-
---
-
-#### Documentation Changes Checklist (from `docs` skill)
-
-**Tone & Style:**
-
- [ ] No filler words ("basically", "simply", "just", "in order to")
- [ ] No hedging ("might", "could", "perhaps")
- [ ] Active voice, second person ("you")
- [ ] Direct and confident
-
-**Structure:**
-
- [ ] Code before explanation (show, don't tell first)
- [ ] Progressive disclosure (simple → complex)
- [ ] Matches appropriate doc type (handbook, guide, API ref, component)
- [ ] Has "See Also" section with cross-links
-
-**Code Examples:**
-
- [ ] All imports shown
- [ ] Examples are runnable/copy-pasteable
- [ ] Includes Do/Don't patterns where helpful
-
-**AI Readiness:**
-
- [ ] Self-contained (doesn't rely on external context)
- [ ] Clean markdown (no complex HTML)
-
---
-
-#### Test Changes Checklist
+For test changes, apply these checks:

 - [ ] Tests follow `act → assert` pattern
 - [ ] Test file named `<module>.test.ts`
@@ -173,8 +94,6 @@ Based on detected categories, apply the relevant quick checklists:
 - [ ] Uses `vi.fn()` for mocks
 - [ ] Tests live in `tests/` directory next to implementation

---
-
 ### Step 5: General Code Review

 In addition to skill-based checks, review for: