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
- AlejandroVegaFullstackDev/ai-skill-coachtheir own version, first seen Sep 22, 2026
- flll/grow-your-own-skillstheir own version, first seen Jul 5, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
- AlejandroVegaFullstackDev/ai-skill-coach★ 3same name
- flll/grow-your-own-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository185 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- 2000s-visualization-expertSkill
- 2026-legal-research-agentSkill
- adhd-daily-plannerSkill
- adhd-design-expertSkill
- admin-dashboardSkill
- agent-creatorSkill
- ai-engineerSkill
- ai-video-production-masterSkill
- anthropic-technical-deep-diveSkill
- api-architectSkill
- automatic-stateful-prompt-improverSkill
- background-job-orchestratorSkill
- bot-developerSkill
- caching-strategiesSkill
- career-biographerSkill
- chatbot-analyticsSkill
- checklist-disciplineSkill
- claude-ecosystem-promoterSkill
- clinical-diagnostic-reasoningSkill
- clip-aware-embeddingsSkill
- cloudflare-worker-devSkill
- code-architectureSkill
- code-necromancerSkill
- code-review-checklistSkill
- collage-layout-expertSkill
- color-contrast-auditorSkill
- color-theory-palette-harmony-expertSkill
- competitive-cartographerSkill
- component-template-generatorSkill
- computer-vision-pipelineSkill
- cost-accrual-trackerSkill
- cost-optimizerSkill
- cost-verification-auditorSkill
- crisis-detection-intervention-aiSkill
- crisis-response-protocolSkill
- cv-creatorSkill
- dark-mode-design-expertSkill
- database-design-patternsSkill
- data-pipeline-engineerSkill
- data-viz-2025Skill
- dependency-managementSkill
- design-accessibility-auditorSkill
- design-archivistSkill
- design-criticSkill
- design-justiceSkill
- design-system-creatorSkill
- design-system-documenterSkill
- design-system-generatorSkill
- design-trend-analyzerSkill
- devops-automatorSkill
- diagramming-expertSkill
- digital-estate-plannerSkill
- docker-containerizationSkill
- document-generation-pdfSkill
- drizzle-migrationsSkill
- drone-cv-expertSkill
- drone-inspection-specialistSkill
- email-composerSkill
- error-handling-patternsSkill
- The first 60 shown.
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
- Distinctive: line 56
Provide decision trees: - Not templates, but "If X then A, if Y then B"
- Very specific: line 67
Critical: Keep SKILL.md under 500 lines.
- Distinctive: line 190
Follow these steps in order when creating a new skill:
- Distinctive: line 209
Create the skill directory structure:
- Distinctive: line 219
Write in imperative/infinitive form ("To accomplish X, do Y")
- Distinctive: line 244
Write description with keywords and NOT clause
- Distinctive: line 245
Add anti-patterns you've observed
- Very specific: line 267
Run python scripts/test_activation.py <path> to validate
- Very specific: line 270
Run python scripts/validate_skill.py <path> → Get validation report
- Very specific: line 271
Run python scripts/check_self_contained.py <path> → Check tool completeness
- Distinctive: line 274
Update CHANGELOG.md with improvements made
≈ “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.
Files
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:
- numpyMove 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))"
doneSkill 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 historySelf-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-editorfor "rotate this PDF" → Needsscripts/rotate_pdf.pyfrontend-webapp-builder→ Needsassets/hello-world/templatebig-queryskill → Needsreferences/schema.mdfor 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 queriesRun 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
Bashfor 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
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
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.

