Skill Builder

Build production-quality Skills for Claude Code with proper structure, discoverable descriptions, and best practices.

Quick Reference

Description Formula: [What it does] + [When to use it] + [Trigger terms users say]

Name Rules: Lowercase letters, numbers, hyphens only; max 64 characters; no spaces

Description Rules: Max 1024 characters; must be specific with trigger terms

The Skill Creation Workflow

Phase 1: Requirements Gathering

Use AskUserQuestion to understand what they need:

What should the Skill do?

• What capability or expertise should it provide?

• What tasks should it help with?

When should it activate?

• What scenarios or contexts?

• What words/phrases would users say?

• What file types or operations?

Scope decision

• Personal Skill (~/.claude/skills/) - just for this user

• Project Skill (.claude/skills/) - shared with team via git

Structure complexity

• Single file (simple instructions/examples)

• Multi-file (scripts, templates, extensive docs)

Tool restrictions

• Full access (default)

• Restricted (allowed-tools field for read-only or limited scope)

Phase 2: Description Crafting

The description determines discoverability. Use this proven formula:

[Specific operations] + [When to use] + [Trigger terms]

Example walkthrough:

• ❌ "Helps with documents" (too vague)

• ✅ "Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction."

Key elements:

• Specific operations: List concrete actions (extract, analyze, generate, validate)

• When to use: Scenarios and contexts (when working with X, during Y, for Z tasks)

• Trigger terms: Exact words users would say (PDF, forms, commit message, data analysis)

See examples/descriptions.md for more patterns.

Phase 3: Name Validation

Validate and format the name:

• Convert to lowercase

• Replace spaces with hyphens

• Remove invalid characters (only allow: a-z, 0-9, -)

• Ensure max 64 characters

• Make it descriptive but concise

Examples:

• "My PDF Tool" → "my-pdf-tool"

• "Code Reviewer!!!" → "code-reviewer"

• "data_analysis" → "data-analysis"

Phase 4: Structure Planning

Single file when:

• Instructions and examples fit comfortably in one file

• No scripts or utilities needed

• Straightforward workflow

Multi-file when:

• Extensive documentation (split into reference.md)

• Scripts or utilities needed (scripts/ directory)

• Templates or boilerplate (templates/ directory)

• Many examples (examples.md)

Recommended structure for complex Skills:

skill-name/ ├── SKILL.md # Core instructions (loaded first) ├── reference.md # Detailed API/reference (loaded if needed) ├── examples.md # Additional examples (loaded if needed) ├── scripts/ # Utility scripts │ ├── helper.py │ └── process.sh └── templates/ # Template files └── template.txt

Phase 5: Implementation

Create the directory

Personal Skill

mkdir -p ~/.claude/skills/skill-name

Project Skill

mkdir -p .claude/skills/skill-name

Multi-file structure

mkdir -p ~/.claude/skills/skill-name/{templates,scripts,examples}

Write SKILL.md

Template structure:

name: skill-name description: [Use the formula from Phase 2] allowed-tools: Read, Grep, Glob # Optional: only if restricting tools

Skill Name

Brief introduction explaining what this Skill does.

Quick Start

Provide the most common use case with a concrete example.

Instructions

Step-by-step guidance for Claude:

1. [First step with specific actions]
2. [Second step with expected behavior]
3. [Continue pattern]

Examples

Show concrete code examples:

# Example code that demonstrates usage

Best Practices

- Key principle or pattern

- Important consideration

- Common pitfall to avoid

Requirements

List any dependencies:

pip install required-package

#### Add supporting files if multi-file

Reference from SKILL.md:
```markdown
For detailed API reference, see [reference.md](reference.md).

Use the helper script:
```bash
python scripts/helper.py input.txt

### Phase 6: Validation

Before finalizing, check:

- [ ] Description follows formula (what + when + triggers)
- [ ] Description under 1024 characters
- [ ] Name is lowercase-with-hyphens, under 64 chars
- [ ] YAML has opening and closing `---`
- [ ] YAML uses spaces not tabs
- [ ] Instructions are clear and actionable
- [ ] Examples are concrete and tested
- [ ] Dependencies are documented
- [ ] Tool restrictions (if any) are appropriate

See [reference/validation-checklist.md](reference/validation-checklist.md) for complete checklist.

### Phase 7: Testing

1. **Restart Claude Code** (required for Skills to load)

2. **Test discovery**:
   - Ask using trigger terms from your description
   - Verify Skill activates automatically
   - Try variations of trigger phrases

3. **Test workflow**:
   - Follow instructions as Claude
   - Verify all examples work
   - Check edge cases

4. **Debug if needed**:
   ```bash
   # Check Skill was loaded
   # Ask: "What Skills are available?"

   # View Skill file
   cat ~/.claude/skills/skill-name/SKILL.md

   # Check for YAML syntax errors
   claude --debug

Common Issues and Solutions

Issue: Skill doesn't activate

Causes:

- Description too vague

- Trigger terms don't match user's words

- YAML syntax error

- Didn't restart Claude Code

Solutions:

- Make description more specific with exact trigger terms

- Add more synonyms and related terms

- Validate YAML (check --- delimiters, spaces not tabs)

- Restart Claude Code

Issue: Skill activates when it shouldn't

Causes:

- Description too broad

- Overlapping with other Skills

Solutions:

- Narrow description scope

- Add specific context (file types, operations)

- Consider splitting into focused Skills

Issue: YAML syntax errors

Common mistakes:

- Missing opening ---
 (line 1)

- Missing closing ---
 (before Markdown content)

- Using tabs instead of spaces

- Unquoted strings with special characters

Fix:

---
name: skill-name
description: Description text here
---

# Markdown starts here

Iteration and Improvement

After using a Skill, improve it:

- Track activation patterns: Does it activate when expected?

- Gather feedback: What's confusing or missing?

- Refine description: Add trigger terms from actual usage

- Expand examples: Add real scenarios encountered

- Update instructions: Clarify ambiguous steps

Educational Principles

When creating Skills, remember:

Why descriptions matter: Claude uses them for discovery. Vague descriptions = never activated.

Why multi-file structure works: Progressive loading. Claude reads SKILL.md first, supporting files only when needed. Keeps context focused.

Why tool restrictions are powerful: Creates safe, focused Skills. Read-only analysis Skills can't accidentally modify files.

Why trigger terms are crucial: Users don't know your Skill exists. They ask questions naturally. Trigger terms bridge their words to your Skill.

Quick Templates

Basic Skill template: templates/basic-skill.md

Advanced multi-file template: templates/advanced-skill.md

Description examples: examples/descriptions.md

Tips for Great Skills

- Be specific in descriptions - exact operations, file types, scenarios

- Include trigger synonyms - users say things differently

- Start simple, expand later - single file first, add complexity when needed

- Test with real requests - use actual words users would say

- Document dependencies clearly - don't assume packages are installed

- Provide concrete examples - show don't tell

- Make instructions actionable - specific steps, not vague guidance

- Consider scope carefully - personal for experimentation, project for team

- Use tool restrictions wisely - read-only Skills for analysis/review

- Iterate based on usage - refine trigger terms from real activation patterns

Next Steps

After creating a Skill:

- Share with team (if project Skill, commit to git)

- Document in project CLAUDE.md if it's a pattern others should know

- Create related Skills for connected workflows

- Consider packaging multiple Skills as a plugin for wider distribution

Remember: Great Skills have specific descriptions with trigger terms. That's the difference between a Skill that gets used and one that never activates.