Skill Coach: Creating Expert-Level Agent 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 (wc -l) → Should be <500
4. Remove dead files → Delete unreferenced scripts/references
5. Test activation → Ask questions that should/shouldn't trigger it

Quick Start

Creating a New Skill:

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
5. Use Review Checklist below

Core Principles

1. Progressive Disclosure Architecture

Skills load in three phases:

• Phase 1 (~100 tokens): Metadata (name, description) - "Should I activate?"
• Phase 2 (<5k tokens): Main instructions in SKILL.md - "How do I do this?"
• Phase 3 (as needed): Scripts, references, assets - "Show me the details"

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

2. Description Field Design

The description is your activation trigger. Formula: [What] [Use for] [Keywords] NOT for [Exclusions]

Progression from Bad → Good:

❌ Bad: description: Helps with images

• Too vague, no keywords, no exclusions

⚠️ Better: description: Image processing with CLIP

• Has keyword (CLIP) but no use cases or exclusions

✅ Good: description: CLIP semantic search. Use for image-text matching, zero-shot classification. Activate on "CLIP", "embeddings", "image search". NOT for counting, fine-grained classification, spatial reasoning.

• Clear capability, use cases, keywords, and exclusions

3. Anti-Pattern Detection

Great skills actively warn about common mistakes. Structure:

## Common Anti-Patterns

### Pattern: [Name]
**What it looks like**: [Code example or description]
**Why it's wrong**: [Fundamental reason]
**What to do instead**: [Better approach]
**How to detect**: [Validation rule]

4. Temporal Knowledge

Technology evolves. Capture what changed and when:

## Evolution Timeline

### Pre-2024: Old Approach
[What people used to do]

### 2024-Present: Current Best Practice
[What changed and why]

### Watch For
[Deprecated patterns LLMs might still suggest]

Skill Structure

Mandatory:

your-skill/
└── SKILL.md           # Core instructions (<500 lines)

Optional (only if needed):

├── scripts/           # Working code (not templates)
├── references/        # Deep dives (referenced from SKILL.md)
├── assets/            # Config files, templates
└── examples/          # Concrete good/bad examples

Anti-pattern: Creating structure "just in case" - only add files that SKILL.md references

SKILL.md Template Structure

---