building-skills
Skill9 starsChanged 9 months agoMITView on GitHub
Create, restructure, and validate Claude Code skills following best practices. Handles directory structure, YAML frontmatter, progressive disclosure, credential management, self-learning with consolidation, and script organization. Use when creating new skills, restructuring existing skills, reviewing skills for quality, or asking about skill structure, patterns, or best practices.
- Reads credentials
3 other projects use a version of this.
Adopted by
Most recently taken up by
- develeep/dev-gongbangtheir own version, first seen Nov 15, 2026
- zlliang/skillstheir own version, first seen Nov 2, 2026
- MSILycanthropy/skillstheir own version, first seen Feb 11, 2026
Other versions3 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 3
- develeep/dev-gongbang★ 1same name
- MSILycanthropy/skills★ 1same name
- zlliang/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 repository3 other files it gives its agents.
- animatorSkill
- qmdSkill
- stealth-browserSkill
The file
We split this skill into the rules it gives an agent
9 rules. About 0 are common, 5 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
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 14
Read LEARNED.md before building or reviewing any skill.
- Very specific: line 46
Every skill MUST have LEARNED.md with consolidation rules.
- Very specific: line 78
allowed-tools: Only tools the skill needs.
- Distinctive: line 86
Write 3-5 user requests this skill should fire on.
- Distinctive: line 98
Before the body. The description determines if the skill ever triggers.
- Distinctive: line 125
Stay under 500 lines: If approaching 300, start splitting to references/.
- Very specific: line 141
Add Self-Learning section to SKILL.md (see template below).
- Very specific: line 171
Validate: Run validate_skill.py.
- Distinctive: line 247
Before adding, check length.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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
Building Skills
Read LEARNED.md before building or reviewing any skill.
Core Principles
1. Context Window is Sacred
Skills share context with system prompt, conversation history, other skills, and the user's request. Only add what Claude doesn't already know.
For every line ask: Does this justify its token cost? If Claude knows it, cut it.
2. Progressive Disclosure
Skills load in three stages. Design for this.
| Stage | What loads | Budget | Contains |
| Discovery | name + description | ~100 tokens | Trigger keywords, when to use |
| Activation | SKILL.md body | <5000 tokens | Instructions, workflows, quick start |
| Execution | references/, scripts/ | As needed | Detailed docs, executable code |
Critical: The description field is the trigger mechanism. All "when to use" info goes there, not the body. The body only loads AFTER triggering.
3. Degrees of Freedom
Match instruction specificity to how fragile the task is:
- High freedom (text guidance): Creative tasks, multiple valid approaches. "Write a blog post following these guidelines."
- Medium freedom (parameterized scripts): Preferred pattern exists but adapts. "Run the audit script, interpret results."
- Low freedom (exact scripts, few params): Fragile operations, API calls, deploys. "Run exactly:
python scripts/deploy.py --env prod"
4. Self-Learning is Mandatory
Every skill MUST have LEARNED.md with consolidation rules. No exceptions.
Required Structure
skill-name/
├── SKILL.md # Required. <500 lines. Core instructions.
├── LEARNED.md # Required. <50 lines. Dated entries + consolidation.
├── scripts/ # Executable code. Runs but never loaded into context.
├── references/ # Detailed docs. Loaded into context on demand (costs tokens).
├── setup/ # Credential templates, setup instructions.
└── assets/ # Files used in output (templates, icons). Never loaded into context.Key distinction: references/ costs tokens when read. scripts/ and assets/ don't - scripts execute and return output, assets are used in generated files. Put large docs, templates, and data in assets/ not references/.
Frontmatter
---
name: skill-name
description: |
Third person. WHAT it does + WHEN to use it + trigger keywords.
This is the primary trigger. Max 1024 chars. No angle brackets.
allowed-tools: Bash Read Write
---name: kebab-case, max 64 chars, no consecutive/leading/trailing hyphens. Must match directory name.
description: The most important field. Claude reads ALL descriptions to decide which skill to trigger. Front-load trigger conditions. Include keywords users would actually say. Bad: "Manages Google Ads." Good: "Control Google Ads via official API. Create, pause, optimize campaigns, ads, keywords, bids. Run audits. Use when user mentions Google Ads, PPC, AdWords, Quality Score, or ad performance."
allowed-tools: Only tools the skill needs. Common: Bash Read Write Edit.
Allowed keys: name, description, license, allowed-tools, metadata, compatibility. Nothing else.
Creating a New Skill
1. Define trigger examples
Write 3-5 user requests this skill should fire on. These become description keywords and test cases.
2. Scaffold
python3 ~/.claude/skills/building-skills/scripts/init_skill.py my-skill --path ~/.claude/skillsThis creates SKILL.md, LEARNED.md, scripts/, references/, setup/, and assets/ with guided TODOs.
3. Write the description FIRST
Before the body. The description determines if the skill ever triggers.
Pattern: [What it does] + [How/via what] + [Specific actions] + [Trigger keywords]
Example: "Local semantic search for markdown knowledge bases using qmd (tobi/qmd). Indexes markdown with BM25 keyword search, vector embeddings, and hybrid reranked queries. Auto-indexes on edits via Claude Code hooks. Use when searching project docs, knowledge bases, meeting notes, or any indexed markdown collection."
4. Write SKILL.md body
# Skill Name
## Quick Start
[Minimal working example - simplest successful use]
## Core Operations
[Brief list. Link to references/ for detail if >100 lines.]
## Workflows
[Checklists for multi-step tasks. Conditional routing for different paths.]
## Error Reference
[Common errors and fixes. Keep actionable, not exhaustive.]
## Self-Learning
[LEARNED.md link + what to record + consolidation rules]Stay under 500 lines. If approaching 300, start splitting to references/.
5. Add self-learning
Create LEARNED.md:
# skill-name - Learned
<!-- Keep under 50 lines. Consolidate before adding. -->
## [Category]
- (YYYY-MM-DD) Observation hereAdd Self-Learning section to SKILL.md (see template below).
6. Add scripts with dependency checking
Scripts must detect missing deps and guide setup, not fail silently:
import os, sys
required = ['MY_API_KEY']
missing = [v for v in required if not os.environ.get(v)]
if missing:
print(f"Missing: {', '.join(missing)}")
print("Add to ~/.claude/settings.json under \"env\"")
sys.exit(1)7. Validate
python3 ~/.claude/skills/building-skills/scripts/validate_skill.py ~/.claude/skills/my-skillFix errors, address warnings, re-run until clean.
Restructuring an Existing Skill
- Audit: SKILL.md line count (<500?), scripts inside skill?, credentials via env vars?, frontmatter valid?, LEARNED.md exists?, description has trigger keywords?
- Split: Core instructions → SKILL.md. Detailed docs → references/. Code → scripts/. Config → setup/. Output files → assets/.
- Fix description: Is it the trigger mechanism? Does it front-load keywords? Third person?
- Add self-learning: LEARNED.md + consolidation section.
- Validate: Run validate_skill.py.
Patterns
Credentials
~/.claude/settings.json env vars. Never hardcode. Scripts detect and print setup instructions. Document in setup/README.md.
Workflow Checklists
Multi-step tasks get numbered, copy-able checklists with explicit steps.
Conditional Routing
**Creating new?** → See [Creation](#creation)
**Editing?** → See [Editing](#editing)
**Debugging?** → See [references/troubleshooting.md](references/troubleshooting.md)Feedback Loops
1. Make changes → 2. Run validator → 3. If errors, fix and go to 2Output Templates
Strict format: provide exact template in assets/. Flexible format: show examples.
Hook Integration
Skills can hook into Claude Code (PreToolUse/PostToolUse) for system-level behavior like auto-indexing or domain blocking. Document in hooks/ subdirectory.
For detailed pattern examples, see references/patterns.md.
Anti-Patterns
| Don't | Do |
| Trigger info only in body | Put trigger keywords in description |
| Credentials in skill files | ~/.claude/settings.json env vars |
| Scripts in global folder | Scripts inside skill directory |
| SKILL.md >500 lines | Split to references/ |
| Nested references (A→B→C) | One level deep from SKILL.md |
| No LEARNED.md | Every skill must self-learn |
| Unbounded LEARNED.md | Cap 50 lines, consolidate |
| README.md, CHANGELOG.md etc | Skills are for AI, not human docs |
| "You can use..." in description | Third person: "Processes..." |
| Assume deps installed | Check and guide setup on failure |
| Large docs in references/ | Put in assets/ if not needed in context |
Self-Learning Template
## Self-Learning
Read [LEARNED.md](LEARNED.md) before using this skill.
**Update LEARNED.md when you discover:** [list skill-specific things to record]
**Consolidation (keep under 50 lines):**
Before adding a new entry, check file length. If over 50 lines:
1. Merge duplicate/overlapping entries into single proven patterns
2. Remove entries older than 3 months that haven't been reinforced
3. Drop one-off observations that never recurred
4. Move detailed context to `LEARNED-archive.md` if worth preserving
5. Keep only entries that would change behavior - if obvious, cut itSelf-Learning
Read LEARNED.md before building or reviewing any skill.
Update LEARNED.md when you discover:
- Patterns that worked well in production skills
- Description wording that improved or hurt triggering
- Common mistakes when building skills
- Validation gaps (things the validator should catch)
- Structure decisions that helped or hurt
Consolidation (keep under 50 lines): Before adding, check length. If over 50: merge duplicates, prune stale (>3mo unreinforced), drop one-offs, archive to LEARNED-archive.md.
References
- Patterns Reference - Workflow, output, credential, hook, and testing patterns
- Anthropic Skill Spec - Official skill specification and examples
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.

