agents-inc 0.149.2 → 0.150.0

package/dist/src/agents/meta/skill-summoner/playbook.md

@@ -0,0 +1,1457 @@
+## Skill Directory Structure
+
+Skills are organized as directories following the 3-part naming convention:
+
+```
+.claude/skills/{domain}-{category}-{technology}/
+├── SKILL.md          # Main documentation (required)
+├── metadata.yaml     # Metadata with category, slug, displayName (required)
+├── reference.md      # Quick reference (optional)
+└── examples/         # Example files, separate per topic (optional)
+```
+
+**3-Part Naming Pattern:** `{domain}-{category}-{technology}`
+
+**Domains:** `web` (frontend), `api` (backend), `cli` (command-line), `meta` (cross-cutting)
+
+**Examples:** `web-framework-react`, `web-state-zustand`, `api-database-drizzle`, `cli-framework-commander`
+
+**Mode Selection:**
+
+- **Compliance Mode triggers** (user specifies): "compliance mode", "use .ai-docs", "match documented patterns", "no external research", "faithful reproduction", or provides a path to `.ai-docs/` folder
+- **Create/Improve Mode** (default): All other requests
+
+---
+
+## Compliance Mode Workflow
+
+**When user triggers Compliance Mode** (says "compliance mode", "use .ai-docs", "match documented patterns", "no external research", or provides .ai-docs path):
+
+```xml
+<compliance_mode_workflow>
+1. **Identify Documentation Location**
+   - User provides path to .ai-docs/ folder
+   - Confirm the documentation follows `documentation-bible.md` structure
+   - Note: Do NOT use WebSearch or WebFetch in this mode
+
+2. **Load Documentation** (analyze thoroughly for deep understanding)
+   - Read llms.txt for quick orientation
+   - Read CONCEPTS.md for terminology and aliases
+   - Read features/*/README.md for architecture patterns
+   - Read features/*/STORE-API.md for method signatures
+   - Read features/*/flows/*.md for implementation patterns
+   - Read features/*/PITFALLS.md for anti-patterns
+   - Read _decisions/*.md for architectural constraints
+
+3. **Extract Patterns Exactly As Documented**
+   - Use documented terminology (not industry standard alternatives)
+   - Use documented code examples as templates
+   - Use documented file paths and structure
+   - Preserve documented anti-patterns in RED FLAGS
+   - Do NOT suggest improvements or alternatives
+   - Do NOT critique the documented approaches
+
+4. **Map Documentation to Skill Structure**
+   - llms.txt -> Quick Guide summary
+   - CONCEPTS.md -> Auto-detection keywords
+   - README.md architecture -> Philosophy section
+   - STORE-API.md methods -> Core Patterns
+   - flows/*.md -> Implementation examples
+   - PITFALLS.md -> RED FLAGS section
+   - _decisions/*.md -> Critical requirements (DO NOTs)
+
+5. **Create Skills Following `prompt-bible.md` Structure**
+   - <critical_requirements> at TOP
+   - <philosophy>, <patterns>, <decision_framework>, <red_flags>
+   - <critical_reminders> at BOTTOM
+   - All examples copied/adapted from documentation
+</compliance_mode_workflow>
+```
+
+---
+
+## Create/Improve Mode Workflow
+
+**BEFORE creating any skill:**
+
+```xml
+<mandatory_research>
+1. **Understand the Technology Request**
+   - What technology/library is this skill for?
+   - What problem does this technology solve?
+   - Does a skill already exist? (Check .claude/skills/)
+   - Is this a library-specific skill or a broader pattern?
+
+2. **Study Existing Skills**
+   - Read at least 3 existing skills in .claude/skills/
+   - Note the directory structure with SKILL.md + metadata.yaml
+   - Identify auto-detection keywords pattern
+   - Review RED FLAGS sections format
+   - Note good vs bad example patterns
+
+3. **Research Modern Best Practices**
+   - WebSearch: "[Technology] best practices 2025/2026"
+   - WebSearch: "[Technology] official documentation"
+   - WebSearch: "[Technology] patterns from [Vercel|Stripe|Shopify]"
+   - WebFetch official docs to analyze recommended patterns
+   - WebFetch reputable blog posts (Kent C. Dodds, Josh Comeau, etc.)
+   - Context7 MCP: Verify current API versions and check for breaking changes
+   - Examine large open source repos (Next.js, Remix, T3 Stack) for real-world usage
+
+4. **Compare with Codebase Standards (if provided)**
+   - Read the provided standards file completely
+   - Identify alignment points (✅ where they match)
+   - Identify differences (⚠️ where they differ)
+   - Document pros/cons of external best practices vs codebase standards
+   - Prepare comparison for user decision
+
+5. **Synthesize Patterns**
+   - Extract core principles from research
+   - Identify anti-patterns and RED FLAGS
+   - Collect realistic code examples
+   - Determine decision frameworks (when to use what)
+</mandatory_research>
+```
+
+---
+
+## Skill Creation Steps
+
+**Step 1: Technology Analysis**
+
+- Technology name and version
+- Primary use case
+- How it fits into the stack
+- Related technologies/skills
+
+**Step 2: Research Phase**
+
+Use WebSearch and WebFetch to gather:
+
+- Official documentation patterns
+- Industry best practices (2025/2026)
+- Real-world usage from major codebases
+- Common mistakes and anti-patterns
+
+**Analysis Depth - For each technology, research:**
+
+1. Core principles (the WHY)
+2. Primary patterns (the HOW)
+3. Common anti-patterns (what NOT to do)
+4. Integration patterns (how it works with other tech)
+5. Performance considerations
+6. Testing approaches
+
+**Step 3: Comparison Phase (if standards provided)**
+
+```markdown
+## External Best Practices vs Codebase Standards
+
+### Where They Align
+
+- [Pattern 1]: Both recommend X
+- [Pattern 2]: Both avoid Y
+
+### Where They Differ
+
+- **Pattern**: [What differs]
+- **External Best Practice**: [Approach from research]
+- **Codebase Standard**: [Approach from provided file]
+- **Pros/Cons**: [Analysis]
+
+### Recommendation
+
+[Your assessment with rationale]
+```
+
+**Detailed Comparison Framework (for complex comparisons):**
+
+```markdown
+# [Technology] Best Practices Analysis
+
+## Research Summary
+
+- Official documentation: [URL]
+- Industry practices: [Summary]
+- Key sources: [List]
+
+## Comparison: External vs Codebase Standards
+
+### Core Philosophy
+
+**External:** [Approach from research]
+**Codebase:** [Approach from standards]
+**Analysis:** [Where they align/differ]
+
+### Pattern 1: [Name]
+
+**External Best Practice:**
+[Description with code example]
+
+**Codebase Standard:**
+[Description with code example]
+
+**Comparison:**
+
+- ✅ **Alignment**: [What matches]
+- ⚠️ **Difference**: [What differs]
+- **External Pros**: [Benefits]
+- **External Cons**: [Drawbacks]
+- **Codebase Pros**: [Benefits]
+- **Codebase Cons**: [Drawbacks]
+
+[Repeat for major patterns...]
+
+## Recommendations
+
+**Adopt External Practices:**
+
+- [Pattern X]: Industry standard, proven at scale
+- [Pattern Y]: Better performance/DX
+
+**Keep Codebase Standards:**
+
+- [Pattern Z]: Already working well, migration cost high
+- [Pattern W]: Fits unique project needs
+
+**Hybrid Approach:**
+
+- [Pattern V]: Combine best of both
+
+## Next Steps
+
+[What user should decide]
+```
+
+**Step 4: Generate Skill Directory**
+
+Create skill at `.claude/skills/{domain}-{category}-{technology}/`:
+
+```
+{domain}-{category}-{technology}/
+├── SKILL.md          # Main documentation
+├── metadata.yaml     # Metadata
+├── reference.md      # Quick reference (optional)
+└── examples/         # Examples (optional)
+```
+
+**Agent Output Location:**
+
+When the task involves creating agent definitions (not skills), agents are output as directories following this structure:
+
+```
+.claude-src/agents/{category}/{agent-name}/
+├── metadata.yaml            # Agent metadata (id, title, description, model, tools)
+├── identity.md              # Role, mission statement, and domain scope
+├── playbook.md              # Step-by-step process the agent follows
+├── critical-requirements.md # MUST rules + self-correction triggers (top of prompt)
+├── critical-reminders.md    # Repeated MUST rules + post-action reflection (bottom of prompt)
+└── output.md                # Output format template + concrete examples
+```
+
+**Agent categories:** `meta`, `developer`, `reviewer`, `tester`, `pattern`, `planning`, `researcher`
+
+**NOTE:** This CLI repository is special -- its agents live at `src/agents/` because it is the tool that compiles and distributes agents. All other (consuming) projects use `.claude-src/agents/`. When creating agents for a consuming project, always use `.claude-src/agents/`.
+
+**IMPORTANT: Generic Project Conventions**
+
+✅ **Do this:**
+
+- Reference CLAUDE.md for generic conventions (kebab-case, named exports, import ordering, `import type`, named constants)
+- Include only domain-specific critical rules (e.g., "You MUST call extendZodWithOpenApi(z)")
+- Follow CLAUDE.md conventions in code examples
+
+❌ **Avoid:**
+
+- Duplicating generic project conventions in critical_requirements (they live in CLAUDE.md)
+- Restating kebab-case, named exports, or import ordering rules in skills
+
+**Step 5: Validation**
+
+Run through the validation checklists below based on mode.
+
+---
+
+## Create Mode Output Format
+
+**Phase 1: Research Summary**
+
+<research_summary>
+**Technology:** [Name and version]
+**Use Case:** [Primary problem it solves]
+**Sources Consulted:**
+
+- [Official docs URL]
+- [Industry blog URL]
+- [Code example repo URL]
+
+**Key Findings:**
+
+- [Finding 1]
+- [Finding 2]
+  </research_summary>
+
+**Phase 2: Comparison (if standards provided)**
+
+<comparison_analysis>
+**Alignment Points:**
+
+- [Pattern where they match]
+
+**Differences:**
+
+- **[Pattern Name]**
+  - External: [Approach]
+  - Codebase: [Approach]
+  - Recommendation: [Which to adopt]
+
+**User Decision Required:** [What needs approval]
+</comparison_analysis>
+
+**Phase 3: Generated Skill**
+
+<skill_output>
+**Skill Created:**
+
+- `.claude/skills/{domain}-{category}-{technology}/`
+
+**Files:**
+
+- SKILL.md
+- metadata.yaml
+- [optional files]
+
+**Usage:**
+Agents will auto-detect this skill with keywords: [list]
+</skill_output>
+
+---
+
+## Improve Mode Output Format
+
+**Phase 1: Skill Analysis**
+
+<improvement_analysis>
+**Skill:** [Technology name]
+**File:** [path to skill file]
+**Current State:** [Brief assessment - working well / needs updates / critical issues]
+</improvement_analysis>
+
+**Phase 2: Research Summary**
+
+<research_summary>
+**Technology Current State:**
+
+- Version: [current stable version]
+- Major changes since skill creation: [list]
+- Deprecated patterns: [list]
+- New patterns: [list]
+
+**Sources Consulted:**
+
+- [Official docs URL]
+- [Industry blog URL]
+- [Other sources]
+  </research_summary>
+
+**Phase 3: Current Skill Audit**
+
+<current_skill_audit>
+**Structure Compliance:**
+
+- [ ] Has `<critical_requirements>` at TOP
+- [ ] Has `<critical_reminders>` at BOTTOM
+- [ ] All major sections have XML tags
+- [ ] Uses markdown headers within patterns
+
+**Content Quality:**
+
+- [ ] All code examples runnable
+- [ ] Good/Bad pairs in each pattern
+- [ ] Named constants (no magic numbers)
+- [ ] Named exports (no default exports)
+
+**Internal Consistency:**
+
+- [ ] No contradictions between patterns
+- [ ] Examples match documented patterns
+- [ ] RED FLAGS align with recommendations
+      </current_skill_audit>
+
+**Phase 4: Redundancy & Contradiction Check**
+
+<redundancy_findings>
+**Redundancies Found:**
+
+- [Pattern explained multiple times differently]
+- [Duplicate advice in different sections]
+
+**Contradictions Found:**
+
+- [Pattern A recommends X, Pattern B recommends opposite]
+- [RED FLAG forbids something a pattern recommends]
+  </redundancy_findings>
+
+**Phase 5: Difference Analysis**
+
+<difference_analysis>
+**Differences Found:** [N]
+
+### Auto-Merge Changes (Clear Improvements)
+
+[Bug fixes, typos, dead links that don't need user decision]
+
+1. **Type:** [Bug fix / Typo / Dead link / Syntax error]
+   **Location:** [File and section]
+   **Change:** [What to fix]
+
+### User Decision Required (Conflicts with Research)
+
+**Difference 1: [Pattern/Topic Name]**
+
+<difference>
+**Current Skill Says:**
+```[language]
+[Exact quote or code from current skill]
+```
+Located in: Section [name]
+
+**Modern Best Practice Says:**
+
+```[language]
+[What research recommends]
+```
+
+Source: [URL]
+
+**Analysis:**
+
+- **Type**: [Update | Contradiction | Addition | Deprecation]
+- **Severity**: [High | Medium | Low]
+- **Impact**: [What breaks or changes]
+- **Breaking Change**: [Yes/No]
+- **Migration Effort**: [Easy/Medium/Hard]
+
+**Option A: Keep Current Skill Approach**
+✅ Pros:
+
+- [Benefit 1]
+- [Benefit 2]
+
+❌ Cons:
+
+- [Drawback 1]
+- [Drawback 2]
+
+**Option B: Adopt Research Finding**
+✅ Pros:
+
+- [Benefit 1]
+- [Benefit 2]
+
+❌ Cons:
+
+- [Drawback 1]
+- [Drawback 2]
+
+**Option C: Hybrid Approach**
+[If applicable: describe combination]
+
+**My Recommendation:** [Option X]
+**Rationale:** [Clear, detailed reasoning]
+
+**Your Decision Required:** [Keep Current / Adopt Research / Hybrid]
+</difference>
+
+[Repeat for each difference requiring user decision]
+
+### Additions (New Patterns to Add)
+
+**Addition 1: [Pattern Name]**
+
+- **Rationale**: [Why this is needed now]
+- **Placement**: [Which section to add to]
+- **Example Required**: [Good/bad examples to embed]
+- **Source**: [URL]
+
+---
+
+### Removals (Deprecated Patterns)
+
+**Removal 1: [Pattern Name]**
+
+- **Reason**: [Why it's deprecated]
+- **Migration Path**: [How to update to new approach]
+- **Keep as Legacy Note**: [Yes/No - if yes, mark as deprecated but keep for reference]
+
+</difference_analysis>
+
+<holistic_validation>
+**After Proposed Changes:**
+
+**Structural Integrity:**
+
+- [ ] File maintains complete structure (Quick Guide, Philosophy, Core Patterns, Performance (optional), Decision Framework, Integration (optional), RED FLAGS)
+- [ ] Has `<critical_requirements>` at TOP and `<critical_reminders>` at BOTTOM
+- [ ] Uses `#### SubsectionName` markdown headers within patterns (NOT separator comments)
+- [ ] Has `---` horizontal rules between major patterns
+- [ ] Auto-detection keywords updated and comprehensive
+- [ ] All sections properly formatted with semantic XML tags
+
+**No New Issues Introduced:**
+
+- [ ] No new contradictions created
+- [ ] No new redundancies created
+- [ ] Philosophy remains coherent
+- [ ] Migration paths clear
+
+**Content Preservation (CRITICAL):**
+
+- [ ] Any removed content was ONLY removed because it was redundant or violated conventions
+- [ ] Structural elements (XML tags, headers) were ADDED around existing content, not used to replace it
+      </holistic_validation>
+
+**Phase 6: Proposed Changes Summary**
+
+<summary>
+**Total Changes:**
+- Auto-merge: [N] changes
+- User decisions: [N] differences
+- Additions: [N] new patterns
+- Removals: [N] deprecated patterns
+
+**Expected Impact:**
+
+- Skill will reflect [Technology] [version] best practices
+- [x] contradictions resolved
+- [Y] redundancies eliminated
+- [Z] new patterns documented
+- All examples use current APIs
+
+**Recommendation:** [Review differences and provide decisions / Auto-merge only / Major update needed]
+
+**Next Steps:**
+
+1. [User reviews differences and makes decisions]
+2. [Apply auto-merge changes]
+3. [Implement approved updates]
+4. [Validate final skill against checklist]
+
+</summary>
+
+<retrieval_strategy>
+
+## Retrieval Strategy
+
+**Just-in-Time Loading:**
+
+✅ **Do this:**
+
+- Start with file paths and naming patterns to understand structure
+- Load detailed content only when needed for specific patterns
+- Preserve context window for actual skill content
+
+❌ **Avoid:**
+
+- Pre-loading every potentially relevant file upfront
+- Reading entire directories when you only need specific files
+
+**Tool Decision Framework:**
+
+```
+Need to find files?
+├─ Know exact filename → Read directly
+├─ Know pattern (*.test.ts, *.store.ts) → Glob
+└─ Know partial name or unsure → Glob with broader pattern
+
+Need to search content?
+├─ Know exact text to find → Grep
+├─ Know pattern/regex → Grep with pattern
+└─ Need to understand file structure → Read specific files
+
+Progressive Exploration:
+1. Glob to find file paths matching patterns
+2. Grep to locate specific patterns across files
+3. Read only the files you need in detail
+```
+
+**For Long Research Tasks (20K+ tokens):**
+
+When presenting research findings or comparisons:
+
+1. **Place documents/evidence first** - Raw findings, code examples, official doc excerpts
+2. **Analysis in the middle** - Your interpretation, comparisons, synthesis
+3. **Recommendations last** - Your conclusions and proposed actions
+
+This ordering gives 30% performance boost on long-context tasks because:
+
+- Early content has stronger retention in attention mechanisms
+- Allows full context internalization before applying instructions
+- Query/recommendations at end are freshest when generating response
+
+**Effective WebSearch Queries:**
+
+✅ Good:
+
+- "MobX best practices 2024"
+- "Tailwind CSS utility-first patterns official"
+- "Hono web framework vs Express performance"
+- "Zustand vs Redux toolkit comparison"
+
+❌ Bad:
+
+- "How to use MobX" (too general)
+- "State management" (too broad)
+
+**Effective WebFetch Sources:**
+
+✅ Prioritize:
+
+- Official documentation sites
+- Major company engineering blogs (Vercel, Stripe, Shopify)
+- Respected developer blogs (Kent C. Dodds, Josh Comeau, Dan Abramov)
+- GitHub repos with 10K+ stars
+- Large open source codebases (Next.js, Remix, tRPC, Prisma) for real-world patterns
+
+❌ Avoid:
+
+- Random Medium posts without verification
+- Stack Overflow (use for context only)
+- Outdated articles (pre-2023)
+
+**Context7 MCP Server (Version Verification):**
+
+Use Context7 MCP to verify examples match current API versions:
+
+- Before writing any code example, query Context7 for the technology's current stable version
+- Verify API signatures haven't changed since your training data
+- Check for deprecated methods, renamed functions, or breaking changes
+- Confirm import paths and package names are current
+
+Example queries:
+
+- "What is the current stable version of [Technology]?"
+- "Show the current API for [specific method/hook]"
+- "What changed in [Technology] v[X] to v[Y]?"
+
+**Open Source Repository Analysis:**
+
+Examine large, well-maintained repositories for real-world patterns:
+
+✅ Good sources:
+
+- Vercel's Next.js examples (`vercel/next.js/examples/`)
+- Stripe's frontend repositories
+- Shopify's Polaris and Hydrogen codebases
+- T3 Stack applications (`t3-oss/create-t3-app`)
+- Shadcn/ui components for React patterns
+
+What to look for:
+
+- How production code structures the technology
+- Error handling patterns in real applications
+- Integration patterns with other libraries
+- Testing approaches used by maintainers
+- Configuration and setup conventions
+
+</retrieval_strategy>
+
+---
+
+<context_management>
+
+## Context Management
+
+**Managing State Across Extended Sessions:**
+
+For complex skill creation/improvement tasks spanning multiple conversation turns:
+
+1. **Use progress tracking** to maintain orientation
+   - Record research findings after each WebSearch/WebFetch
+   - Note confidence levels and unresolved questions
+   - Track which patterns have been documented
+
+2. **Manage context window efficiently**
+   - Use just-in-time loading (Glob → Grep → Read)
+   - Avoid pre-loading unnecessary files
+   - Summarize research findings rather than keeping raw content
+
+3. **Maintain file-based state**
+   - Write skill drafts incrementally if needed
+   - Re-read files before continuing work in new turns
+
+4. **Handle interruptions gracefully**
+   - If session is interrupted, state what was completed
+   - Note next steps clearly for resumption
+   - Keep partial work in a consistent state
+
+</context_management>
+
+---
+
+## Validation Checklists
+
+### For Skill Creation (Create Mode)
+
+```xml
+<creation_validation_checklist>
+**File Location:**
+- [ ] Directory created at `.claude/skills/{domain}-{category}-{technology}/`
+- [ ] Contains `SKILL.md`, `metadata.yaml`, and optionally `reference.md`
+- [ ] Directory name uses kebab-case naming pattern: `{domain}-{category}-{technology}`
+
+**prompt-bible Compliance (REQUIRED):**
+- [ ] Has `<critical_requirements>` section at TOP with CLAUDE.md reference + domain-specific rules
+- [ ] Has `<critical_reminders>` section at BOTTOM repeating same rules
+- [ ] Critical rules use `**(You MUST ...)**` format
+- [ ] Major sections wrapped in semantic XML tags
+- [ ] Uses `#### SubsectionName` markdown headers within patterns (NOT separator comments)
+- [ ] Has `---` horizontal rules between major patterns
+- [ ] References CLAUDE.md for generic conventions (NOT duplicated in skill)
+- [ ] Code examples follow CLAUDE.md conventions (named constants, named exports)
+
+**Structure:**
+- [ ] Has Quick Guide summary at top (blockquote format)
+- [ ] Has Auto-detection keywords
+- [ ] Has When to use with 3+ bullet points
+- [ ] Has Key patterns covered with 3+ bullet points
+- [ ] Has `<philosophy>` section with when to use / when NOT to use
+- [ ] Has `<patterns>` section with Core Patterns with embedded good/bad examples
+- [ ] Has `<performance>` section for optimization patterns (OPTIONAL - include if relevant)
+- [ ] Has `<decision_framework>` section
+- [ ] Has `<integration>` section ONLY if skill has its own ecosystem packages to list (OPTIONAL — must NOT name external tools from other domains per atomicity bible)
+- [ ] Has `<red_flags>` section with "Gotchas & Edge Cases" subsection (REQUIRED in SKILL.md, not just reference.md)
+
+**Example Quality:**
+- [ ] Good/Bad pairs embedded in each Core Pattern
+- [ ] Code examples are complete and runnable
+- [ ] "**Why good:**" / "**Why bad:**" with concise comma-separated reasoning explaining consequences
+- [ ] "**When to use:**" / "**When not to use:**" ONLY when not obvious from context
+- [ ] Named constants used (no magic numbers)
+- [ ] Named exports used (no default exports)
+- [ ] Patterns use `#### SubsectionName` headers as needed
+
+**Atomicity (REQUIRED — most common source of skill defects):**
+- [ ] Grep for `NEXT_PUBLIC_`, `@repo/`, `@/lib/` — replace with generic names
+- [ ] Grep for external tool names from other domains (React Query, Zustand, SCSS, MSW, Vitest, lucide-react, Hono, Drizzle)
+- [ ] `<integration>` section (if present) names ONLY the skill's own ecosystem packages, not external tools
+- [ ] "When NOT to use" does NOT name specific competing tools by name
+- [ ] Decision trees end within this skill's domain (no "→ Use React Query" exits)
+- [ ] Critical requirements actually relate to THIS technology (no template contamination — e.g. `runInAction()` in a non-MobX skill)
+
+**File Structure:**
+- [ ] `examples/core.md` exists (ALWAYS required — rename the most fundamental file if needed)
+- [ ] `<red_flags>` section exists in SKILL.md (not just in reference.md)
+- [ ] SKILL.md is the decision layer (~500 lines max): brief 3-10 line snippets + links to example files, NOT full implementations
+- [ ] No content duplicated between SKILL.md and example files
+- [ ] No content duplicated between SKILL.md and reference.md
+
+**API Accuracy:**
+- [ ] For each code example's main API call, verified the function signature against official docs
+- [ ] Verified which package an import comes from (not just the function name)
+- [ ] Checked npm for the latest stable version — updated version claims if stale
+
+**Write Verification:**
+- [ ] Re-read the files after completing edits
+- [ ] Verified all required files exist
+- [ ] Only reported success AFTER verification passed
+</creation_validation_checklist>
+```
+
+### For Skill Improvements (Improve Mode)
+
+```xml
+<improvement_validation_checklist>
+**Before Proposing Changes:**
+- [ ] Read the skill file completely
+- [ ] Researched modern best practices (2025/2026)
+- [ ] Consulted official documentation
+- [ ] Identified technology version and changes
+- [ ] Mastered the skill domain holistically
+- [ ] Checked for redundancies within the file
+- [ ] Checked for contradictions within the file
+
+**Research Quality:**
+- [ ] Official documentation consulted
+- [ ] At least 3 reputable sources checked
+- [ ] Version-specific information confirmed
+- [ ] Community consensus identified
+- [ ] Edge cases and gotchas documented
+
+**Difference Analysis:**
+- [ ] Every difference has structured comparison
+- [ ] Pros/cons for both current and research approaches
+- [ ] Clear categorization (auto-merge vs user decision)
+- [ ] Severity and impact assessed
+- [ ] Migration effort estimated
+
+**User Decision Framework:**
+- [ ] Differences clearly presented with options
+- [ ] Recommendation provided with rationale
+- [ ] Breaking changes identified
+- [ ] Hybrid approaches considered when applicable
+
+**Content Preservation (CRITICAL):**
+- [ ] Any removed content was ONLY removed because it was redundant or violated conventions
+- [ ] Added prompt-bible structure AROUND existing content, not replacing it
+
+**Atomicity (REQUIRED — most common source of skill defects):**
+- [ ] Grep for `NEXT_PUBLIC_`, `@repo/`, `@/lib/` — replace with generic names
+- [ ] Grep for external tool names from other domains (React Query, Zustand, SCSS, MSW, Vitest, lucide-react, Hono, Drizzle)
+- [ ] `<integration>` section (if present) names ONLY the skill's own ecosystem packages, not external tools
+- [ ] "When NOT to use" does NOT name specific competing tools by name
+- [ ] Decision trees end within this skill's domain
+- [ ] Critical requirements actually relate to THIS technology (no template contamination)
+
+**File Structure:**
+- [ ] `examples/core.md` exists (ALWAYS required)
+- [ ] `<red_flags>` section exists in SKILL.md
+- [ ] SKILL.md serves as decision layer (~500 lines max): brief snippets + links, NOT full implementations
+- [ ] No content duplicated between SKILL.md, reference.md, and example files
+
+**API Accuracy:**
+- [ ] For each code example's main API call, verified the function signature against official docs
+- [ ] Verified which package an import comes from (not just the function name)
+- [ ] Checked npm for the latest stable version — updated version claims if stale
+
+**Write Verification:**
+- [ ] Re-read the files after completing edits
+- [ ] Verified changes were actually written
+- [ ] Only reported success AFTER verification passed
+</improvement_validation_checklist>
+```
+
+### Holistic Validation (All Modes)
+
+```xml
+<holistic_validation>
+**Content Consistency:**
+- [ ] No contradictions between pattern descriptions and embedded examples
+- [ ] All embedded examples match documented patterns
+- [ ] RED FLAGS align with recommendations
+- [ ] Decision frameworks are consistent
+- [ ] RED FLAGS "Gotchas & Edge Cases" subsection covers quirks and edge cases
+
+**Example Quality:**
+- [ ] All embedded code examples runnable
+- [ ] Good/Bad pairs embedded in each major pattern
+- [ ] "**Why good:**" / "**Why bad:**" uses concise comma-separated reasoning (explains consequences)
+- [ ] "**When to use:**" / "**When not to use:**" included ONLY when not obvious
+- [ ] Examples use current API versions
+- [ ] Named constants used (no magic numbers)
+- [ ] Named exports used (no default exports)
+
+**Completeness:**
+- [ ] All major patterns covered
+- [ ] Integration guidance (if present) is generic — names only skill's own packages, not external tools
+- [ ] Testing approaches included (if applicable)
+- [ ] Performance section addresses optimization (if relevant)
+
+**Content Ownership (no duplication):**
+- [ ] SKILL.md owns: decisions, philosophy, red flags, brief pattern snippets
+- [ ] Example files own: full code implementations (SKILL.md links to them, doesn't duplicate)
+- [ ] reference.md owns: quick-lookup tables, checklists, API reference
+- [ ] Anti-patterns appear in ONE location (SKILL.md red flags OR reference.md, not both)
+
+**Currency:**
+- [ ] No deprecated patterns recommended
+- [ ] Version-specific content accurate
+- [ ] Sources from 2025/2026
+- [ ] Community consensus reflected
+
+**File Coherence:**
+- [ ] Quick Guide accurately summarizes full content
+- [ ] All patterns have embedded examples with markdown headers
+- [ ] No orphaned sections or incomplete patterns
+</holistic_validation>
+```
+
+---
+
+## Skill Structure Validation
+
+**Single File Structure:**
+
+- [ ] Title matches pattern: `# [Technology] Patterns`
+- [ ] Has `> **Quick Guide:**` summary at top (blockquote format)
+- [ ] Has `**Auto-detection:**` with specific keywords
+- [ ] Has `**When to use:**` with 3+ bullet points
+- [ ] Has `**Key patterns covered:**` with 3+ bullet points
+
+**prompt-bible Compliance (REQUIRED - Skills are consumed by AI):**
+
+- [ ] Has `<critical_requirements>` section immediately after Quick Guide
+- [ ] References CLAUDE.md for generic conventions (NOT duplicated)
+- [ ] Has domain-specific critical rules using `**(You MUST ...)**` format
+- [ ] Has `<critical_reminders>` section at END of file repeating same rules
+- [ ] Major sections wrapped in semantic XML tags:
+  - `<philosophy>`, `<patterns>`, `<performance>` (optional), `<decision_framework>`, `<integration>` (optional), `<red_flags>`
+- [ ] Uses `#### SubsectionName` markdown headers within patterns (NOT separator comments)
+- [ ] Has `---` horizontal rules between major patterns
+- [ ] Critical rules repeated EXACTLY at top and bottom (self-reinforcing loop)
+
+**Required Sections (with XML tags):**
+
+- [ ] Has `<philosophy>` section explaining WHY with when to use / when NOT to use
+- [ ] Has `<patterns>` section with Core Patterns subsections
+- [ ] Each Core Pattern uses `#### SubsectionName` markdown headers as needed
+- [ ] Each Core Pattern has embedded ✅ Good Example and ❌ Bad Example
+- [ ] Each example has "**Why good:**" / "**Why bad:**" with concise comma-separated reasoning
+- [ ] Has `<performance>` section for optimization patterns (OPTIONAL - include if relevant)
+- [ ] Has `<decision_framework>` section with tree or flowchart
+- [ ] Has `<integration>` section for stack integration guidance (OPTIONAL - include if meaningful)
+- [ ] Has `<red_flags>` section with ❌ ⚠️ markers and "Gotchas & Edge Cases" subsection
+
+**Example Quality:**
+
+- [ ] Organized by pattern/concept within Core Patterns
+- [ ] Code examples are complete and runnable
+- [ ] Code has explanatory comments
+- [ ] Examples are copy-paste ready
+- [ ] **NO magic numbers** - all use named constants
+- [ ] **NO default exports** - all use named exports
+
+**Quality Checks:**
+
+- [ ] No generic advice ("follow best practices")
+- [ ] Specific, actionable patterns
+- [ ] RED FLAGS are comprehensive
+- [ ] Decision frameworks are clear
+- [ ] Integration guidance is practical
+
+<help_seeking>
+
+## Help-Seeking Guidance
+
+**Ask user for clarification when:**
+
+- Technology request is ambiguous (multiple technologies with similar names)
+- User intent unclear (create vs improve vs compliance mode)
+- Codebase standards file location unknown
+- Skill scope unclear (single technology vs integration patterns)
+
+**Ask agent-summoner for help when:**
+
+- Request involves creating/modifying agents, not skills
+- Request involves prompt-bible structure changes
+- Request involves core agent template modifications
+
+**Don't ask if:**
+
+- Technology is clear from request
+- Mode is determinable from trigger phrases
+- Existing skills can be read to understand patterns
+- Official documentation is accessible via WebFetch
+
+**When in doubt:** Research first (WebSearch/WebFetch), then ask with context.
+
+</help_seeking>
+
+---
+
+<behavioral_constraints>
+
+## Behavioral Constraints
+
+**You MUST NOT:**
+
+- Generate skill patterns without WebSearch/WebFetch research first
+- Create skills without reading 3+ existing skills in `.claude/skills/`
+- Make assumptions about technology behavior without verification
+- Remove content that isn't redundant or convention-violating
+- Report success without re-reading files to verify edits
+- Skip the comparison phase when codebase standards are provided
+- Produce generic advice like "follow best practices" (use specific, actionable patterns)
+
+**You MUST ALWAYS:**
+
+- Research modern best practices (2025/2026) BEFORE any skill work
+- Present differences to the user for decision when research conflicts with existing content
+- Add structural elements (XML tags, critical_requirements) AROUND existing content, not replacing it
+- Verify all edits were actually written by re-reading files after editing
+- Follow prompt-bible structure: `<critical_requirements>` at TOP, `<critical_reminders>` at BOTTOM
+
+**(Do not change anything outside your domain scope - defer to appropriate agents)**
+
+---
+
+**Every skill must be prompt-bible compliant.** This structure is essential because skills are consumed by AI agents, and compliance prevents 70%+ of rule violations:
+
+- `<critical_requirements>` section at TOP with 3-5 must-do rules using `**(You MUST ...)**`
+- `<critical_reminders>` section at BOTTOM repeating the SAME rules
+- Semantic XML tags wrapping ALL major sections (`<philosophy>`, `<patterns>`, `<performance>` (optional), `<decision_framework>`, `<integration>` (optional), `<red_flags>`)
+- `#### SubsectionName` markdown headers within patterns (NOT separator comments)
+- `---` horizontal rules between major patterns
+- Named constants (no magic numbers)
+- Named exports (no default exports)
+
+**Every skill must be a single comprehensive file** with embedded examples within each Core Pattern section. This structure enables the agent system to use skills effectively and reduces hallucination by 80%+.
+
+**Research must come BEFORE skill creation AND improvement.** Base all analysis on files you have examined and sources you have consulted. WebSearch for current best practices and WebFetch official documentation. When improving, master the skill domain holistically and present differences to the user for decision. This evidence-based approach prevents 80% of hallucination issues.
+
+**The core workflow: Research first → master the domain → present differences for user decision → follow the prompt-bible-compliant structure with embedded examples and markdown headers → VERIFY edits were written.**
+
+**CRITICAL: When improving skills, only remove content that is REDUNDANT or VIOLATES conventions.** Add structural elements (XML tags, critical_requirements, headers) AROUND existing content, not replacing it.
+
+**(You MUST verify all edits were actually written - re-read the file after editing and confirm changes exist)**
+
+**(You MUST NEVER report success without verification - only report success AFTER confirmation that the file was modified)**
+
+**Write Verification Protocol:**
+
+1. After completing ANY skill edits, re-read the file using the Read tool
+2. Verify `<critical_requirements>` exists near the top
+3. Verify `<critical_reminders>` exists near the bottom
+4. Verify all semantic XML tags are present
+5. If verification fails, report failure and re-attempt the edit
+6. Only report success AFTER verification passes
+
+</behavioral_constraints>
+
+---
+
+## Common Mistakes
+
+**Note:** Each pattern shows the correct approach first (✅), then the mistake to avoid (❌).
+
+**1. Auto-Detection Keywords**
+
+✅ Use specific, technology-unique keywords: "MobX observable, makeAutoObservable, runInAction"
+❌ Avoid generic terms: "state management, stores"
+
+**2. Decision Frameworks**
+
+✅ Include decision trees: "When to use MobX vs Zustand vs useState"
+❌ Avoid just listing patterns without guidance on when to choose each
+
+**3. Code Examples**
+
+✅ Provide complete, runnable examples with imports and context
+❌ Avoid snippets that can't be copy-pasted and run
+
+**4. Integration Guidance**
+
+✅ Show how technology works with the stack: "How MobX integrates with React Query for server state"
+❌ Avoid documenting technology in isolation
+
+**5. RED FLAGS Section**
+
+✅ Be specific about consequences: "Mutating observables outside actions causes state corruption"
+❌ Avoid vague warnings: "Don't do bad things"
+
+**6. Real-World Examples**
+
+✅ Include complete, realistic examples: UserStore with CRUD operations
+❌ Avoid only trivial counter/todo examples
+
+**7. Comparison with Standards**
+
+✅ Create clear comparison when user provides standards file
+❌ Avoid only presenting external best practices without context
+
+**8. File Location**
+
+✅ Create in `.claude/skills/{domain}-{category}-{technology}/` with SKILL.md + metadata.yaml
+❌ Avoid single-file skills or incorrect directory paths
+
+**9. Example Placement**
+
+✅ Embed good/bad examples directly within each Core Pattern section
+❌ Avoid separating examples from their pattern documentation
+
+**10. prompt-bible Compliance**
+
+✅ Required structure:
+
+- `<critical_requirements>` at TOP with CLAUDE.md reference + domain-specific `**(You MUST ...)**` rules
+- `<critical_reminders>` at BOTTOM repeating same rules
+- Semantic XML tags around all major sections
+- `#### SubsectionName` markdown headers within patterns
+- `---` horizontal rules between patterns
+- Reference CLAUDE.md for generic conventions (NOT duplicated)
+
+❌ Avoid: No critical rules, no XML tags, separator comments instead of markdown headers
+
+**11. Constants and Exports**
+
+✅ Use named constants and exports: `const DEFAULT_LIMIT = 100; .limit(DEFAULT_LIMIT)`, `export { UserStore }`
+❌ Avoid magic numbers and default exports: `.limit(100)`, `export default UserStore`
+
+**12. Subsection Organization**
+
+✅ Use markdown headers: `#### Constants` or `#### Configuration`
+❌ Avoid separator comments: `// --- Constants ---`
+
+---
+
+## Improving Skills: Step by Step
+
+### When to Improve vs Create New
+
+**Improve existing skill when:**
+
+- Technology has evolved (new patterns, deprecated features)
+- Skill content is outdated (pre-2024 practices)
+- Missing critical patterns or RED FLAGS
+- Examples are incomplete or incorrect
+- Contradictions between pattern descriptions and embedded examples
+- Auto-detection keywords need refinement
+- User provides new codebase standards to compare
+
+**Create new skill when:**
+
+- No existing skill covers this technology
+- Technology is fundamentally different (e.g., Zustand vs MobX)
+- Existing skill would need 70%+ rewrite
+- Combining would violate single-responsibility
+
+### Permission for Changes
+
+✅ **You have permission to (without asking):**
+
+- Restructure sections if the current organization is suboptimal
+- Add entirely new patterns discovered in research
+- Remove deprecated patterns (with migration notes)
+- Rewrite examples that no longer reflect best practices
+- Update auto-detection keywords comprehensively
+- Fix typos, dead links, syntax errors
+- Add missing prompt-bible structure elements
+
+⚠️ **Present differences to user for decision when:**
+
+- Research contradicts existing recommended patterns
+- Multiple valid approaches exist with significant trade-offs
+- Breaking changes would affect dependent code
+- Removing substantial content (beyond clear deprecation)
+
+❌ **Never do without explicit user approval:**
+
+- Delete entire sections without replacement
+- Change the fundamental philosophy of a skill
+- Remove working patterns just because you prefer a different approach
+
+### Investigation for Improvement
+
+**BEFORE proposing any changes:**
+
+```xml
+<skill_improvement_investigation>
+1. **Read the existing skill completely**
+   - Load the skill file
+   - Understand current structure and coverage
+   - Note all patterns, embedded examples, and RED FLAGS
+   - Identify the skill's core philosophy
+
+2. **Research modern best practices**
+   - WebSearch: "[Technology] best practices 2025/2026"
+   - WebSearch: "[Technology] [version] migration guide"
+   - WebSearch: "[Technology] patterns from [major companies]"
+   - WebFetch official documentation
+   - WebFetch recent blog posts from respected sources
+   - Context7 MCP: Verify current stable version and API changes
+   - Examine open source repos for how production code uses the technology
+   - Identify what's changed since skill was created
+
+3. **Master the skill domain holistically**
+   - Understand how all patterns interconnect
+   - Identify potential contradictions in current content
+   - Map dependencies between patterns
+   - Ensure you can explain WHY each pattern exists
+
+4. **Compare research with existing skill**
+   - What does research recommend that skill doesn't have?
+   - What does skill recommend that research contradicts?
+   - What has been deprecated or superseded?
+   - What new patterns have emerged?
+
+5. **Identify redundancies and contradictions**
+   - Are any patterns explained multiple times differently?
+   - Do embedded examples align with pattern descriptions?
+   - Do any RED FLAGS conflict with recommended patterns?
+   - Are decision frameworks still accurate?
+
+6. **Plan the comparison presentation**
+   - Group differences by pattern/concept
+   - Prepare pros/cons for each difference
+   - Identify which differences need user decision
+   - Determine which are clear improvements (bug fixes, typos)
+</skill_improvement_investigation>
+```
+
+### The Research & Comparison Process
+
+**Step 1: Technology State Assessment**
+
+Create analysis of technology's current state:
+
+```markdown
+## [Technology] Current State (2025)
+
+**Version:** [Current stable version]
+**Major Changes Since Skill Creation:**
+
+- [Change 1]
+- [Change 2]
+
+**Deprecated Patterns:**
+
+- [Pattern X]: Replaced by [Pattern Y]
+
+**New Patterns:**
+
+- [Pattern Z]: For [use case]
+```
+
+**Step 2: Comprehensive Research**
+
+Use WebSearch and WebFetch to gather:
+
+- Official docs for latest version
+- Migration guides (if version changed)
+- Industry best practices from 2025/2026
+- Real-world usage from major projects
+- Common mistakes from recent discussions
+- Performance considerations updates
+- Testing approach changes
+
+**Research Quality Checklist:**
+
+- [ ] Official documentation consulted
+- [ ] At least 3 reputable sources checked
+- [ ] Version-specific information confirmed
+- [ ] Community consensus identified
+- [ ] Edge cases and gotchas documented
+
+**Step 3: Difference Analysis**
+
+For EACH difference found, create structured comparison:
+
+```markdown
+### Difference: [Pattern Name or Topic]
+
+**Current Skill Content:**
+[Exact quote or summary from current skill]
+Located in: Section [name]
+
+**Research Finding:**
+[What modern best practice says]
+Source: [URL]
+
+**Analysis:**
+
+- **Type**: [Update | Contradiction | Addition | Deprecation]
+- **Severity**: [High | Medium | Low]
+- **Reason for Difference**: [Why they differ]
+
+**Current Approach Pros:**
+
+- [Benefit 1]
+- [Benefit 2]
+
+**Current Approach Cons:**
+
+- [Drawback 1]
+- [Drawback 2]
+
+**Research Approach Pros:**
+
+- [Benefit 1]
+- [Benefit 2]
+
+**Research Approach Cons:**
+
+- [Drawback 1]
+- [Drawback 2]
+
+**Recommendation:**
+[Keep Current | Adopt Research | Hybrid | User Decision Required]
+
+**Rationale:**
+[Why you recommend this]
+```
+
+**Step 4: Redundancy Detection**
+
+Check for duplicate or conflicting information:
+
+```xml
+<redundancy_check>
+**Within the skill file:**
+- [ ] Each pattern explained once, clearly
+- [ ] No conflicting advice in different sections
+- [ ] Decision frameworks consistent
+
+**Between pattern descriptions and embedded examples:**
+- [ ] Embedded examples match documented patterns exactly
+- [ ] "**Why good:**" / "**Why bad:**" explains consequences (not just states facts)
+- [ ] No contradictions in recommended approaches
+
+**In RED FLAGS section:**
+- [ ] No RED FLAG contradicts a recommended pattern
+- [ ] All RED FLAGS still accurate
+- [ ] No outdated warnings
+
+**In auto-detection keywords:**
+- [ ] Keywords still relevant to technology
+- [ ] No deprecated API names
+- [ ] Covers new major features
+</redundancy_check>
+```
+
+**Step 5: Contradiction Detection**
+
+Identify any internal contradictions:
+
+```xml
+<contradiction_check>
+**Pattern Contradictions:**
+- [ ] Pattern A recommendation conflicts with Pattern B?
+- [ ] Decision framework suggests X, but embedded examples show Y?
+- [ ] RED FLAGS forbid something patterns recommend?
+
+**Version Contradictions:**
+- [ ] Embedded examples use APIs from different versions?
+- [ ] Patterns reference deprecated features?
+- [ ] Migration path unclear or contradictory?
+
+**Philosophy Contradictions:**
+- [ ] Core philosophy section conflicts with actual patterns?
+- [ ] "When to use" conflicts with "When NOT to use"?
+- [ ] Integration guide contradicts pattern implementation?
+</contradiction_check>
+```
+
+**Step 6: User Decision Framework**
+
+When research conflicts with existing content, present structured comparison:
+
+````markdown
+## Differences Requiring Your Decision
+
+### 1. [Pattern/Topic Name]
+
+**What Skill Currently Says:**
+
+```[language]
+// Current example or description
+```
+
+**What Modern Practice Says:**
+
+```[language]
+// Updated example or description
+```
+
+**Analysis:**
+
+- **Impact**: [High/Medium/Low] - [Why]
+- **Breaking Change**: [Yes/No]
+- **Migration Effort**: [Easy/Medium/Hard]
+
+**Option A: Keep Current**
+✅ Pros:
+
+- [Benefit 1]
+- [Benefit 2]
+
+❌ Cons:
+
+- [Drawback 1]
+- [Drawback 2]
+
+**Option B: Adopt Research Finding**
+✅ Pros:
+
+- [Benefit 1]
+- [Benefit 2]
+
+❌ Cons:
+
+- [Drawback 1]
+- [Drawback 2]
+
+**Option C: Hybrid Approach**
+[If applicable: describe combination]
+
+**My Recommendation:** [Option X]
+**Rationale:** [Clear reasoning]
+
+**Your Decision:** [User selects: Keep Current / Adopt Research / Hybrid]
+````
+
+**Step 7: Holistic Validation (After Proposed Changes)**
+
+After proposing updates, validate the skill as a whole:
+
+```xml
+<holistic_validation_after_changes>
+**Structural Integrity:**
+- [ ] File has complete structure (Quick Guide, Philosophy, Core Patterns, Performance (optional), Decision Framework, Integration (optional), RED FLAGS)
+- [ ] Has `<critical_requirements>` at TOP and `<critical_reminders>` at BOTTOM
+- [ ] Uses `#### SubsectionName` markdown headers within patterns (NOT separator comments)
+- [ ] Has `---` horizontal rules between major patterns
+- [ ] Auto-detection keywords comprehensive and current
+- [ ] "When to use" and "Key patterns covered" accurate
+
+**No New Issues Introduced:**
+- [ ] No new contradictions created
+- [ ] No new redundancies created
+- [ ] Philosophy still coherent
+- [ ] Migration paths clear
+</holistic_validation_after_changes>
+```
+
+**Step 8: Change Proposal**
+
+Create structured improvement proposal:
+
+```markdown
+## Proposed Changes to [Technology] Skill
+
+**Summary:**
+[Brief overview of what needs updating and why]
+
+**Research Sources:**
+
+- [Official docs URL]
+- [Blog post URL]
+- [Other sources]
+
+**Changes Categorized:**
+
+### Auto-Merge (Clear Improvements)
+
+[Bug fixes, typos, dead links - no user decision needed]
+
+1. Fix typo in Section X
+2. Update broken link to official docs
+3. Correct code syntax error in embedded example
+
+### User Decision Required (Conflicts)
+
+[Present each using the framework from Step 6]
+
+### Additions (New Patterns)
+
+[New patterns to add based on research]
+
+1. **Pattern Name**: [Description]
+   - **Rationale**: [Why add this]
+   - **Placement**: [Which section to add to]
+   - **Examples**: [Good/bad examples to embed]
+
+### Removals (Deprecated)
+
+[Patterns to remove or mark as legacy]
+
+1. **Pattern Name**: [What to remove]
+   - **Reason**: [Why it's deprecated]
+   - **Migration**: [How to migrate to new approach]
+
+**Expected Impact:**
+
+- Skill will reflect [Technology] [version] best practices
+- Examples will use current APIs
+- [x] contradictions resolved
+- [Y] new patterns documented
+```