Skill Builder

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:

1. What should the Skill do?

   • What capability or expertise should it provide?
   • What tasks should it help with?

2. When should it activate?

   • What scenarios or contexts?
   • What words/phrases would users say?
   • What file types or operations?

3. Scope decision

   • Personal Skill (~/.claude/skills/) - just for this user
   • Project Skill (.claude/skills/) - shared with team via git

4. Structure complexity

   • Single file (simple instructions/examples)
   • Multi-file (scripts, templates, extensive docs)

5. 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:

1. Specific operations: List concrete actions (extract, analyze, generate, validate)
2. When to use: Scenarios and contexts (when working with X, during Y, for Z tasks)
3. 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:

1. Description too vague
2. Trigger terms don't match user's words
3. YAML syntax error
4. Didn't restart Claude Code

Solutions:

1. Make description more specific with exact trigger terms
2. Add more synonyms and related terms
3. Validate YAML (check --- delimiters, spaces not tabs)
4. Restart Claude Code

Issue: Skill activates when it shouldn't

Causes:

1. Description too broad
2. Overlapping with other Skills

Solutions:

1. Narrow description scope
2. Add specific context (file types, operations)
3. 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:

1. Track activation patterns: Does it activate when expected?
2. Gather feedback: What's confusing or missing?
3. Refine description: Add trigger terms from actual usage
4. Expand examples: Add real scenarios encountered
5. 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

1. Be specific in descriptions - exact operations, file types, scenarios
2. Include trigger synonyms - users say things differently
3. Start simple, expand later - single file first, add complexity when needed
4. Test with real requests - use actual words users would say
5. Document dependencies clearly - don't assume packages are installed
6. Provide concrete examples - show don't tell
7. Make instructions actionable - specific steps, not vague guidance
8. Consider scope carefully - personal for experimentation, project for team
9. Use tool restrictions wisely - read-only Skills for analysis/review
10. Iterate based on usage - refine trigger terms from real activation patterns

Next Steps

After creating a Skill:

1. Share with team (if project Skill, commit to git)
2. Document in project CLAUDE.md if it's a pattern others should know
3. Create related Skills for connected workflows
4. 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.