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

Check for self-contained tool completeness

python scripts/check_self_contained.py <path>

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

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

• Run python scripts/validate_skill.py <path> → Get validation report

• Run python scripts/check_self_contained.py <path> → Check tool completeness

• Address ERRORS first, then WARNINGS, then SUGGESTIONS

• Re-run validation until clean

• 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

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