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:

Core Concepts

Atomic Skill Principles

Atomicity: One skill, one focus

Composability: Skills combine for workflows

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.

Efficiency: Optimal size and structure

Integration Philosophy

CLAUDE.md stays lean:

_INDEX.md is comprehensive:

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]

// 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":

"Core Concepts":

"Patterns":

"Quick Reference":

"Anti-Patterns":

"Related Skills":

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:

Step 2: Research and Outline

Gather information:

Create outline:

# [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:

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:

Step 4: Test Readability

Read through and check:

Readability test:

Step 5: Integration with System

Add to _INDEX.md:

  1. Add skill to category table:
| `new-skill.md` | Brief description of use case | ~300 |
  1. Update category workflow section:
**Common workflows:**
- New workflow: `new-skill.md` → `existing-skill.md`
  1. Add to discovery patterns:
**New Category**: Search `new-*.md`, `category-*.md`
  1. 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
  1. Add to Quick Reference Table:
| New task | new-skill.md, related-skill.md | 1→2 |
  1. Update total counts:
**Total Skills**: [new count]

### By Category Breakdown
- [Category]: [new count] skills

Update CLAUDE.md (Section 9 only):

  1. Update category summary (if new category):
**Advanced Categories** ([new count] skills):
- **New Category** ([count]): Skill 1, Skill 2, Skill 3
  1. Update Quick Category Reference:
New Category:   new-*.md ([count]) | category-*.md ([count])
  1. Update discovery patterns (if new pattern):
ls skills/new-*.md
ls skills/category/*.md
  1. Update total in header:
### Skills Catalog ([new total] Total)

DO NOT:

Step 6: File Organization

Naming convention:

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:

Integration Checklist

Before considering a skill "complete":

Skill file itself:

_INDEX.md updates:

CLAUDE.md updates (Section 9 only):

Testing:

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"
✅

// Configure connection pool const pool = new Pool({ max: 20, // Maximum connections idleTimeoutMillis: 30000, connectionTimeoutMillis: 2000, });

Code Examples

Format consistently:

Bad example:

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

  1. "When to Use This Skill" - Helps discovery
  2. "Core Concepts" - Mental models first
  3. "Patterns" - Practical examples
  4. "Quick Reference" - Emergency lookup
  5. "Anti-Patterns" - Learn from mistakes
  6. "Related Skills" - Next steps

Use visual hierarchy:

Maintenance

Keep skills current:

Version control:

Common Patterns

Pattern 1: Create Category Skill Set

Scenario: Adding 5 skills for new technology (Kubernetes)

Steps:

  1. Create directory: mkdir skills/kubernetes/
  2. Create 5 skills with consistent naming:
  1. Add category to _INDEX.md with table
  2. Update CLAUDE.md Section 9 with category summary
  3. Add discovery pattern: ls skills/kubernetes/*.md

Pattern 2: Split Monolithic Skill

Scenario: Existing skill too large (800 lines)

Steps:

  1. Identify 2-3 distinct sub-topics
  2. Create separate skills for each
  3. Extract content to new files
  4. Update Related Skills to cross-reference
  5. Archive old monolithic skill to _archive/
  6. Update _INDEX.md and CLAUDE.md

Example:

Pattern 3: Add Skill to Existing Category

Scenario: One new skill for existing category

Steps:

  1. Create skill file in category directory or with prefix
  2. Add row to _INDEX.md category table
  3. Update category workflow section if needed
  4. Increment count in CLAUDE.md category summary
  5. 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

Last Updated: 2025-10-18 Format Version: 1.0 (Atomic)