Creating a New Skill

Follow this workflow when creating a new Claude Code Skill.

0) Fetch latest best practices (REQUIRED)

Before writing any skill content, you MUST fetch and read the latest documentation:

1. •Skills overview: https://code.claude.com/docs/en/skills
2. •Best practices: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices

Use WebFetch to retrieve these pages and extract key guidelines before proceeding.

1) Check if skill should merge into existing skill (REQUIRED)

Before creating a new skill, first check if the content belongs in an existing skill.

Review existing skills

ls -la .claude/skills/

Decision criteria for merging

MERGE into existing skill as a rule if:

• •Topic is closely related to an existing skill's domain
• •Content would be a sub-topic of an existing skill
• •Similar workflows or patterns already exist
• •Adding as a rule keeps related knowledge together

CREATE new skill if:

• •Topic is distinct and doesn't fit any existing category
• •Content is substantial enough to warrant standalone skill
• •Different trigger keywords and use cases
• •Would make existing skill too large or unfocused

Token optimization considerations

When to split existing skills:

Skills should be split when they become too large, causing unnecessary token consumption on every load. Use these criteria:

🚨 SPLIT if any of these apply:

• •File size: Reference file >10 KB or >1000 lines
• •Usage frequency mismatch: Topics used in very different scenarios
• •Independent workflows: Topics don't share common patterns
• •Specific trigger words: Topic has distinct keywords that rarely overlap

✅ KEEP TOGETHER if:

• •High correlation: Topics frequently used together (>50% overlap)
• •Shared concepts: Common patterns, terminology, or workflows
• •Small files: All reference files <5 KB each
• •Natural grouping: User thinks of topics as related

Token savings formula:

Token Savings = (Skill_Size × Probability_Not_Needed) - Split_Overhead

Where:
- Skill_Size: Total tokens in skill (SKILL.md + all references)
- Probability_Not_Needed: % of tasks that don't need this topic
- Split_Overhead: ~500-1000 tokens (new SKILL.md + metadata)

Real-world examples from our codebase:

Splitting strategies:

1. •

   Conservative split (safe, minimal disruption):

   • •Split only the largest, most independent file
   • •Keep related topics together
   • •Example: Split 34 KB Sentry analysis from 43 KB workflows
2. •

   Moderate split (balanced):

   • •Split 3-5 distinct topics into separate skills
   • •Keep core patterns together
   • •Example: Split date, i18n, error-handling, cross-platform, code-quality
3. •

   Aggressive split (maximum optimization):

   • •Each major topic becomes its own skill
   • •Only keep truly inseparable content together
   • •Use when: Very large skill (>50 KB), low topic correlation

Example Skill Categories

Merging workflow

If merging into existing skill:

1. •

   Add as a rule file:

   code

   .claude/skills/<existing-skill>/
   ├── SKILL.md                          # Update quick reference
   └── references/rules/
       └── <new-topic>.md                # Add detailed content here
   

2. •

   Update the main SKILL.md:

   • •Add entry to quick reference table
   • •Add brief summary section
   • •Link to the new rule file
3. •

   Example merge:

   markdown

   ## Quick Reference
   
   | Feature | Guide | Key Files |
   |---------|-------|-----------|
   | Existing topic | [existing.md](references/rules/existing.md) | `path/to/files` |
   | **New topic** | [new-topic.md](references/rules/new-topic.md) | `path/to/files` |  <!-- Add this -->
   

Splitting workflow

If splitting an existing skill:

1. •

   Analyze current skill:

   bash

   # Check file sizes
   ls -lh .claude/skills/<skill-name>/references/rules/
   wc -l .claude/skills/<skill-name>/references/rules/*.md
   

2. •

   Identify split candidates:

   • •Files >10 KB or >1000 lines
   • •Topics with distinct trigger words
   • •Workflows used independently
3. •

   Create new skill directories:

   bash

   mkdir -p .claude/skills/<new-skill-1>/references/rules
   mkdir -p .claude/skills/<new-skill-2>/references/rules
   

4. •

   Move files (git tracks as rename):

   bash

   mv .claude/skills/<old-skill>/references/rules/<topic>.md \
      .claude/skills/<new-skill>/references/rules/
   

5. •

   Create SKILL.md for each new skill:

   • •Write focused description with specific trigger words
   • •Add Quick Reference section
   • •Include Related Skills section
6. •

   Update original skill SKILL.md:

   • •Remove split topics from Quick Reference
   • •Update Related Skills to point to new skills
7. •

   Update cross-references:

   bash

   # Find all skills that reference the old skill
   grep -r "old-skill" .claude/skills/*/SKILL.md
   
   # Update each reference to point to appropriate new skill
   

8. •

   Commit with clear message:

   bash

   git add -A .claude/skills/
   git commit -m "refactor: split <old-skill> into focused skills"
   

2) Gather requirements (for new skills)

If creating a new skill, ask the user:

• •What task should this skill automate?
• •What triggers should activate this skill? (keywords, file types, contexts)
• •Should it be project-scoped (.claude/skills/) or personal (~/.claude/skills/)?
• •What tools does it need? (Read, Grep, Glob, Bash, WebFetch, Write, etc.)

3) Create skill structure

Standard structure (recommended)

.claude/skills/<skill-name>/
├── SKILL.md                    # Main entry with quick reference (required)
└── references/
    └── rules/
        ├── topic-1.md          # Detailed guide for topic 1
        ├── topic-2.md          # Detailed guide for topic 2
        └── topic-3.md          # Detailed guide for topic 3

Simple structure (for single-topic skills)

.claude/skills/<skill-name>/
└── SKILL.md                    # All content in one file

SKILL.md template

---
name: skill-name
description: Brief description of what this Skill does and when to use it. Include specific trigger keywords.
allowed-tools: Read, Grep, Glob  # Optional: restrict tool access
---

# Skill Title

Brief overview.

## Quick Reference

| Topic | Guide | Key Files |
|-------|-------|-----------|
| Topic 1 | [topic-1.md](references/rules/topic-1.md) | `path/to/files` |
| Topic 2 | [topic-2.md](references/rules/topic-2.md) | `path/to/files` |

## Topic 1 Summary

See: [references/rules/topic-1.md](references/rules/topic-1.md)

**Key points:**
- Point 1
- Point 2

## Topic 2 Summary

See: [references/rules/topic-2.md](references/rules/topic-2.md)

**Key points:**
- Point 1
- Point 2

## Related Skills

- `/related-skill-1` - Description
- `/related-skill-2` - Description

4) Apply best practices checklist

Naming

• • Use descriptive names: feature-guides, dev-workflows, sentry
• • Max 64 chars, lowercase letters/numbers/hyphens only
• • No reserved words: "anthropic", "claude"
• • Consider project-specific prefix if needed for organization

Description

• • Write in third person ("Processes...", not "I can help...")
• • Include what it does AND when to use it
• • Include specific trigger keywords users would say
• • Max 1024 chars

Content structure

• • Main SKILL.md has quick reference table linking to rules
• • Detailed content goes in references/rules/*.md
• • Each rule file is self-contained and focused
• • Keep SKILL.md body under 500 lines
• • Use Unix-style paths (forward slashes)

Organization

• • Group related topics into one skill with multiple rules
• • Use consistent formatting across all rules
• • Include "Related Skills" section for cross-references
• • Add checklist for complex workflows

5) Output the skill

After gathering requirements and applying best practices:

1. •Create the skill directory with references/rules/ structure
2. •Write SKILL.md with quick reference table
3. •Add rule files for each topic
4. •Summarize what was created
5. •Run token analysis to verify optimization (REQUIRED)

Token Analysis (Self-Check)

ALWAYS run after creating or modifying skills:

# Run token analysis
python3 development/skills-analysis/analyze-skills-tokens.py --sort-by-size

# Check your new skill's token count
python3 development/skills-analysis/analyze-skills-tokens.py --detailed | grep -A 5 "your-skill-name"

Verification checklist:

• • New skill is <5,000 tokens (ideal)
• • If >5,000 tokens: Topics are highly correlated (>50% usage together)
• • If >10,000 tokens: Plan immediate split
• • SKILL.md has Quick Reference (avoid forcing full file load)
• • No duplicate content across skills

Action based on results:

See development/skills-analysis/SKILLS-TOKEN-MONITORING.md for detailed guidance.

Example: Skill with multiple rules

.claude/skills/feature-guides/
├── SKILL.md
└── references/rules/
    ├── adding-features.md
    ├── adding-events.md
    ├── notification-system.md
    └── page-and-route.md

SKILL.md content:

---
name: feature-guides
description: Feature development guides. Use when adding new features, events, notifications, pages, or routes.
---

# Feature Development Guides

## Quick Reference

| Feature | Guide | Key Files |
|---------|-------|-----------|
| Add new feature | [adding-features.md](references/rules/adding-features.md) | `packages/core/src/features/` |
| Add events | [adding-events.md](references/rules/adding-events.md) | `packages/shared/types/events.ts` |

## Adding New Features

See: [references/rules/adding-features.md](references/rules/adding-features.md)

**Key steps:**
1. Implement core logic
2. Add configuration
3. Update UI components

Anti-patterns to avoid

Structure & Organization

• •❌ Creating new skill when content fits existing category
• •❌ Putting all content in SKILL.md (use references/rules for detail)
• •❌ Deeply nested file references (keep one level deep)

Content Quality

• •❌ Vague descriptions like "Helps with documents"
• •❌ Multiple approaches without clear defaults
• •❌ Over-explaining what Claude already knows
• •❌ Missing trigger keywords in description

Token Optimization Anti-patterns

• •❌ Keeping bloated skills: Not splitting when files exceed 10 KB
• •❌ Over-splitting: Creating separate skills for highly correlated topics
• •❌ Ignoring usage patterns: Not considering which topics are used together
• •❌ Vague trigger words: Using generic triggers that cause unnecessary loading
• •❌ No Quick Reference: Forcing full file load instead of showing summary first
• •❌ Duplicate content: Copying content across skills instead of cross-referencing

Examples of Good vs Bad Splitting

❌ BAD: Over-splitting

date-format-display
date-format-parse
date-format-locale

Problem: These are always used together, split overhead > savings

✅ GOOD: Focused skill

date-formatting
├── SKILL.md (Quick Reference)
└── references/rules/date-formatting.md

❌ BAD: Keeping bloated

coding-patterns (15 KB, 9 unrelated files)

Problem: Loading all patterns even when only need one

✅ GOOD: Split by independence

coding-patterns (core patterns only)
date-formatting (independent utility)
i18n (independent utility)
error-handling (independent patterns)