skill-builder

# 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 ```bash # 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: ```yaml --- 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: 1. **What** the skill does (functionality) 2. **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 ```yaml --- # ✅ 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): ``` <project-root>/.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 ```yaml --- 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 ```markdown # 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 ```markdown # In SKILL.md See [Advanced Configuration](docs/ADVANCED.md) for complex scenarios. See [API Reference](docs/API_REFERENCE.md) 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 ```markdown --- 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 1. **Scenario 1**: How to... 2. **Scenario 2**: How to... --- ## Level 3: Detailed Instructions (For Deep Work) ### Step-by-Step Guide #### Step 1: Initial Setup ```bash # 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 ```bash # Advanced usage ``` #### Option 2: Integration ```bash # Integration steps ``` --- ## Level 4: Reference (Rarely Needed) ### Troubleshooting #### Issue: Common Problem **Symptoms**: What you see **Cause**: Why it happens **Solution**: How to fix ```bash # Fix command ``` #### Issue: Another Problem **Solution**: Steps to resolve ### Complete API Reference See [API_REFERENCE.md](docs/API_REFERENCE.md) ### Examples See [examples/](resources$examples/) ### Related Skills - [Related Skill 1](#) - [Related Skill 2](#) ### Resources - [External Link 1](https:/$example.com) - [Documentation](https:/$docs.example.com) ``` --- ### 🎨 Content Best Practices #### Writing Effective Descriptions **Front-Load Keywords**: ```yaml # ✅ GOOD: Keywords first description: "Generate TypeScript interfaces from JSON schema. Use when converting schemas, creating types, or building API clients." # ❌ BAD: Keywords buried description: "This skill helps developers who need to work with JSON schemas by providing a way to generate TypeScript interfaces." ``` **Include Trigger Conditions**: ```yaml # ✅ GOOD: Clear "when" clause description: "Debug React performance issues using Chrome DevTools. Use when components re-render unnecessarily, investigating slow updates, or optimizing bundle size." # ❌ BAD: No trigger conditions description: "Helps with React performance debugging." ``` **Be Specific**: ```yaml # ✅ GOOD: Specific technologies description: "Create Express.js REST endpoints with Joi validation, Swagger docs, and Jest tests. Use when building new APIs or adding endpoints." # ❌ BAD: Too generic description: "Build API endpoints with proper validation and testing." ``` #### Progressive Disclosure Writing **Keep Level 1 Brief** (Overview): ```markdown ## What This Skill Does Creates production-ready React components with TypeScript, hooks, and tests in 3 steps. ``` **Level 2 for Common Paths** (Quick Start): ```markdown ## Quick Start ```bash # Most common use case (80% of users) generate-component MyComponent ``` ``` **Level 3 for Details** (Step-by-Step): ```markdown ## Step-by-Step Guide ### Creating a Basic Component 1. Run generator 2. Choose template 3. Customize options [Detailed explanations] ``` **Level 4 for Edge Cases** (Reference): ```markdown ## Advanced Configuration For complex scenarios like HOCs, render props, or custom hooks, see [ADVANCED.md](docs/ADVANCED.md). ``` --- ### 🛠️ Adding Scripts and Resources #### Scripts Directory **Purpose**: Executable scripts that Claude can run **Location**: `scripts/` in skill directory **Usage**: Referenced from SKILL.md Example: ```bash # In skill directory scripts/ ├── setup.sh # Initialization script ├── validate.js # Validation logic ├── generate.py # Code generation └── deploy.sh # Deployment script ``` Reference from SKILL.md: ```markdown ## Setup Run the setup script: ```bash .$scripts$setup.sh ``` ## Validation Validate your configuration: ```bash node scripts$validate.js config.json ``` ``` #### Resources Directory **Purpose**: Templates, examples, schemas, static files **Location**: `resources/` in skill directory **Usage**: Referenced or copied by scripts Example: ```bash resources/ ├── templates/ │ ├── component.tsx.template │ ├── test.spec.ts.template │ └── story.stories.tsx.template ├── examples/ │ ├── basic-example/ │ ├── advanced-example/ │ └── integration-example/ └── schemas/ ├── config.schema.json └── output.schema.json ``` Reference from SKILL.md: ```markdown ## Templates Use the component template: ```bash cp resources$templates$component.tsx.template src$components/MyComponent.tsx ``` ## Examples See working examples in `resources$examples/`: - `basic-example/` - Simple component - `advanced-example/` - With hooks and context ``` --- ### 🔗 File References and Navigation Claude can navigate to referenced files automatically. Use these patterns: #### Markdown Links ```markdown See [Advanced Configuration](docs/ADVANCED.md) for complex scenarios. See [Troubleshooting Guide](docs/TROUBLESHOOTING.md) if you encounter errors. ```