skill-coach

Skill Coach: Creating Expert-Level Agent Skills

Encode real domain expertise, not just surface-level instructions. Focus on shibboleths - the deep knowledge that separates novices from experts.

When to Use This Skill

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)

Quick Wins

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

What Makes a Great Skill

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

Core Principles

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."

SKILL.md Template

---
name: your-skill-name
description: [What] [When] [Triggers]. NOT for [Exclusions].
allowed-tools: Read,Write  # Minimal only
---

# Skill Name
[One sentence purpose]

## When to Use
✅ Use for: [A, B, C]
❌ NOT for: [D, E, F]

## Core Instructions
[Step-by-step, decision trees, not templates]

## Common Anti-Patterns
### [Pattern]
**Symptom**: [Recognition]
**Problem**: [Why wrong]
**Solution**: [Better approach]

Frontmatter Rules (CRITICAL)

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

Invalid keys that will FAIL upload:

# ❌ 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:

## Integrations
Works with: orchestrator, team-builder

## Activation Triggers
Responds to: "create skill", "review skill", "skill quality"

Validation command:

# 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)
quot; && \
    echo "  ^ in $(basename $(dirname $skill))"
done

Skill Structure

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

Self-Contained Skills (RECOMMENDED)

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.

Decision Trees

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

Skill Creation Process (6 Steps)

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

# Validate skill structure and content
python scripts/validate_skill.py <path>

# Check for self-contained tool completeness
python scripts/check_self_contained.py <path>

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

---

Common Workflows

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 <path> to validate

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

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

Tool Permissions

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

Success Metrics

Reference Files

---

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