agentleFS
dhriyatinandu-botdhriyatinandu-bot/claude-skills/.claude/skills/skill-coach/SKILL.md

skill-coach

Skill0 starsChanged 9 months agoMITView on GitHub

Guides creation of high-quality Agent Skills with domain expertise, anti-pattern detection, and progressive disclosure best practices. Activate on keywords: create skill, review skill, skill

2 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

11 rules. About 0 are common, 7 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Provide decision trees: - Not templates, but "If X then A, if Y then B"

    line 56
  2. Very specific:

    Critical: Keep SKILL.md under 500 lines.

    line 67
  3. Distinctive:

    Follow these steps in order when creating a new skill:

    line 190
  4. Distinctive:

    Create the skill directory structure:

    line 209
  5. Distinctive:

    Write in imperative/infinitive form ("To accomplish X, do Y")

    line 219
  6. Distinctive:

    Write description with keywords and NOT clause

    line 244
  7. Distinctive:

    Add anti-patterns you've observed

    line 245
  8. Very specific:

    Run python scripts/test_activation.py <path> to validate

    line 267
  9. Very specific:

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

    line 270
  10. Very specific:

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

    line 271
  11. Distinctive:

    Update CHANGELOG.md with improvements made

    line 274

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

KeyRequiredPurpose
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:

  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

MetricTarget
Correct activation>90%
False positive rate<5%
Token usage<5k typical

Reference Files

FileContents
references/antipatterns.mdDomain shibboleths and anti-pattern catalog with case studies
references/shibboleths.mdExpert vs novice knowledge patterns
references/validation-checklist.mdComplete review and testing guide
references/self-contained-tools.mdScripts, MCP servers, and subagent implementation patterns
references/scoring-rubric.mdQuantitative skill evaluation (0-10 scoring)
references/skill-composition.mdCross-skill dependencies and composition patterns
references/skill-lifecycle.mdMaintenance, versioning, and deprecation guidance
references/mcp_vs_scripts.mdArchitectural decision guide: Skills vs Agents vs MCPs vs Scripts

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

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.