Skill Builder What This Skill Does Creates production-ready Claude Code Skills with proper YAML frontmatter, progressive disclosure architecture, and complete file$folder structure. This skill guides you through building skills that Claude can autonomously discover and use across all surfaces (Claude.ai, Claude Code, SDK, API). Prerequisites Claude Code 2.0+ or Claude.ai with Skills support Basic understanding of Markdown and YAML Text editor or IDE Quick Start Creating Your First Skill
1. Create skill directory (MUST be at top level, NOT in subdirectories!)
mkdir -p ~/.claude $skills $my -first-skill
2. Create SKILL.md with proper format
cat
~/.claude $skills $my -first-skill/SKILL.md << 'EOF'
name: "My First Skill" description: "Brief description of what this skill does and when Claude should use it. Maximum 1024 characters."
My First Skill
What This Skill Does
[Your instructions here]
Quick Start
[Basic usage] EOF
3. Verify skill is detected
Restart Claude Code or refresh Claude.ai
Complete Specification 📋 YAML Frontmatter (REQUIRED) Every SKILL.md must start with YAML frontmatter containing exactly two required fields:
name : "Skill Name"
REQUIRED: Max 64 chars
description : "What this skill does
REQUIRED: Max 1024 chars
and when Claude should use it."
Include BOTH what & when
- Field Requirements
- name
- (REQUIRED):
- Type
-
- String
- Max Length
-
- 64 characters
- Format
-
- Human-friendly display name
- Usage
-
- Shown in skill lists, UI, and loaded into Claude's system prompt
- Best Practice
-
- Use Title Case, be concise and descriptive
- Examples
- :
- ✅ "API Documentation Generator"
- ✅ "React Component Builder"
- ✅ "Database Schema Designer"
- ❌ "skill-1" (not descriptive)
- ❌ "This is a very long skill name that exceeds sixty-four characters" (too long)
- description
- (REQUIRED):
- Type
-
- String
- Max Length
-
- 1024 characters
- Format
-
- Plain text or minimal markdown
- Content
-
- MUST include:
- What
- the skill does (functionality)
- When
- Claude should invoke it (trigger conditions)
- Usage
-
- Loaded into Claude's system prompt for autonomous matching
- Best Practice
- Front-load key trigger words, be specific about use cases Examples : ✅ "Generate OpenAPI 3.0 documentation from Express.js routes. Use when creating API docs, documenting endpoints, or building API specifications." ✅ "Create React functional components with TypeScript, hooks, and tests. Use when scaffolding new components or converting class components." ❌ "A comprehensive guide to API documentation" (no "when" clause) ❌ "Documentation tool" (too vague) YAML Formatting Rules
✅ CORRECT: Simple string
name : "API Builder" description : "Creates REST APIs with Express and TypeScript."
✅ CORRECT: Multi-line description
name : "Full-Stack Generator" description : "Generates full-stack applications with React frontend and Node.js backend. Use when starting new projects or scaffolding applications."
✅ CORRECT: Special characters quoted
name : "JSON:API Builder" description : "Creates JSON:API compliant endpoints: pagination, filtering, relationships."
❌ WRONG: Missing quotes with special chars
name : API : Builder
YAML parse error!
❌ WRONG: Extra fields (ignored but discouraged)
name : "My Skill" description : "My description" version : "1.0.0"
NOT part of spec
author : "Me"
NOT part of spec
tags : [ "dev" , "api" ]
NOT part of spec
- Critical
-
- Only
- name
- and
- description
- are used by Claude. Additional fields are ignored.
- 📂 Directory Structure
- Minimal Skill (Required)
- ~/.claude$skills/ # Personal skills location
- └── my-skill/ # Skill directory (MUST be at top level!)
- └── SKILL.md # REQUIRED: Main skill file
- IMPORTANT
-
- Skills MUST be directly under
- ~/.claude$skills/[skill-name]/
- .
- Claude Code does NOT support nested subdirectories or namespaces!
- Full-Featured Skill (Recommended)
- ~/.claude$skills/
- └── my-skill/ # Top-level skill directory
- ├── SKILL.md # REQUIRED: Main skill file
- ├── README.md # Optional: Human-readable docs
- ├── scripts/ # Optional: Executable scripts
- │ ├── setup.sh
- │ ├── validate.js
- │ └── deploy.py
- ├── resources/ # Optional: Supporting files
- │ ├── templates/
- │ │ ├── api-template.js
- │ │ └── component.tsx
- │ ├── examples/
- │ │ └── sample-output.json
- │ └── schemas/
- │ └── config-schema.json
- └── docs/ # Optional: Additional documentation
- ├── ADVANCED.md
- ├── TROUBLESHOOTING.md
- └── API_REFERENCE.md
- Skills Locations
- Personal Skills
- (available across all projects):
- ~/.claude$skills/
- └── [your-skills]/
- Path
- :
- ~/.claude$skills/
- or
- $HOME/.claude$skills/
- Scope
-
- Available in all projects for this user
- Version Control
-
- NOT committed to git (outside repo)
- Use Case
-
- Personal productivity tools, custom workflows
- Project Skills
- (team-shared, version controlled):
/.claude$skills/ - └── [team-skills]/
- Path
- :
- .claude$skills/
- in project root
- Scope
-
- Available only in this project
- Version Control
-
- SHOULD be committed to git
- Use Case
-
- Team workflows, project-specific tools, shared knowledge
- 🎯 Progressive Disclosure Architecture
- Claude Code uses a
- 3-level progressive disclosure system
- to scale to 100+ skills without context penalty:
- Level 1: Metadata (Name + Description)
- Loaded
-
- At Claude Code startup, always
- Size
-
- ~200 chars per skill
- Purpose
-
- Enable autonomous skill matching
- Context
- Loaded into system prompt for ALL skills
name : "API Builder"
11 chars
description : "Creates REST APIs..."
~50 chars
Total: ~61 chars per skill
100 skills = ~6KB context (minimal!)
- Level 2: SKILL.md Body
- Loaded
-
- When skill is triggered$matched
- Size
-
- ~1-10KB typically
- Purpose
-
- Main instructions and procedures
- Context
- Only loaded for ACTIVE skills
API Builder
What This Skill Does [Main instructions - loaded only when skill is active]
Quick Start [Basic procedures]
- Step-by-Step Guide
- [Detailed instructions]
- Level 3+: Referenced Files
- Loaded
-
- On-demand as Claude navigates
- Size
-
- Variable (KB to MB)
- Purpose
-
- Deep reference, examples, schemas
- Context
- Loaded only when Claude accesses specific files
In SKILL.md
See
Advanced Configuration
for complex scenarios.
See
API Reference
for complete documentation.
Use template:
resources$templates$api-template.js
- Claude will load these files ONLY if needed
- Benefit
- Install 100+ skills with ~6KB context. Only active skill content (1-10KB) enters context. 📝 SKILL.md Content Structure Recommended 4-Level Structure
name : "Your Skill Name" description : "What it does and when to use it"
Your Skill Name
Level 1: Overview (Always Read First) Brief 2-3 sentence description of the skill.
Prerequisites
Requirement 1
Requirement 2
What This Skill Does 1. Primary function 2. Secondary function 3. Key benefit
Level 2: Quick Start (For Fast Onboarding)
Basic Usage ```bash
- Simplest use case
- command --option value
- Common Scenarios
- Scenario 1
-
- How to...
- Scenario 2
- How to... Level 3: Detailed Instructions (For Deep Work) Step-by-Step Guide Step 1: Initial Setup
Commands
Expected output: Success message Step 2: Configuration Configuration option 1 Configuration option 2 Step 3: Execution Run the main command Verify results Advanced Options Option 1: Custom Configuration
Advanced usage
Option 2: Integration
Integration steps
- Level 4: Reference (Rarely Needed)
- Troubleshooting
- Issue: Common Problem
- Symptoms
-
- What you see
- Cause
-
- Why it happens
- Solution
- How to fix
Fix command
- Issue: Another Problem
- Solution
- Steps to resolve Complete API Reference See API_REFERENCE.md Examples See examples/