name: claude-skill-builder description: Interactive skill creator for Claude Code. Triggers when user mentions creating skills, building skills, skill templates, skill frontmatter, allowed-tools, or wants to scaffold a new skill. allowed-tools: Read, Write, Edit, Grep, Glob, Bash model: sonnet

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:

Description has specific trigger keywords
File is named SKILL.md (case-sensitive)
File is in correct location:
- Personal: ~/.claude/skills/category/skill-name/SKILL.md
- Project: .claude/skills/category/skill-name/SKILL.md
YAML frontmatter is valid (no tabs, proper indentation)
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

Constructeur de compétences Claude Code

Recommandé pour