Skill Builder

This skill helps you create well-structured Claude Code Skills. Use it when the user wants to build a new skill for Claude Code.

When to Use This Skill

Invoke this skill when users:

•Want to create a new Claude Code Skill
•Ask how to build or structure a skill
•Need help with skill frontmatter or organization
•Want to validate an existing skill structure

Skill Creation Workflow

Step 1: Understand the Requirements

Ask the user these questions (use AskUserQuestion tool when appropriate):

•What will the skill do? - Get a clear description of the skill's purpose
•When should it trigger? - Understand what user requests should activate it
•What's the scope? - Is it project-specific or personal/general-purpose?
•What resources are needed? - Templates, scripts, reference data, etc.

Step 2: Determine Skill Location

Based on scope, choose the directory:

•Project-specific: .claude/skills/[skill-name]/ (within project root)
•Personal/general: ~/.claude/skills/[skill-name]/ (available everywhere)

Step 3: Create Directory Structure

Use this pattern:

code

skill-name/
├── SKILL.md           (required: main instructions)
├── REFERENCE.md       (optional: detailed reference info)
├── FORMS.md           (optional: templates and forms)
├── scripts/           (optional: executable code)
│   ├── script1.py
│   └── script2.sh
└── resources/         (optional: templates, data files)
    └── template.txt

Step 4: Write SKILL.md

The SKILL.md must follow this structure:

markdown

---
name: skill-name
description: Clear description of what this skill does and when to use it
---

# Skill Name

Main instructions for Claude go here.

## When to Use

Describe scenarios where this skill should be invoked.

## How It Works

Step-by-step instructions for Claude to follow.

## Examples

Provide examples of usage.

Frontmatter Requirements:

•name: Max 64 chars, lowercase letters/numbers/hyphens only (e.g., "excel-automation")
•
description: Non-empty, max 1024 chars, should clearly indicate when to use the skill
- •IMPORTANT: Include BOTH natural language AND technical keywords
- •Natural language: How non-technical users would describe it ("fix broken code", "save data", "put online")
- •Technical terms: Jargon that developers use ("debug", "database schema", "deploy")
- •Example: "Auto-invoked when user wants to fix broken code, not working, or crashed. Also triggers on debug, stack trace, error analysis."

Best Practices for Instructions:

•Write like an "onboarding guide for a new team member"
•Use clear, step-by-step procedures
•Include contextual examples
•Reference supporting files instead of embedding everything
•Keep instructions under 5k tokens for efficient loading
•Use progressive disclosure: reference detailed info in REFERENCE.md

Step 5: Add Supporting Files (Optional)

REFERENCE.md: Detailed technical information that Claude can read when needed

•API documentation
•Detailed specifications
•Comprehensive examples
•Technical constraints

FORMS.md: Templates and structured formats

•Form templates
•Output format examples
•Structured data patterns

scripts/: Executable code for complex operations

•Python scripts for data processing
•Shell scripts for automation
•Utilities that Claude can invoke via bash

resources/: Static files and templates

•Document templates
•Sample data
•Reference materials

Step 6: Validate the Skill

Check these requirements:

• SKILL.md exists with valid YAML frontmatter
• name is lowercase, alphanumeric with hyphens, max 64 chars
• description is clear, non-empty, max 1024 chars
• Description includes natural language keywords (not just technical jargon)
• Instructions are clear and actionable
• File references are correct
• No internet/API dependencies (Claude Code constraint)
• Only uses pre-installed packages

Run automated validation:

bash

python .validation/validate-skills.py

Validation Scoring (29 points total):

•SKILL.md exists: 1 point
•Valid frontmatter: 3 points
•Name validation: 2 points
•Description validation: 3 points
•Content structure: 5 points
•Token count <5000: 2 points
•Supporting files: 3 points
•Scripts directory: 2 points
•Industry standards: 3 points
•Examples: 2 points
•Natural language keywords: 3 points (NEW)

Passing threshold: 80% (24/29 points)

Step 7: Test the Skill

After creation:

•Verify the skill is discoverable (Claude should see it in metadata)
•Test with a sample task that should trigger it
•Ensure resources load correctly when referenced
•Check that instructions are clear and complete

Progressive Disclosure Strategy

Design skills to minimize token usage:

•
Always Loaded (Metadata): ~100 tokens
- •Just the YAML frontmatter
•
Loaded When Triggered (Instructions): <5k tokens
- •Core procedures from SKILL.md body
•
Loaded As Needed (Resources): No token cost
- •Files Claude reads via bash commands
- •Scripts Claude executes when required
- •Templates Claude accesses on demand

Common Skill Patterns

Document Generation Skill

code

doc-generator/
├── SKILL.md          (generation instructions)
├── templates/        (document templates)
└── scripts/          (formatting scripts)

Code Analysis Skill

code

code-analyzer/
├── SKILL.md          (analysis procedures)
├── REFERENCE.md      (pattern definitions)
└── scripts/          (analysis tools)

Automation Skill

code

automation-helper/
├── SKILL.md          (automation workflows)
├── FORMS.md          (configuration templates)
└── scripts/          (automation scripts)

Implementation Steps

When helping users build a skill:

•Gather Information: Use AskUserQuestion to understand requirements
•Plan Structure: Determine files needed based on complexity
•Create Directory: Make the skill directory in appropriate location
•Write SKILL.md: Create with proper frontmatter and instructions
•Add Supporting Files: Create REFERENCE.md, FORMS.md, scripts as needed
•Validate: Check all requirements are met
•Document: Explain to user how to test and use the skill
•Show Location: Provide the full path to the created skill

Validation Checklist

Before completing, verify:

• Directory created in correct location
• SKILL.md has valid frontmatter
• Name follows naming rules
• Description is clear and helpful
• Instructions are actionable
• Examples are provided
• Supporting files are organized logically
• No external dependencies
• File paths in instructions are correct

Tips for Great Skills

•Clear Descriptions: Make it obvious when Claude should use the skill
•Step-by-Step: Write procedures as numbered steps
•Examples First: Show examples before explaining
•Minimize Context: Use progressive disclosure extensively
•Self-Contained: Don't assume external resources are available
•Tested Procedures: Ensure instructions actually work
•Helpful Metadata: Write descriptions that help with discovery

Common Mistakes to Avoid

•Using uppercase or special characters in skill name
•Making descriptions too vague or too long
•Embedding all content in SKILL.md instead of using supporting files
•Referencing non-existent files
•Assuming internet access or external APIs
•Creating overly complex skills that should be split
•Forgetting to include "when to use" guidance

Reference Files

See the templates directory for:

•Basic skill template
•Advanced skill template with supporting files
•Example skills for common use cases