Claude Code Skill Builder

Purpose

Guide users through creating well-structured Claude Code skills with proper frontmatter, clear descriptions, and effective trigger keywords. Auto-invokes when users want to create or modify skills.

When to Use

Auto-invoke when users mention:

• Creating skills - "create a skill", "make a skill", "new skill"
• Skill structure - "skill template", "skill format", "skill frontmatter"
• Trigger keywords - "skill description", "when to invoke", "trigger words"
• Skill configuration - "allowed-tools", "skill permissions", "skill model"
• Skill organization - "skill directory", "skill files", "multi-file skill"

Knowledge Base

• Official docs:

  .claude/skills/ai/claude-code/docs/code_claude_com/docs_en_skills.md

• Project guide:

  .claude/docs/creating-components.md

• Examples in repository:

  .claude/skills/

Process

1. Gather Requirements

Ask the user:

Let me help you create a Claude Code skill! I need a few details:

1. **Skill name** (lowercase-with-hyphens):
   Example: nextjs-expert, pdf-processor, git-commit-helper

2. **What does this skill do?**
   Describe the capability in 1-2 sentences.

3. **When should this skill activate?**
   List keywords users will mention: Next.js, React, API, authentication, etc.

4. **What tools will it need?**
   - Read (read files)
   - Write (create new files)
   - Edit (modify existing files)
   - Grep (search file contents)
   - Glob (find files by pattern)
   - Bash (run shell commands)

5. **Scope:**
   - Personal (`~/.claude/skills/`) - just for you
   - Project (`.claude/skills/`) - shared with team

6. **Category/subdirectory?**
   Example: data, api, frontend, backend, testing

2. Validate Input

Check the skill name:

• Must be lowercase
• Use hyphens (not underscores or spaces)
• Maximum 64 characters
• Descriptive and clear

Validate description:

• Maximum 1024 characters
• Must include trigger keywords
• Should explain both WHAT and WHEN

3. Create Skill Structure

Determine file structure:

Single file skill (simple):

skill-name/
└── SKILL.md

Multi-file skill (complex):

skill-name/
├── SKILL.md (overview and main instructions)
├── REFERENCE.md (detailed API reference)
├── EXAMPLES.md (code examples)
├── scripts/
│   └── helper.py (utility scripts)
└── templates/
    └── template.txt (file templates)

4. Generate SKILL.md

Create frontmatter with:

• name

  : Skill identifier (from user input)

• description

  : Clear description with ALL trigger keywords

• allowed-tools

  : Only tools actually needed

• model

  : sonnet (default), opus (complex), or haiku (fast)

Template structure:

---
name: skill-identifier
description: What this does and when to use it. Include keywords: keyword1, keyword2, keyword3
allowed-tools: Read, Write, Edit, Grep, Glob, Bash
model: sonnet
---

# Skill Name

## Purpose
[Clear explanation of what this skill provides]

## When to Use
- Trigger condition 1 (specific keywords)
- Trigger condition 2 (user scenarios)
- Trigger condition 3 (related topics)

## Process

### 1. Analyze the Request
[How to understand what the user wants]

### 2. Gather Context
Use tools to collect information:
- Read relevant files
- Search for patterns
- Find related code

### 3. Provide Solution
[Step-by-step approach to solving the problem]

### 4. Verify Result
[How to confirm the solution works]

## Examples

### Example 1: Basic Usage
**User request:** [Example request]
**Process:** [How skill handles it]
**Output:** [What user sees]

### Example 2: Advanced Usage
**User request:** [Complex scenario]
**Process:** [Multi-step handling]
**Output:** [Comprehensive result]

## Best Practices
- Practice 1: [Specific guidance]
- Practice 2: [Common pattern]
- Practice 3: [Expert tip]

## Common Pitfalls
- ❌ **Pitfall 1**: [What to avoid and why]
  ✅ **Instead**: [Better approach]

- ❌ **Pitfall 2**: [Common mistake]
  ✅ **Instead**: [Correct way]

## Resources
- [Official Documentation](url)
- [Related Guide](path/to/guide.md)

5. Create Supporting Files (if needed)

For complex skills, offer to create:

REFERENCE.md:

# Detailed Reference

## API Documentation
[Comprehensive API details]

## Configuration Options
[All available settings]

## Advanced Features
[Expert-level capabilities]

EXAMPLES.md:

# Examples

## Example 1: [Scenario]
[Detailed code example with explanation]

## Example 2: [Scenario]
[Another complete example]

6. Test and Validate

After creating the skill:

# Verify file exists
ls -la path/to/skill/SKILL.md

# Check file structure
cat path/to/skill/SKILL.md | head -20

# Validate YAML frontmatter
cat path/to/skill/SKILL.md | sed -n '1,/^---$/p'

Provide testing instructions:

To test your skill:
1. Restart Claude Code or start a new session
2. Mention one of your trigger keywords
3. Watch for skill activation
4. Ask: "What skills are available?" to verify it's loaded

7. Provide Next Steps

Give the user:

• Path to the created skill file
• How to test it
• How to modify it
• How to share it (if project skill)
• How to add more supporting files

Skill Size Guidelines

Warn if skill is getting large:

• ✅ Good: < 600 lines
• ⚠️ Warning: 600-900 lines (consider splitting)
• ❌ Too large: > 900 lines (must split or refactor)

If too large, suggest:

• Split into multiple focused skills
• Move detailed docs to separate reference files
• Extract examples to EXAMPLES.md
• Link to external documentation

Frontmatter Best Practices

Description Field

✅ Good descriptions:

description: Expert in Next.js App Router, server components, server actions, and React Server Components. Use when user mentions Next.js, RSC, App Router, or server-side React patterns.

❌ Bad descriptions:

description: Helps with Next.js

Allowed Tools

Only request tools you actually use:

• Don't request all tools "just in case"
• Be specific about needs
• Consider security implications

Examples:

# Read-only skill
allowed-tools: Read, Grep, Glob

# Code generator
allowed-tools: Read, Write, Grep, Glob

# Full development workflow
allowed-tools: Read, Write, Edit, Grep, Glob, Bash

Model Selection

Choose based on complexity:

• haiku

  : Fast, simple tasks, quick responses

• sonnet

  : Balanced, most skills (recommended)

• opus

  : Complex reasoning, advanced tasks

Example Skills to Reference

Point users to examples in the repository:

• .claude/skills/data/toon-formatter/skill.md

  - Data processing

• .claude/skills/ai/anthropic/skill.md

  - API expertise

• .claude/skills/ai/claude-code/skill.md

  - Tool knowledge

Common Skill Types

API/Framework Expert

Purpose: Deep knowledge of a specific framework or API Triggers: Framework name, features, patterns Tools: Read, Grep, Glob Example: Next.js expert, FastAPI expert, React expert

Code Generator

Purpose: Create boilerplate or scaffolding Triggers: "generate", "create", "scaffold", "template" Tools: Write, Read, Grep, Glob Example: Component generator, test file creator

Code Analyzer

Purpose: Review and analyze existing code Triggers: "review", "analyze", "check", "audit" Tools: Read, Grep, Glob Example: Security auditor, performance analyzer

Development Workflow

Purpose: Automate common dev tasks Triggers: Workflow steps, automation keywords Tools: Read, Write, Edit, Bash Example: Deployment helper, commit message generator

Data Processor

Purpose: Transform or analyze data Triggers: Data formats, transformation keywords Tools: Read, Write, Edit, Grep Example: TOON formatter, JSON converter

Troubleshooting

Skill Not Activating

Check:

1. Description has specific trigger keywords
2. File is named

   SKILL.md

   (case-sensitive)
3. File is in correct location:
   • Personal:

     ~/.claude/skills/category/skill-name/SKILL.md

   • Project:

     .claude/skills/category/skill-name/SKILL.md

4. YAML frontmatter is valid (no tabs, proper indentation)
5. Restart Claude Code to load new skills

Debug with:

# Verify location
ls ~/.claude/skills/*/SKILL.md
ls .claude/skills/*/SKILL.md

# Check YAML syntax
head -20 path/to/SKILL.md

# Run in debug mode
claude --debug

Skill Conflicts

If multiple skills have similar triggers:

• Make descriptions more specific
• Use distinct keywords
• Reference specific use cases
• Consider combining into one skill

File Not Found Errors

Check that referenced files exist:

# From SKILL.md, check references like [reference.md](reference.md)
ls path/to/skill/reference.md

Best Practices Summary

DO:

✅ Include specific trigger keywords in description ✅ Keep skills focused on one capability ✅ Provide clear examples in the skill ✅ Use progressive disclosure (reference external files) ✅ Test the skill before sharing ✅ Document version changes

DON'T:

❌ Make descriptions too vague ❌ Try to handle everything in one skill ❌ Request unnecessary tools ❌ Skip examples ❌ Forget to test activation triggers ❌ Go over 900 lines without splitting

Resources

• Official Skill Docs:

  .claude/skills/ai/claude-code/docs/code_claude_com/docs_en_skills.md

• Anthropic Skill Guide: https://docs.claude.com/en/docs/agents-and-tools/agent-skills/
• Project Component Guide:

  .claude/docs/creating-components.md

• Skill Examples:

  .claude/skills/

  directory