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:
Add NOT clause to description → Prevents false activation Add 1-2 anti-patterns → Prevents common mistakes Check line count (run validator) → Should be fewer than 500 lines Remove dead files → Delete unreferenced scripts/references Test activation → Questions that should/shouldn't trigger it What Makes a Great Skill
Great skills are progressive disclosure machines that:
Activate precisely - Specific keywords + NOT clause Encode shibboleths - Expert knowledge that separates novice from expert Surface anti-patterns - "If you see X, that's wrong because Y, use Z" Capture temporal knowledge - "Pre-2024: X. 2024+: Y" Know their limits - "Use for A, B, C. NOT for D, E, F" Provide decision trees - Not templates, but "If X then A, if Y then B" 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:
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:
❌ 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)$" && \ 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:
How to execute from scratch 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
Check for self-contained tool completeness
python scripts/check_self_contained.py
Step 6: Iterate
After real-world use:
Notice struggles or inefficiencies Identify how SKILL.md or bundled resources should be updated Implement changes and test again Common Workflows
Create Skill from Expertise:
Define scope: What expertise? What keywords? What NOT to handle? Write description with keywords and NOT clause Add anti-patterns you've observed 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
Recursive Self-Improvement (use this skill to improve skills):
Run python scripts/validate_skill.py
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 Metric Target Correct activation >90% False positive rate <5% Token usage <5k typical Reference Files 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