skill-coach

Use for:

• Creating new Agent Skills from scratch
• Reviewing/auditing existing skills
• Improving skill activation rates
• Adding domain expertise to skills
• Debugging why skills don't activate

NOT for:

• General Claude Code features (slash commands, MCPs)
• Non-skill coding advice
• Debugging runtime errors (use domain skills)

Immediate improvements for existing skills:

1. Add NOT clause to description → Prevents false activation
2. Add 1-2 anti-patterns → Prevents common mistakes
3. Check line count (run validator) → Should be fewer than 500 lines
4. Remove dead files → Delete unreferenced scripts/references
5. Test activation → Questions that should/shouldn't trigger it

Great skills are progressive disclosure machines that:

1. Activate precisely - Specific keywords + NOT clause
2. Encode shibboleths - Expert knowledge that separates novice from expert
3. Surface anti-patterns - "If you see X, that's wrong because Y, use Z"
4. Capture temporal knowledge - "Pre-2024: X. 2024+: Y"
5. Know their limits - "Use for A, B, C. NOT for D, E, F"
6. Provide decision trees - Not templates, but "If X then A, if Y then B"
7. Stay under 500 lines - Core in SKILL.md, deep dives in /references

Progressive Disclosure

• Phase 1 (~100 tokens): Metadata - "Should I activate?"
• Phase 2 (<5k tokens): SKILL.md - "How do I do this?"
• Phase 3 (as needed): References - "Show me the details"

Critical: Keep SKILL.md under 500 lines. Split details into /references.

Description Formula

[What] [Use for] [Keywords] NOT for [Exclusions]

```

❌ Bad: "Helps with images"

⚠️ Better: "Image processing with CLIP"

✅ Good: "CLIP semantic search. Use for image-text matching.

Activate on 'CLIP', 'embeddings'. NOT for counting, spatial reasoning."

```

```markdown

---

name: your-skill-name

description: [What] [When] [Triggers]. NOT for [Exclusions].

allowed-tools: Read,Write # Minimal only

---

# Skill Name

[One sentence purpose]

✅ Use for: [A, B, C]

❌ NOT for: [D, E, F]

[Step-by-step, decision trees, not templates]

[Pattern]

Symptom: [Recognition]

Problem: [Why wrong]

Solution: [Better approach]

```

Only these frontmatter keys are allowed by Claude's skill marketplace:

| Key | Required | Purpose |

|-----|----------|---------|

| name | ✅ | Lowercase-hyphenated identifier |

| description | ✅ | Activation keywords + NOT clause |

| allowed-tools | ⚠️ | Comma-separated tool names |

| license | ❌ | e.g., "MIT" |

| metadata | ❌ | Custom key-value pairs |

Invalid keys that will FAIL upload:

```yaml

# ❌ WRONG - These will break skill upload

integrates_with:

- orchestrator

triggers:

- "activate on this"

tools: Read,Write

outputs: formatted text

coordinates_with: other-skill

python_dependencies:

- numpy

```

Move custom info to the body:

```markdown

Works with: orchestrator, team-builder

Responds to: "create skill", "review skill", "skill quality"

```

Validation command:

```bash

# Find invalid frontmatter keys

for skill in .claude/skills/*/SKILL.md; do

sed -n '/^---$/,/^---$/p' "$skill" | grep -E "^[a-zA-Z_-]+:" | cut -d: -f1 | \

grep -vE "^(name|description|license|allowed-tools|metadata)$" && \

echo " ^ in $(basename $(dirname $skill))"

done

```

Mandatory:

```

your-skill/

└── SKILL.md # Core instructions (max 500 lines)

```

Strongly Recommended (self-contained skills):

```

├── scripts/ # Working code - NOT templates

├── mcp-server/ # Custom MCP if external APIs needed

├── agents/ # Subagent definitions if orchestration needed

├── references/ # Deep dives on domain knowledge

└── CHANGELOG.md # Version history

```

Skills with working tools are immediately useful. See references/self-contained-tools.md for full patterns.

Quick decision: External APIs? → MCP. Multi-step workflow? → Subagents. Repeatable operations? → Scripts.

When to create a NEW skill?

• ✅ Domain expertise not in existing skills
• ✅ Pattern repeats across 3+ projects
• ✅ Anti-patterns you want to prevent
• ❌ One-time task → Just do it directly
• ❌ Existing skill could be extended → Improve that one

Skill vs Subagent vs MCP?

• Skill: Domain expertise, decision trees (no runtime state)
• Subagent: Multi-step workflows needing tool orchestration
• MCP: External APIs, auth, stateful connections

Follow these steps in order when creating a new skill:

Step 1: Understand with Concrete Examples

Skip only if usage patterns are already clear. Ask:

• "What functionality should this skill support?"
• "Can you give examples of how it would be used?"
• "What would a user say that should trigger this skill?"

Step 2: Plan Reusable Contents

For each example, analyze:

1. How to execute from scratch
2. What scripts, references, assets would help with repeated execution

Example analyses:

• pdf-editor for "rotate this PDF" → Needs scripts/rotate_pdf.py
• frontend-webapp-builder → Needs assets/hello-world/ template
• big-query skill → Needs references/schema.md for table schemas

Step 3: Initialize the Skill

Create the skill directory structure:

```

your-skill/

├── SKILL.md # Core instructions (max 500 lines)

├── scripts/ # Working code - NOT templates

├── references/ # Deep dives on domain knowledge

└── assets/ # Files used in output (templates, icons)

```

Step 4: Write SKILL.md

• Write in imperative/infinitive form ("To accomplish X, do Y")
• Answer: Purpose? When to use? How to use bundled resources?
• Reference all scripts/references so Claude knows they exist

Step 5: Validate and Package

```bash

# Validate skill structure and content

python scripts/validate_skill.py

# Check for self-contained tool completeness

python scripts/check_self_contained.py

```

Step 6: Iterate

After real-world use:

1. Notice struggles or inefficiencies
2. Identify how SKILL.md or bundled resources should be updated
3. Implement changes and test again

---

Create Skill from Expertise:

1. Define scope: What expertise? What keywords? What NOT to handle?
2. Write description with keywords and NOT clause
3. Add anti-patterns you've observed
4. Test activation thoroughly

Debug Activation Issues (flowchart):

```

Skill not activating when expected?

├── Check description has specific keywords

│ ├── NO → Add "Activate on: keyword1, keyword2"

│ └── YES → Check if query contains those keywords

│ ├── NO → Add missing keyword variations

│ └── YES → Check for conflicting NOT clause

│ ├── YES → Narrow exclusion scope

│ └── NO → Check file structure

│ ├── SKILL.md missing → Create it

│ └── Wrong location → Move to .claude/skills/

Skill activating when it shouldn't?

├── Missing NOT clause?

│ ├── YES → Add "NOT for: exclusion1, exclusion2"

│ └── NO → NOT clause too narrow

│ └── Expand exclusions based on false positive queries

```

Run python scripts/test_activation.py to validate

Recursive Self-Improvement (use this skill to improve skills):

1. Run python scripts/validate_skill.py → Get validation report
2. Run python scripts/check_self_contained.py → Check tool completeness
3. Address ERRORS first, then WARNINGS, then SUGGESTIONS
4. Re-run validation until clean
5. Update CHANGELOG.md with improvements made

Guidelines:

• Read-only skill: Read,Grep,Glob
• File modifier: Read,Write,Edit
• Build integration: Read,Write,Bash(npm:,git:)
• ⚠️ Never: Unrestricted Bash for untrusted skills

| Metric | Target |

|--------|--------|

| Correct activation | >90% |

| False positive rate | <5% |

| Token usage | <5k typical |

| File | Contents |

|------|----------|

| references/antipatterns.md | Domain shibboleths and anti-pattern catalog with case studies |

| references/shibboleths.md | Expert vs novice knowledge patterns |

| references/validation-checklist.md | Complete review and testing guide |

| references/self-contained-tools.md | Scripts, MCP servers, and subagent implementation patterns |

| references/scoring-rubric.md | Quantitative skill evaluation (0-10 scoring) |

| references/skill-composition.md | Cross-skill dependencies and composition patterns |

| references/skill-lifecycle.md | Maintenance, versioning, and deprecation guidance |

| references/mcp_vs_scripts.md | Architectural decision guide: Skills vs Agents vs MCPs vs Scripts |

---

This skill guides: Skill creation | Skill auditing | Anti-pattern detection | Progressive disclosure | Domain expertise encoding