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: Pattern-based finding

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)