--- name: new-skill description: Creates a new Claude Code Skill following best practices. Use when the user wants to create a new skill, add a skill, or asks about writing skills for Claude Code. Fetches latest documentation before generating skill content. New skill. Create a skill. allowed-tools: Read, Grep, Glob, WebFetch, Write --- # 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 ```bash 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:** | Original | Size | Split Into | Token Savings | |----------|------|------------|---------------| | `1k-coding-patterns` | 15 KB (9 files) | 6 focused skills | 47-53% in 90% cases | | `1k-dev-workflows` | 43 KB (3 files) | 3 focused skills | 80% when not doing Sentry | **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 | Category | Skill | Merge candidates | |----------|-------|------------------| | Code quality | `code-quality` | Lint fixes, pre-commit tasks, documentation | | Sentry analysis | `sentry-analysis` | Crash reports, AppHang, ANR fixes | | Native module patches | `patching-native-modules` | iOS\/Android crash fixes, native code patches | | Error monitoring | `sentry` | Error filtering, crash configuration | | Architecture | `architecture` | Project structure, import rules | | Coding patterns | `coding-patterns` | React patterns, TypeScript conventions | | Performance | `performance` | Optimization, concurrent requests, memoization | | Error handling | `error-handling` | Try\/catch, error boundaries, user-facing errors | | State management | `state-management` | State atoms, global state | | Cross-platform | `cross-platform` | Platform-specific code | | Date formatting | `date-formatting` | Date\/time display, locale formatting | | i18n | `i18n` | Translations, locales | | Git workflow | `git-workflow` | Branching, commits, PRs | | Dev commands | `dev-commands` | Build, test, lint commands | ### Merging workflow If merging into existing skill: 1. **Add as a rule file:** ``` .claude\/skills\/\/ ├── SKILL.md # Update quick reference └── references\/rules\/ └── .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` | ``` ### Splitting workflow If splitting an existing skill: 1. **Analyze current skill:** ```bash # Check file sizes ls -lh .claude\/skills\/\/references\/rules\/ wc -l .claude\/skills\/\/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\/\/references\/rules mkdir -p .claude\/skills\/\/references\/rules ``` 4. **Move files (git tracks as rename):** ```bash mv .claude\/skills\/\/references\/rules\/.md \ .claude\/skills\/\/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 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.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.md # All content in one file ``` ### SKILL.md template ```yaml --- 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:** ```bash # 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:** | Token Count | Action | |-------------|--------| | < 2,000 | ✅ Excellent - proceed | | 2,000 - 5,000 | ✅ Good - proceed, monitor growth | | 5,000 - 10,000 | ⚠️ Review: Can topics be split? If highly correlated, proceed with Quick Reference | | > 10,000 | 🚨 Split before committing | See [development\/skills-analysis\/SKILLS-TOKEN-MONITORING.md](..\/..\/..\/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:** ```yaml --- 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) ```