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:

```language
# 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.

skill-builder