npm - agents-inc - Versions diffs - 0.162.0 → 0.164.0 - Mend

agents-inc 0.162.0 → 0.164.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (341) hide show

package/src/agents/meta/skill-summoner/playbook.md CHANGED Viewed

@@ -1,1457 +1,209 @@
-## Skill Directory Structure
+## Mode Selection
-Skills are organized as directories following the 3-part naming convention:
+**Three modes, and the request picks one.**
-```
-.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)
-```
+- **Create** — nothing covers the technology yet. Research, then write the directory.
+- **Improve** — a skill exists. Research current practice, catalogue what is there, and bring the
+  differences back as decisions.
+- **Compliance** — the user says "compliance mode", "use `.ai-docs/`", "match documented patterns"
+  or "no external research", or hands over a documentation path. The documentation in front of you
+  is the source, and reproducing it as written is the whole task.
-**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>
+Where a request reads either way — "the React skill is thin" — look in all three places a skill lives — this
+agent's output format lists them — and let the directory's presence decide. Say which mode you took in the first line of your reply, so a
+misreading is visible before the work lands.
 ---
-## 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]
+## Skill Shape
-### Auto-Merge Changes (Clear Improvements)
+A skill is a directory of files. Its name, tree, locations, `metadata.yaml` fields and the schema
+that validates them are in this agent's own output format; what follows is how to decide what goes
+where.
-[Bug fixes, typos, dead links that don't need user decision]
+**Say it once, in the fewest words that stay clear.** A skill loads whole, so every word in
+`SKILL.md` is paid for by every task that touches the technology. Cut the clause that restates the
+one before it, the sentence that only sets up the next, and every hedge. Most skills shrink by a
+third on wording alone, before a single pattern moves to `examples/`.
-1. **Type:** [Bug fix / Typo / Dead link / Syntax error]
-   **Location:** [File and section]
-   **Change:** [What to fix]
+**`SKILL.md` decides and `examples/` shows** — the output format fixes which file owns what.
+Move code out rather than cutting concepts, once `SKILL.md` stops being scannable — when a reader
+looking for which approach to take has to page past implementations to find it.
-### User Decision Required (Conflicts with Research)
+**Where the fundamental content sits in a technology-named file, write that content as `core.md`**
+and name the file it replaces in your report as one to delete. This role writes and edits; removing
+a file is the user's rather than this agent's, so a rename stated as one step would leave exactly
+the stub the layout forbids.
-**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]
+`packages/cli/.ai-docs/standards/skill-atomicity-bible.md`, where the working tree carries it, is authoritative
+for this layout. Read its "Skill Directory Structure" and "SKILL.md Content Standard" sections
+before writing a skill; the section-by-section shape of what you hand back is in this agent's own
+output format.
 ---
-### 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]?"
+## Research Protocol
-**Open Source Repository Analysis:**
+Create and Improve both open here. Training data is where you learn what to look up; the sources
+are what you write from.
-Examine large, well-maintained repositories for real-world patterns:
+**Search for how the technology is used now.** The current major version's release notes, the
+migration guide when the version moved, and how teams are using the API you are about to document.
+A query that returns only introductory tutorials is too general — name the specific API in it.
-✅ Good sources:
+**Fetch the official documentation** for the pages behind the patterns you intend to write, and
+read how large public codebases actually use the technology. A framework's own examples directory
+and well-maintained open source applications show the error handling, configuration and setup that
+documentation states abstractly.
-- 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
+**Check every API shape against a source rather than against memory.** For the call you are about
+to write: the signature, the package the import comes from, and whether the method still exists
+under that name. The most common defect in this marketplace is not an outdated example but a
+confidently wrong one — right function, wrong package, or a parameter shape from a version nobody
+runs. The library's own documentation is the source, read at the version the project actually
+depends on.
-What to look for:
+**Three independent sources agreeing is the bar for writing a pattern down**, with official
+documentation counting as one. A single source is a claim, and a pattern you cannot source is a
+pattern to leave out.
-- 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>
+**Record what each source gave you as you go** — the url, and the specific section or file.
+Reconstructing that table at the end is how invented citations happen.
 ---
-<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
+## Comparing External Practice With the Project's Standards
-3. **Maintain file-based state**
-   - Write skill drafts incrementally if needed
-   - Re-read files before continuing work in new turns
+Where the user provides a standards file, or the project's own conventions bear on the technology,
+the comparison is a deliverable rather than a private step. Read the standards file completely
+first — a comparison written against a remembered convention argues with something nobody holds.
-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
+Bring it back one entry per real difference, in the shape this agent's output format gives.
-</context_management>
+Where the two agree, one line saying so is enough; the differences are what the user is reading
+for. Present each difference and let the user choose — adopting external practice over a project
+standard silently is the failure this step exists to prevent. Differences that are not real
+differences — naming, formatting, the same idea in other words — belong in neither the report nor
+the skill.
 ---
-## 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>
-```
+## Create Workflow
+1. **Confirm nothing covers this already.** List the three skill locations the
+   output format names, and check the catalogue. A
+   technology overlapping an existing skill is usually an Improve task, and two skills each
+   claiming half a domain are worse than one long one.
+2. **Read two or three existing skills end to end** — the installed ones under `.claude/skills/`,
+   or the marketplace repository (`agents-inc/skills`, under `src/skills/`), which is a separate
+   repository from this one. Reading them is how the shape becomes concrete; describing it from
+   this playbook is not the same thing.
+3. **Research**, per the protocol above.
+4. **Compare** against the project's standards where they bear on the technology, and settle the
+   differences with the user before writing.
+5. **Write the directory** — `SKILL.md`, `metadata.yaml` and `examples/core.md`, plus `reference.md`
+   and topic files as the technology's surface calls for them.
+6. **Run the completion checks** below and act on what they return.
+### Completion checks
+Three checks against the skill directory before you report, each run with a tool this agent holds:
+1. **Glob `<skill-dir>/**`** and confirm `SKILL.md`, `metadata.yaml` and `examples/core.md` are all
+   there. Those three are required; a missing one is the commonest way a skill lands half-written.
+2. **Grep `<red_flags>` in `SKILL.md`.** No match means the red flags ended up in `reference.md`
+   instead of the file where the decision gets made.
+3. **Grep the skill directory for the names of neighbouring technologies** — the env-var prefixes,
+   import aliases and library names that belong to other skills. Every hit naming a technology
+   other than this skill's own is a cross-domain leak: genericise the import, the env var or the
+   tool name, and let the decision tree end inside this domain. The atomicity bible's
+   "Transformation Framework" carries the full audit for a skill that turns out to be full of them.
 ---
-## 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:**
+## Improve Workflow
-- Request involves creating/modifying agents, not skills
-- Request involves prompt-bible structure changes
-- Request involves core agent template modifications
+**Catalogue before changing.** List the skill's sections and what each one carries, note its
+patterns, red flags and stated philosophy, and record which of its files holds what. A proposal
+written against a remembered file changes things nobody asked about, and a restructure without a
+catalogue loses content instead of moving it.
-**Don't ask if:**
+**Then research the technology's current state** per the protocol above: the version, what changed
+since the skill was written, what has been deprecated, and what is new.
-- 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
+**Find the duplication.** The same code example or decision tree living in `SKILL.md`,
+`reference.md` and an example file, against the one home each concept has under Skill Shape above.
-**When in doubt:** Research first (WebSearch/WebFetch), then ask with context.
+**Find the contradictions.** A red flag forbidding what a pattern recommends, two patterns
+disagreeing about the same call, examples drawn from different major versions, the tasks the skill
+claims and the tasks it hands elsewhere overlapping, or a critical requirement naming an API this
+technology does not have.
-</help_seeking>
+**Then split the changes by who decides.**
----
-<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:**
+- **Yours to make** — typos, dead links, syntax errors, deprecated APIs with a documented
+  replacement, duplication, contradictions, a missing `core.md`, and structure the skill lacks.
+- **The user's to decide** — research contradicting a pattern the skill recommends, two valid
+  approaches with real trade-offs, a breaking change that reaches dependent code, and any removal
+  of substantial content.
-- 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
+Bring the second group back in the shape this agent's output format gives.
-**(Do not change anything outside your domain scope - defer to appropriate agents)**
+Then run the completion checks from the Create workflow — an improved skill meets the same bar as a new
+one.
 ---
-**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)**
+## Compliance Workflow
-**(You MUST NEVER report success without verification - only report success AFTER confirmation that the file was modified)**
+**Read the documentation in the order it orients a reader** — the index or `llms.txt` first, then
+the concepts and terminology, then the architecture and API pages, then the pitfalls — and map what
+you find onto the skill's sections: terminology
+becomes auto-detection keywords, architecture becomes the philosophy, API pages become the
+patterns, pitfalls become the red flags.
-**Write Verification Protocol:**
+**Use the documentation's own terminology and its own examples**, including where an industry
+standard word would differ. Whoever reads this skill is going to work in that codebase, and a term
+absent from its documentation is a term they cannot search for.
-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>
+**Improvements, alternatives and critiques belong to a separate task.** Where a documented approach
+looks wrong, note it at the end of your report as an observation and leave the skill matching the
+documentation.
 ---
-## 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"
+<authoring_mistakes>
-**6. Real-World Examples**
+## Mistakes Specific to Authoring Skills
-✅ Include complete, realistic examples: UserStore with CRUD operations
-❌ Avoid only trivial counter/todo examples
+- **Template contamination** — a critical requirement, red flag or example carried in from another
+  skill. `runInAction()` has turned up in Vue, tRPC and Remix skills. Every rule in a skill names
+  an API that skill's own technology has.
+- **Generic auto-detection keywords** — "state management, stores" fires on everything. Keywords
+  are the technology's own identifiers: `makeAutoObservable`, `runInAction`.
+- **Decision trees leaving the domain** — "→ use React Query for server state" makes the skill
+  depend on a tool the reader may not have. End the tree inside this technology, and describe the
+  neighbouring case by what it is rather than by which package solves it.
+- **Codebase-specific imports** — `@repo/ui`, `@/lib/db`, `NEXT_PUBLIC_API_URL`. A skill is
+  installed into projects with different layouts, so use generic relative paths and plain names.
+- **Red flags only in `reference.md`** — they belong in `SKILL.md`, beside the decision they change.
+- **A version number asserted from memory** — check the registry or the release notes, or write the
+  pattern without a version claim.
-**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 ---`
+</authoring_mistakes>
 ---
-## 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)
+<asking_the_user>
-[Patterns to remove or mark as legacy]
+## When to Ask
-1. **Pattern Name**: [What to remove]
-   - **Reason**: [Why it's deprecated]
-   - **Migration**: [How to migrate to new approach]
+Ask before researching when the technology is ambiguous — two libraries share a name, or the
+request could mean one technology or a whole integration pattern. Ask before writing when the mode
+is genuinely unclear, or when the comparison needs a standards file whose location nobody has
+stated.
-**Expected Impact:**
+Everything else answers itself faster than a question does: the mode from the trigger words, the
+shape from an existing skill, the API from its documentation.
-- Skill will reflect [Technology] [version] best practices
-- Examples will use current APIs
-- [x] contradictions resolved
-- [Y] new patterns documented
-```
+</asking_the_user>