cc-dev-template 0.1.48 → 0.1.49

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-dev-template",
-  "version": "0.1.48",
+  "version": "0.1.49",
   "description": "Structured AI-assisted development framework for Claude Code",
   "bin": {
     "cc-dev-template": "./bin/install.js"

package/src/skills/creating-agent-skills/SKILL.md

@@ -1,54 +1,18 @@
 ---
 name: creating-agent-skills
-description: Expert guidance for creating, modifying, and auditing Claude Code skills. Use when the user asks to "create a skill", "build a new skill", "audit skills", "review my skills", "update a skill", "modify a skill", "improve a skill", or mentions skill development, SKILL.md files, or progressive disclosure.
+description: Expert guidance for creating and fixing Claude Code skills. Use when the user asks to "create a skill", "build a new skill", "fix a skill", "audit skills", "review my skills", "update a skill", "modify a skill", "improve a skill", or mentions skill development, SKILL.md files, or progressive disclosure.
 ---
 
 # Creating Agent Skills
 
 ## What To Do Now
 
-Ask what the user wants to do with skills.
+Ask the user what they need.
 
-Use `AskUserQuestion`:
-- **Create a new skill** - Build a skill through guided conversation
-- **Audit existing skills** - Review skills for best practices compliance
-- **Modify a skill** - Update or improve an existing skill
-- **Something else** - Free-form request
-
-## Route to Workflow
-
-Based on choice, read the appropriate workflow:
-
-| Choice | Action |
+| Intent | Action |
 |--------|--------|
-| Create | Read `references/create.md` |
-| Audit | Read `references/audit.md` |
-| Modify | Read `references/modify.md` |
-| Something else | Help find the right approach |
-
-## Essential Knowledge
-
-**A skill IS a prompt.** When activated, Claude reads SKILL.md. It must contain instructions, not documentation about the skill.
-
-**Progressive disclosure.** SKILL.md should be lean (<150 lines). Heavy content goes in references/. This keeps context efficient.
-
-**The test:** After reading SKILL.md, would Claude know what to DO? If it only knows what the skill is about, it's written wrong.
-
-For complete principles, workflows load `references/principles.md` as needed.
-
-## Quick Reference
-
-**Skill locations:**
-
-| Level | Path |
-|-------|------|
-| User | `~/.claude/skills/` |
-| Project | `.claude/skills/` |
-
-**Bundled scripts:**
-- `scripts/find-skills.js` - Discover all installed skills
-- `scripts/validate-skill.js` - Validate a skill's structure
-
-## Requirements
+| Create a new skill | Read `references/create-step-1-understand.md` |
+| Fix, improve, audit, or modify an existing skill | Read `references/fix-step-1-diagnose.md` |
 
-- Node.js (for validation scripts)
+If the user says "audit my skills", that is the fix path.
+If they mention a specific skill that needs changes, that is also the fix path.

package/src/skills/creating-agent-skills/references/create-step-1-understand.md

@@ -0,0 +1,42 @@
+# Step 1: Understand the Domain
+
+The skill's quality depends entirely on understanding the domain. Start a conversation with the user.
+
+## What To Uncover
+
+- **The task** they want to standardize — what do they do repeatedly that they want encoded?
+- **Domain knowledge** Claude does not naturally have — terminology, patterns, edge cases, gotchas
+- **Why certain approaches work** — not just what the steps are, but the reasoning behind them
+- **Concrete examples** of the task done well — ask for real examples or walk-throughs
+- **Common mistakes** people make when doing this task
+
+## How To Have This Conversation
+
+If the user already provided comprehensive context (a detailed spec, all the steps, domain knowledge), verify your understanding and move on — do not re-ask what they already answered. If the context is thin or ambiguous, have a real conversation.
+
+Ask one or two questions at a time. This should feel like a conversation, not a form.
+
+Good questions:
+- "Walk me through how you do this today."
+- "What's the most important thing to get right?"
+- "What mistakes do people commonly make?"
+- "What would an expert know that a beginner wouldn't?"
+- "Can you show me an example of this done well?"
+
+Ask follow-up questions. Dig into the WHY behind their answers. If they say "always do X before Y", ask why that order matters.
+
+## If the Task Is Non-Obvious
+
+If this is a domain where Claude would not naturally know how to proceed — research it. Look at examples. Try to figure out how you would approach the task yourself. The skill author needs to understand the domain, not just record what the user says.
+
+Use the Explore agent or web search if the domain requires knowledge you lack.
+
+## When To Move On
+
+Move on when all of these are true:
+- You can articulate what makes this task hard or nuanced
+- You have enough domain knowledge to write instructions a fresh Claude instance could follow
+- You understand WHY the approaches work, not just WHAT they are
+- The user confirms you understand their needs
+
+Read `references/create-step-2-design.md`.

package/src/skills/creating-agent-skills/references/create-step-2-design.md

@@ -0,0 +1,113 @@
+# Step 2: Design the Skill
+
+Based on what you learned in the conversation, design the skill's structure before writing anything.
+
+## Determine the Name
+
+- Hyphen-case: lowercase letters, numbers, and hyphens only
+- Prefer gerund form: `processing-pdfs`, `creating-reports`, `reviewing-code`
+- Must match the directory name
+- Max 64 characters
+
+## Determine the Skill Type
+
+There are two types. Pick one:
+
+**Informational** — A single SKILL.md file that captures knowledge, conventions, or best practices. No sequential workflow. The agent absorbs it and applies it to whatever it's doing. Example: a `prompting` skill that teaches how to write good prompts.
+
+**Procedural** — A chain of step files for a sequential process. SKILL.md routes to step 1. Step 1 chains to step 2. Each step file covers ONE phase. The agent only sees the current step. Example: a skill that downloads a video, transcribes it, formats it, and summarizes it — four distinct phases, four files.
+
+**How to decide:** If the skill describes a process with distinct sequential phases, it is procedural. If it captures principles or knowledge applied whenever relevant, it is informational.
+
+## Design the Frontmatter
+
+Every skill has YAML frontmatter. Required and optional fields:
+
+### Required
+
+| Field | Rules |
+|-------|-------|
+| `name` | Hyphen-case, matches directory name, max 64 chars |
+| `description` | Third person, quoted trigger phrases, WHEN to use not HOW it works, max 1024 chars |
+
+### Optional
+
+| Field | Purpose |
+|-------|---------|
+| `argument-hint` | Placeholder shown after slash command (e.g., `[issue-number]`, `[filename]`) |
+| `disable-model-invocation` | Set `true` to prevent Claude from auto-activating — use for side-effect workflows like deploy or commit |
+| `user-invocable` | Set `false` to hide from the `/` menu — use for background knowledge skills |
+| `allowed-tools` | Restrict which tools the skill can use (e.g., `Read, Grep, Glob` for read-only) |
+| `model` | Override the model used when this skill is active |
+| `context` | Set `fork` to run in an isolated sub-agent context |
+| `agent` | Sub-agent type when `context: fork` is set (`Explore`, `Plan`, `general-purpose`, or custom) |
+| `hooks` | Lifecycle hooks scoped to this skill |
+
+### String Substitutions Available in Skill Content
+
+| Syntax | What It Does |
+|--------|--------------|
+| `$ARGUMENTS` | Full argument string passed after `/skill-name` |
+| `$ARGUMENTS[N]` or `$N` | Positional argument (0-based) |
+| `${CLAUDE_SESSION_ID}` | Current session ID |
+| `` !`command` `` | Output of a shell command, injected at activation time before Claude sees the content |
+
+## Craft the Description
+
+The description determines when Claude activates the skill. This is the most important piece of metadata.
+
+Collect 5-10 trigger phrases from the user: "When you need this skill, what would you say to Claude?"
+
+Combine into a description that:
+- Uses third person: "This skill should be used when..."
+- Includes the actual trigger phrases in quotes
+- Focuses on WHEN to use, not HOW it works
+- Stays under 1024 characters
+
+**Key insight:** If the description explains too much about WHAT the skill does, Claude believes it already knows enough and will not activate. Keep it about WHEN.
+
+**Context budget note:** Skill descriptions load at startup and share a character budget (default 15,000 chars across all skills). Keep descriptions tight — they cost tokens every session.
+
+## Plan the File Layout
+
+**For informational skills:**
+```
+skill-name/
+└── SKILL.md
+```
+Optionally add `references/` for depth that is not always needed.
+
+**For procedural skills:**
+```
+skill-name/
+├── SKILL.md                    # Routes to step 1
+└── references/
+    ├── step-1-[name].md        # Chains to step 2
+    ├── step-2-[name].md        # Chains to step 3
+    └── step-3-[name].md        # Final step
+```
+
+**When to add `scripts/`:** Deterministic operations that need reliability — validation, code generation, file operations.
+
+**When to add `templates/`:** Boilerplate files that get copied or modified by the agent.
+
+## For Procedural Skills: Plan the Steps
+
+List out the steps. Each step becomes one markdown file in `references/`. For each step, determine:
+- What the agent does during this step
+- What signals the step is complete (the chain condition)
+- What the next step is
+
+## Confirm With the User
+
+Present the design:
+- Name
+- Type (informational or procedural)
+- Frontmatter configuration
+- Description text
+- File layout
+- For procedural: the step breakdown
+
+Ask: "Does this design look right?"
+
+Read `references/create-step-3-write.md` when the design is confirmed.

package/src/skills/creating-agent-skills/references/create-step-3-write.md

@@ -0,0 +1,177 @@
+# Step 3: Write the Skill
+
+Write the skill files based on the design from step 2. Everything in this file applies while writing.
+
+## The Fundamental Rule
+
+A skill IS a prompt. When Claude reads SKILL.md, it must know what to DO — not what the skill is about.
+
+**The test:** After writing each file, ask: "If Claude reads this right now, does it know what action to take?" If it would understand what the skill is about but not know what to do — rewrite it.
+
+## Writing Style
+
+### Instructions, Not Documentation
+
+Write as instructions. Imperative form.
+
+| Wrong | Right |
+|-------|-------|
+| "This skill parses PDF files" | "Parse the PDF file" |
+| "You should validate the input" | "Validate the input" |
+| "The next step involves formatting" | "Format the output" |
+
+Never describe what the skill IS. Tell Claude what to DO.
+
+### No Meta-Descriptions
+
+Remove any of these — they describe, they do not instruct:
+
+- "Who this is for:" — Claude does not need audience info
+- "Success looks like:" — describe outcomes through instructions, not meta-sections
+- "The purpose is..." — documentation language
+- "This skill orchestrates..." — describes what the skill IS
+- "Overview" or "Introduction" sections — get to the action
+
+### Positive Framing
+
+Tell Claude what TO do, not what NOT to do. Negatives require extra processing and can prime the unwanted behavior.
+
+| Negative | Positive |
+|----------|----------|
+| "Don't hallucinate facts" | "Only use information from the provided documents" |
+| "Don't be too formal" | "Write in a conversational, friendly tone" |
+| "Avoid long paragraphs" | "Keep paragraphs to 3-4 sentences" |
+| "Don't skip validation" | "Always validate before proceeding" |
+
+### Explain WHY, Not Just WHAT
+
+Trust Claude's intelligence. Provide goals and constraints rather than exhaustive implementation details.
+
+Provide:
+- The goal or purpose of the task
+- Why this matters (business context, use case)
+- Constraints that exist (technical, business)
+- What success looks like
+
+Let Claude handle:
+- Edge cases it can reason about
+- Best practices for the domain
+- Reasonable implementation choices
+
+Only give step-by-step instructions when the task genuinely requires precision or the domain knowledge is non-obvious.
+
+### Public Knowledge vs Tribal Knowledge
+
+This is critical. If the agent writing this skill knows how to do something, the agent executing it will know too. Both are Claude.
+
+**Public knowledge — state WHAT to do, not HOW:**
+- Standard CLI tools (git, npm, yt-dlp, ffmpeg, curl): "Use yt-dlp to search YouTube" — not the full command with flags
+- Common libraries and frameworks: "Parse the JSON response" — not the exact API call
+- Standard programming patterns: "Validate the input" — not a code block showing validation
+
+**Tribal knowledge — include the specifics:**
+- Custom internal CLI tools the project built
+- Project-specific conventions or configurations that are non-obvious
+- Workarounds for known bugs or quirks in the codebase
+- Domain-specific sequences that only an expert would know
+- Exact file paths, schemas, or formats unique to this project
+
+The test: if you removed the specific details, would a fresh Claude instance still know how to do it? If yes, remove the details. If no, keep them — that is the skill's value.
+
+### Be Clear and Direct
+
+No hedging. State exactly what to do.
+
+| Vague | Clear |
+|-------|-------|
+| "Maybe consider adding..." | "Add..." |
+| "It might be nice to have..." | "Include..." |
+| "You could potentially..." | "Use..." |
+
+### Challenge Every Line
+
+The context window is a shared resource. For every piece of content, ask: does this justify its token cost?
+
+- If Claude already knows it (common programming knowledge, obvious best practices) — remove it.
+- If it is not needed for the current step — it belongs in a different step file or not at all.
+- Three similar examples are better than ten. Pick the best ones.
+
+## Structural Rules
+
+### Size Targets
+
+| Type | SKILL.md Target |
+|------|-----------------|
+| Router (procedural) | Under 150 lines |
+| Informational | Under 300 lines |
+
+If SKILL.md exceeds these, move content to `references/`.
+
+### For Procedural Skills: Chained Steps
+
+Each step file covers ONE phase of the workflow. Structure each file:
+
+1. A clear header naming the step
+2. Immediate actionable instructions — what to do NOW
+3. A chain link at the bottom: "Read `references/[next-step].md`" with an optional condition
+
+**Critical rules:**
+- No table of contents across steps
+- No "this is step 3 of 5"
+- No overview of the full workflow
+- Each file is self-contained for what the agent needs RIGHT NOW
+- The agent discovers future steps only by reaching them
+
+### For Informational Skills
+
+Single SKILL.md file. Use sections and tables to organize knowledge. No chaining needed.
+
+Optionally add `references/` for depth that is not always needed — the SKILL.md would say "for more detail on X, read `references/x-details.md`".
+
+### SKILL.md Structure for Router Skills
+
+```
+---
+name: skill-name
+description: [third person, trigger phrases, WHEN not HOW]
+---
+
+# Skill Title
+
+## What To Do Now
+
+[Immediate action — ask a question, route to a workflow]
+
+| Choice | Action |
+|--------|--------|
+| Option A | Read `references/step-1-a.md` |
+| Option B | Read `references/step-1-b.md` |
+```
+
+Keep it minimal. Only include context that is needed at EVERY activation.
+
+### MCP Tool References
+
+When a skill uses MCP tools, use fully qualified names:
+```
+Use the BigQuery:bigquery_schema tool to retrieve table schemas.
+```
+Without the server prefix, Claude may fail to locate the tool.
+
+## Anti-Patterns
+
+**Option menus instead of defaults:** Provide a recommended default, not a menu of choices. "Use pdfplumber for text extraction" not "You can use pypdf, pdfplumber, PyMuPDF, or pdf2image."
+
+**Windows-style paths:** Always use forward slashes: `references/guide.md`, not `references\guide.md`.
+
+**Deeply nested indirection:** Sequential chaining is fine (step 1 → step 2 → step 3) because each step is self-contained. What to avoid is layers of indirection where you must read through multiple files to reach the actual instructions: SKILL.md → overview.md → details.md → actual-info.md.
+
+## Write the Files
+
+With these principles applied, write all the skill files now:
+
+1. SKILL.md (router or informational, depending on the design)
+2. For procedural: each step file in `references/`
+3. Any `scripts/` or `templates/` files if the design calls for them
+
+Read `references/create-step-4-review.md` when all files are written.

package/src/skills/creating-agent-skills/references/create-step-4-review.md

@@ -0,0 +1,63 @@
+# Step 4: Review
+
+Review every file you wrote before proceeding. Fix issues now — do not proceed with known problems.
+
+## Public Knowledge Audit
+
+Do this first. Go through every file in the skill and find each:
+- Code block (``` fenced blocks)
+- CLI command or flag sequence
+- API call or library usage example
+- Specific implementation detail
+
+For EACH one, ask: **"Would a fresh Claude instance — with no access to the user's original request — know how to do this?"**
+
+- If yes: **delete the code block or detail.** Replace with a high-level instruction. Example: replace `yt-dlp "ytsearch5:<query>" --print "%(title)s | %(channel)s | %(duration_string)s | %(webpage_url)s" --no-download` with "Use yt-dlp to search YouTube and display results."
+- If no: **keep it.** This is tribal knowledge — project-specific commands, internal tools, non-obvious configurations. This is the skill's value.
+
+The user's original request may have included specific commands and implementation details. That does not mean they belong in the skill. The user provided them for YOUR understanding. The skill is for a future Claude instance that already knows standard tools. Only encode what a fresh instance would NOT know.
+
+## Self-Review Checklist
+
+Go through each file and verify:
+
+### Actionability
+- After reading this file, would Claude know what action to take?
+- Is every section written as instructions, not documentation?
+- Are there any meta-descriptions? ("Who this is for", "Success looks like", "The purpose is...") Remove them.
+
+### Progressive Disclosure
+- For procedural skills: does each step file focus on ONE phase?
+- Does each step chain correctly to the next?
+- Is SKILL.md lean? Is heavy content in `references/`?
+- For informational skills: is it a single cohesive file without unnecessary splitting?
+
+### Writing Style
+- Imperative form throughout? ("Parse" not "You should parse")
+- Positive framing? ("Use X" not "Don't use Y")
+- No hedging? ("Add" not "Maybe consider adding")
+- Is every line worth its token cost? Remove what Claude already knows.
+
+### Structure
+- SKILL.md under size target? (150 lines for router, 300 for informational)
+- Valid YAML frontmatter with `name` and `description`?
+- Name matches the directory name?
+- Description uses third person with quoted trigger phrases?
+- All referenced files exist? (no broken links)
+
+## Run Validation
+
+```bash
+node ~/.claude/skills/creating-agent-skills/scripts/validate-skill.js [skill-path]
+```
+
+Handle results:
+- **Errors:** Fix each one, re-run validation, repeat until passing
+- **Warnings:** Evaluate each — most should be fixed
+- **Info:** Review but these may be acceptable (e.g., step files referenced from other steps rather than SKILL.md)
+
+Only proceed when validation passes and self-review is clean.
+
+If you found and fixed issues, re-run both the self-review and validation to confirm.
+
+Read `references/create-step-5-install.md` when review passes with no remaining issues.

package/src/skills/creating-agent-skills/references/create-step-5-install.md

@@ -0,0 +1,39 @@
+# Step 5: Install and Test
+
+## Choose Install Location
+
+Ask the user where to install:
+
+| Level | Path | When to Use |
+|-------|------|-------------|
+| User | `~/.claude/skills/[name]/` | Available across all projects |
+| Project | `.claude/skills/[name]/` | This project only |
+
+## Install
+
+Copy the skill directory to the target location. Ensure all files are in place — SKILL.md, `references/`, `scripts/`, `templates/` as applicable.
+
+## Test
+
+Guide the user through testing:
+
+1. Start a new Claude Code session (or restart the current one)
+2. Test explicit invocation: type `/skill-name`
+3. Test autonomous activation: say one of the trigger phrases from the description
+4. Verify the skill activates and behaves as expected
+
+## If Testing Reveals Issues
+
+Iterate. The job is not done until the skill works.
+
+- Instructions wrong? Go back to the write step.
+- Structure wrong? Go back to the design step.
+- Domain knowledge missing? Go back to the understand step.
+
+## Completion
+
+Summarize what was created:
+- Skill name
+- Install location
+- Trigger phrases
+- File structure (list all files)

package/src/skills/creating-agent-skills/references/fix-step-1-diagnose.md

@@ -0,0 +1,83 @@
+# Step 1: Diagnose
+
+Find the skill, read everything, and understand what is wrong.
+
+## Find the Skill
+
+If the user named a specific skill, locate it. Otherwise, discover available skills:
+
+```bash
+node ~/.claude/skills/creating-agent-skills/scripts/find-skills.js
+```
+
+Ask which skill to fix.
+
+## Read Everything
+
+Read the entire skill — every file:
+- SKILL.md
+- Every file in `references/`
+- Every file in `scripts/`
+- Every file in `templates/` or `assets/`
+
+Trace the execution path: if SKILL.md says "read `references/step-1.md`", read that file and follow its chain.
+
+Cannot diagnose a skill without reading all its files.
+
+## Understand What Is Wrong
+
+Ask the user:
+- "What is the skill supposed to do?"
+- "What does it actually do instead?"
+- "Can you show me an example of it failing or behaving incorrectly?"
+
+Get specific about expected behavior versus actual behavior.
+
+## Diagnose Against Principles
+
+Evaluate each file against these criteria:
+
+### Actionability
+- After reading this file, would Claude know what to DO?
+- Or does it just describe what the skill is about?
+- Any dead ends where Claude would not know what to do next?
+
+### Progressive Disclosure
+- Is SKILL.md lean (under 150 lines for routers, under 300 for informational)?
+- Is heavy content in `references/`, not inline?
+- For procedural skills: is each phase in its own step file, chained to the next?
+- Or is everything crammed into one file?
+
+### Routing and Chaining
+- For multi-step skills: does each file hand off clearly to the next?
+- Are there dead ends with no next action?
+- Is the chain condition clear (when to move on)?
+
+### Writing Style
+- Second person language? ("You should..." — should be imperative: "Parse...")
+- Negative framing? ("Don't skip..." — should be positive: "Always validate...")
+- Meta-descriptions? ("Who this is for", "Success looks like", "The purpose is...")
+- Hedging? ("Maybe consider..." — should be direct: "Add...")
+- Public knowledge spelled out? (exact CLI flags, standard API calls that Claude already knows — should state WHAT to do, not HOW, unless it is tribal/project-specific knowledge)
+
+### Description Quality
+- Third person? ("This skill should be used when...")
+- Quoted trigger phrases?
+- Focuses on WHEN to use, not HOW it works?
+- Under 1024 characters?
+
+### Structural
+- Valid YAML frontmatter with `name` and `description`?
+- Name matches directory name?
+- All referenced files exist?
+- Any unreferenced files in `references/` that should be connected?
+
+## Summarize Findings
+
+Present the diagnosis to the user:
+- List each issue found
+- Which file it is in
+- What principle it violates
+- What the fix would look like
+
+Read `references/fix-step-2-apply.md` when diagnosis is complete and findings are summarized.

package/src/skills/creating-agent-skills/references/fix-step-2-apply.md

@@ -0,0 +1,90 @@
+# Step 2: Apply Fixes
+
+Fix the issues identified in diagnosis. Plan the changes, confirm with the user, then apply.
+
+## Plan Changes First
+
+Before editing, state:
+- Which files will change and what specifically changes
+- Any new files needed (e.g., splitting a monolithic file into step files)
+- Any files to delete
+
+Confirm the plan with the user before making changes.
+
+## Writing Principles
+
+Apply these while making every change:
+
+### Instructions, Not Documentation
+
+Write as instructions. Imperative form.
+
+| Wrong | Right |
+|-------|-------|
+| "This skill parses PDF files" | "Parse the PDF file" |
+| "You should validate the input" | "Validate the input" |
+| "The next step involves formatting" | "Format the output" |
+
+### No Meta-Descriptions
+
+Remove any of these:
+- "Who this is for:" — Claude does not need audience info
+- "Success looks like:" — describe outcomes through instructions
+- "The purpose is..." — documentation language
+- "This skill orchestrates..." — describes what the skill IS
+- "Overview" or "Introduction" sections — get to the action
+
+### Positive Framing
+
+| Negative | Positive |
+|----------|----------|
+| "Don't hallucinate facts" | "Only use information from the provided documents" |
+| "Don't skip validation" | "Always validate before proceeding" |
+| "Avoid long paragraphs" | "Keep paragraphs to 3-4 sentences" |
+
+### Explain WHY, Not Just WHAT
+
+Provide goals and constraints. Trust Claude's intelligence. Only give step-by-step when the domain genuinely requires precision.
+
+### Public Knowledge vs Tribal Knowledge
+
+If the agent writing this skill knows how to do something, the agent executing it will know too. Both are Claude.
+
+- **Public knowledge** (standard CLI tools, common libraries, standard patterns): state WHAT to do, not HOW. "Use yt-dlp to search YouTube" — not the full command with flags.
+- **Tribal knowledge** (custom internal tools, project-specific conventions, workarounds, non-obvious domain sequences): include the specifics. That is the skill's value.
+
+The test: if you removed the specific details, would a fresh Claude instance still know how to do it? If yes, remove them.
+
+### Be Clear and Direct
+
+No hedging. "Add..." not "Maybe consider adding..."
+
+### Challenge Every Line
+
+Does this justify its token cost? If Claude already knows it — remove it. If it is not needed for the current step — move or remove it.
+
+**The test:** After rewriting each file, ask: "If Claude reads this right now, does it know what action to take?"
+
+## Common Fix Patterns
+
+**Documentation to instructions:** Rewrite "This skill does X" as "Do X".
+
+**Add trigger phrases:** Collect phrases from user, add to description in third person with quotes.
+
+**Move content to references:** Identify inline content that should be loaded on-demand. Create reference files, add pointers.
+
+**Fix second person:** "You should parse" becomes "Parse". "You can use" becomes "Use".
+
+**Fix negative framing:** "Don't skip validation" becomes "Always validate". "Never assume" becomes "Verify explicitly".
+
+**Fix progressive disclosure:** Split a monolithic SKILL.md into a lean router + step files in `references/`. Each step file covers one phase and chains to the next.
+
+**Fix dead ends:** Ensure every file either chains to the next step or completes the flow with a clear ending.
+
+**Fix description:** Rewrite to third person, add quoted trigger phrases, focus on WHEN not HOW.
+
+## Apply the Changes
+
+Make all planned modifications now.
+
+Read `references/fix-step-3-validate.md` when all fixes are applied.