Two things find a skill and they were being confused for one. An agent matches on the description; a person types the name. The guidance here only said "filename matches domain", which decides neither — so the catalogue grew mcp-builder beside skill-creator, discovery beside planning, testing beside deployment. An agent looking for the one that makes a thing has to try both words and hope. The shape is <subject>-<act>, two words, and the acts are a closed list with no synonyms: port, build, test, review, deploy, plan. One word only where the skill is its subject and there is no act — hanzo-base, anti-slop. Never three; a third word is almost always a category, and the index is what categories are for. port rather than copy is not a coin toss. A port keeps what the target system already does right and reproduces the source's behaviour and appearance; copying says to take the implementation, which is the thing these skills tell you not to do. The test: could somebody who knows the rule, and has never seen the skill, write its name correctly on the first try? If not the name is wrong, not the reader. The short version is in the agent manifest, so an agent reads the rule before it needs a name and can derive app-port without looking it up. Co-authored-by: Hanzo Dev <[email protected]>
18 KiB
name, description
| name | description |
|---|---|
| skill-creation | Creating new atomic skills for the skills system |
Skill Creation
Scope: Creating atomic skills, structure, integration with CLAUDE.md, discovery patterns Lines: ~400 Last Updated: 2025-10-18
When to Use This Skill
Activate this skill when:
- Creating new atomic skills for the skills system
- Refactoring monolithic skills into atomic components
- Documenting specialized knowledge for reuse
- Integrating new skills into CLAUDE.md efficiently
- Establishing skill discovery patterns
- Ensuring skills remain composable and maintainable
Core Concepts
Atomic Skill Principles
Atomicity: One skill, one focus
- Single domain (e.g., "Postgres query optimization" not "All database skills")
- Clear scope boundary
- Self-contained knowledge
- Can be read and applied in isolation
Composability: Skills combine for workflows
- Reference related skills
- Support skill chaining (Skill A → Skill B → Skill C)
- Work together for complex tasks
- No circular dependencies
Discoverability: a name somebody can guess
Two things find a skill and they are not the same thing. An agent matches on the description — so the description says when the skill applies and when it does not. A person types the name — so the name has to be guessable by someone who has never seen it.
Guessable means a closed vocabulary. mcp-builder and skill-creator both
exist here, which means neither is guessable: an agent looking for the one that
makes a thing has to try both words and hope.
The shape: <subject>-<act>, two words.
One word only where the skill is its subject and there is no act — a product
or a standard, like hanzo-base or anti-slop. Never three; a third word is
almost always a category, and categories are what the index is for.
The acts. One word each, and no synonyms.
| Act | Use | Never |
|---|---|---|
| Bring something onto this stack | port |
migrate, convert, adopt, copy |
| Make one from nothing | build |
create, builder, creator, scaffold, generate |
| Check one behaves | test |
testing, qa, validate, verify |
| Judge one's quality | review |
audit, critique, lint |
| Ship one | deploy |
deployment, release, publish, ship |
| Decide what to do | plan |
planning, discovery, research |
port rather than copy is not a coin toss. A port keeps what the target
system already does right and reproduces the source's behaviour and
appearance; copying says to take the implementation, which is the thing these
skills tell you not to do.
The test before you name it. Could somebody who knows the rule above, and has never seen your skill, write down its name correctly on the first try? If not, the name is wrong — not the reader.
- Category directories (
cicd/,infrastructure/) group, they do not name - Keywords in "When to Use This Skill" are what the matcher reads
- Referenced in _INDEX.md
Efficiency: Optimal size and structure
- Target: 250-400 lines
- Maximum: 500 lines (split if larger)
- Minimum: 150 lines (merge if smaller)
- Scannable sections with clear headers
Integration Philosophy
CLAUDE.md stays lean:
- Don't list every skill individually
- Use category summaries with counts
- Provide Quick Category Reference for pattern matching
- Target: Keep CLAUDE.md under 800 lines
_INDEX.md is comprehensive:
- Complete skill catalog with tables
- Discovery patterns (by tech, task, domain)
- Skill combination examples (workflows)
- Quick reference for common tasks
Skill Structure Template
Required Sections
Every atomic skill must include:
# [Skill Name]
**Scope**: One-line description of what this skill covers
**Lines**: ~[estimated line count]
**Last Updated**: YYYY-MM-DD
## When to Use This Skill
Activate this skill when:
- [Specific trigger 1]
- [Specific trigger 2]
- [Specific trigger 3]
- [Specific trigger 4]
- [Specific trigger 5]
## Core Concepts
### [Concept 1]
**[Sub-concept]**:
- Key point 1
- Key point 2
- Key point 3
### [Concept 2]
[Explanation with code examples where applicable]
---
## Patterns
### [Pattern 1 Name]
```[language]
// Code example
// With explanatory comments
When to use:
- Condition 1
- Condition 2
[Pattern 2 Name]
// Another example
Benefits:
- Benefit 1
- Benefit 2
Quick Reference
[Reference Table or Command List]
Command/Pattern | Use Case | Example
-------------------|--------------------|---------
[item] | [when to use] | [example]
[Key Guidelines]
✅ DO: [Good practice]
✅ DO: [Good practice]
❌ DON'T: [Anti-pattern]
❌ DON'T: [Anti-pattern]
Anti-Patterns
❌ [Anti-pattern 1]: [Why it's bad] ✅ [Correct approach]
❌ [Anti-pattern 2]: [Why it's bad] ✅ [Correct approach]
Related Skills
related-skill-1.md- [How it relates]related-skill-2.md- [How it relates]related-skill-3.md- [How it relates]
Last Updated: YYYY-MM-DD Format Version: 1.0 (Atomic)
### Section Guidelines
**"When to Use This Skill"**:
- 5-8 specific activation triggers
- Action-oriented ("Implementing X", "Debugging Y")
- Helps with skill discovery
- Should match _INDEX.md "Use When" column
**"Core Concepts"**:
- Foundational knowledge
- Mental models and frameworks
- 2-4 major concepts
- Each concept 3-5 sub-points
**"Patterns"**:
- Practical code examples
- Real-world scenarios
- Copy-paste ready snippets
- Commented for clarity
**"Quick Reference"**:
- Cheat sheet format
- Tables, lists, command references
- Scannable at a glance
- Emergency lookup section
**"Anti-Patterns"**:
- Common mistakes
- What NOT to do
- Why it's wrong + correct alternative
- Learn from common errors
**"Related Skills"**:
- 3-6 related atomic skills
- How they connect (workflow, dependency, alternative)
- Enables skill composition
---
## Creating a New Skill
### Step 1: Scope Definition
**Ask these questions**:
1. What's the **single focus** of this skill?
2. Can I describe it in **one line**?
3. Is it **too broad**? (Split into multiple skills)
4. Is it **too narrow**? (Merge with related skill)
5. What are **5 triggers** for activating this skill?
**Example scoping**:
- ❌ "Database development" → Too broad
- ❌ "PostgreSQL EXPLAIN ANALYZE" → Too narrow
- ✅ "Postgres query optimization" → Just right (indexes, EXPLAIN, query rewriting)
### Step 2: Research and Outline
**Gather information**:
- Official documentation
- Best practices articles
- Common patterns from experience
- Anti-patterns and gotchas
**Create outline**:
```markdown
# [Skill Name]
## Core Concepts (2-4 concepts)
- Concept 1: [Mental model]
- Concept 2: [Key principle]
## Patterns (4-8 patterns)
- Pattern 1: [Common use case]
- Pattern 2: [Alternative approach]
## Quick Reference
- Commands/APIs
- Decision matrix
## Anti-Patterns (3-5)
- Common mistake 1
- Common mistake 2
## Related Skills (3-6)
- Skill A (workflow predecessor)
- Skill B (alternative)
- Skill C (next step)
Step 3: Write Content
Writing guidelines:
- Use active voice ("Configure X" not "X is configured")
- Code examples for every pattern
- Clear comments in code
- Real-world context ("When building REST APIs...")
- Concrete over abstract (show don't tell)
Code example format:
// ❌ Bad: No error handling
async function fetchUser(id: string) {
const response = await fetch(`/api/users/${id}`);
return response.json();
}
// ✅ Good: Proper error handling
async function fetchUser(id: string) {
const response = await fetch(`/api/users/${id}`);
if (!response.ok) {
throw new Error(`Failed to fetch user: ${response.status}`);
}
return response.json();
}
Balance depth vs brevity:
- Go deep on one topic
- Keep related topics as references to other skills
- Aim for 250-400 lines
- If over 500 lines → split into 2 skills
Step 4: Test Readability
Read through and check:
- Can I scan this in 2 minutes?
- Are code examples copy-paste ready?
- Is Quick Reference section useful?
- Do headers clearly segment content?
- Are anti-patterns concrete?
- Do related skills make sense?
Readability test:
- Remove yourself from the skill for 1 day
- Come back and try to use it cold
- Can you find what you need quickly?
Step 5: Integration with System
Add to _INDEX.md:
- Add skill to category table:
| `new-skill.md` | Brief description of use case | ~300 |
- Update category workflow section:
**Common workflows:**
- New workflow: `new-skill.md` → `existing-skill.md`
- Add to discovery patterns:
**New Category**: Search `new-*.md`, `category-*.md`
- Create skill combination example (if workflow-worthy):
### New Workflow Name
1. `skill-1.md` - Purpose
2. `new-skill.md` - Purpose
3. `skill-3.md` - Purpose
- Add to Quick Reference Table:
| New task | new-skill.md, related-skill.md | 1→2 |
- Update total counts:
**Total Skills**: [new count]
### By Category Breakdown
- [Category]: [new count] skills
Update CLAUDE.md (Section 9 only):
- Update category summary (if new category):
**Advanced Categories** ([new count] skills):
- **New Category** ([count]): Skill 1, Skill 2, Skill 3
- Update Quick Category Reference:
New Category: new-*.md ([count]) | category-*.md ([count])
- Update discovery patterns (if new pattern):
ls skills/new-*.md
ls skills/category/*.md
- Update total in header:
### Skills Catalog ([new total] Total)
DO NOT:
- ❌ List individual skills in CLAUDE.md (use summaries)
- ❌ Add more than 10 lines to CLAUDE.md per skill
- ❌ Duplicate content between CLAUDE.md and _INDEX.md
- ❌ Exceed 800 lines in CLAUDE.md
Step 6: File Organization
Naming convention:
- Lowercase with hyphens:
postgres-query-optimization.md - Technology prefix:
postgres-*.md,react-*.md - Pattern:
[tech]-[focus].md
Directory structure:
skills/
api/ # Category directories for cohesion
rest-api-design.md
graphql-schema-design.md
cicd/
github-actions-workflows.md
ci-testing-strategy.md
database/ # Or flat with prefix
postgres-query-optimization.md
postgres-*.md # Or prefixed files at root
react-*.md
skill-creation.md # Meta skills at root
_INDEX.md # Always at root
Category vs flat:
- Use category directories for 4+ related skills
- Use prefix pattern for 2-3 related skills
- Keep meta/workflow skills at root (beads-*, skill-creation)
Integration Checklist
Before considering a skill "complete":
Skill file itself:
- Title matches filename
- Scope is one clear line
- Line count is accurate (~actual count)
- "When to Use This Skill" has 5+ triggers
- Core Concepts section (2-4 concepts)
- Patterns section with code examples (4-8 patterns)
- Quick Reference section (tables/commands)
- Anti-Patterns section (3-5 patterns)
- Related Skills section (3-6 skills)
- Last Updated date is current
- Format Version is specified
- Total lines: 250-400 (max 500)
_INDEX.md updates:
- Added to category table with description
- Updated category workflow section
- Added to discovery patterns (if new pattern)
- Created skill combination example (if applicable)
- Added to Quick Reference Table (if common task)
- Updated total skills count
- Updated category breakdown counts
CLAUDE.md updates (Section 9 only):
- Updated category summary with new count
- Updated Quick Category Reference (if needed)
- Updated discovery patterns (if new pattern)
- Updated total skills count in header
- Verified CLAUDE.md still under 800 lines
- No individual skill descriptions added (summaries only)
Testing:
- Skill is discoverable via pattern search
- Skill is scannable (can read in 2-3 minutes)
- Code examples are copy-paste ready
- Related skills references are accurate
- Skill fits into documented workflows
Best Practices
Writing Style
Be concise:
❌ "When you are working on implementing authentication and authorization
for your API endpoints, you should consider using this skill."
✅ "Implementing API authentication and authorization"
Be specific:
❌ "This helps with databases"
✅ "Optimizing slow Postgres queries with EXPLAIN plans and indexes"
Use examples:
❌ "Configure your settings appropriately"
✅
```typescript
// Configure connection pool
const pool = new Pool({
max: 20, // Maximum connections
idleTimeoutMillis: 30000,
connectionTimeoutMillis: 2000,
});
### Code Examples
**Format consistently**:
- Language identifier in code fence
- Comments explaining key lines
- Real-world variable names (not foo/bar)
- Show both bad ❌ and good ✅ patterns
- Keep examples under 30 lines
**Bad example**:
```javascript
// No context, unclear purpose
function process(x) {
return x.map(y => y * 2);
}
Good example:
// Transform user data for API response
interface User {
id: string;
email: string;
password: string; // Never send to client
}
function sanitizeUser(user: User) {
const { password, ...safeUser } = user;
return safeUser; // Only id and email
}
Organization
Front-load important info:
- "When to Use This Skill" - Helps discovery
- "Core Concepts" - Mental models first
- "Patterns" - Practical examples
- "Quick Reference" - Emergency lookup
- "Anti-Patterns" - Learn from mistakes
- "Related Skills" - Next steps
Use visual hierarchy:
#for skill title##for major sections###for sub-sections**Bold**for emphasis`code`for commands/filenames- Horizontal rules
---between major sections
Maintenance
Keep skills current:
- Update "Last Updated" date when changing content
- Review annually for outdated patterns
- Add new patterns as they emerge
- Archive deprecated patterns to Anti-Patterns
Version control:
- Commit skills to git
- Use descriptive commit messages
- Tag major skill system versions
- Track CLAUDE.md changes separately
Common Patterns
Pattern 1: Create Category Skill Set
Scenario: Adding 5 skills for new technology (Kubernetes)
Steps:
- Create directory:
mkdir skills/kubernetes/ - Create 5 skills with consistent naming:
kubernetes-basics.mdkubernetes-deployments.mdkubernetes-services.mdkubernetes-security.mdkubernetes-troubleshooting.md
- Add category to _INDEX.md with table
- Update CLAUDE.md Section 9 with category summary
- Add discovery pattern:
ls skills/kubernetes/*.md
Pattern 2: Split Monolithic Skill
Scenario: Existing skill too large (800 lines)
Steps:
- Identify 2-3 distinct sub-topics
- Create separate skills for each
- Extract content to new files
- Update Related Skills to cross-reference
- Archive old monolithic skill to
_archive/ - Update _INDEX.md and CLAUDE.md
Example:
- Before:
database-complete.md(800 lines) - After:
postgres-query-optimization.md,postgres-migrations.md,postgres-schema-design.md
Pattern 3: Add Skill to Existing Category
Scenario: One new skill for existing category
Steps:
- Create skill file in category directory or with prefix
- Add row to _INDEX.md category table
- Update category workflow section if needed
- Increment count in CLAUDE.md category summary
- Update total counts in both files
Anti-Patterns
❌ Monolithic skills: 1000+ line skills covering entire domains ✅ Split into 3-5 atomic skills (250-400 lines each)
❌ Listing all skills in CLAUDE.md: Bloats the main config ✅ Use category summaries and Quick Category Reference
❌ No discovery patterns: Skills hard to find ✅ Consistent naming, category directories, _INDEX.md search patterns
❌ Copy-paste from docs: Raw documentation dumps ✅ Curated patterns, real-world examples, opinionated best practices
❌ Missing code examples: Abstract explanations only ✅ Every pattern has code example with comments
❌ No Related Skills: Skills exist in isolation ✅ Link 3-6 related skills for composability
❌ Inconsistent structure: Each skill different format ✅ Follow template structure (When/Core/Patterns/Quick/Anti/Related)
❌ Stale content: Skills never updated ✅ Review and update annually, track "Last Updated" date
Quick Reference
New Skill Checklist
1. Define scope (one-line description, 5 triggers)
2. Research content (docs, best practices)
3. Create outline (Core/Patterns/Quick/Anti/Related)
4. Write content (250-400 lines, code examples)
5. Test readability (scan in 2 minutes)
6. Add to _INDEX.md (table, workflows, patterns)
7. Update CLAUDE.md Section 9 (summary, counts)
8. Verify CLAUDE.md still < 800 lines
9. Commit to git
File Structure Quick Copy
# Skill Name
**Scope**: One-line description
**Lines**: ~300
**Last Updated**: 2025-10-18
## When to Use This Skill
- Trigger 1
- Trigger 2
## Core Concepts
### Concept 1
## Patterns
### Pattern 1
## Quick Reference
## Anti-Patterns
## Related Skills
---
**Last Updated**: 2025-10-18
**Format Version**: 1.0 (Atomic)
CLAUDE.md Impact Budget
Adding 1 skill to existing category:
_INDEX.md: +1 line (table row)
CLAUDE.md: +0 lines (increment count in summary)
Adding new category (5 skills):
_INDEX.md: +40 lines (section with table)
CLAUDE.md: +2 lines (category summary + quick ref)
Current budget:
CLAUDE.md: 678/800 lines (122 lines remaining)
Can add ~60 skills before hitting limit (at current efficiency)
Related Skills
beads-workflow.md- Managing skill creation as tracked workbeads-context-strategies.md- Managing context during large skill creationfrontend/nextjs-seo.md- Example of well-structured atomic skilltesting/performance-testing.md- Example of comprehensive patterns sectiondatabase/postgres-query-optimization.md- Example of code-heavy skill
Last Updated: 2025-10-18 Format Version: 1.0 (Atomic)