skill-builder

name Skill Builder description Create new Claude Code Skills with proper YAML frontmatter, progressive disclosure structure, and complete directory organization. Use when you need to build custom skills for specific workflows, generate skill templates, or understand the Claude Skills specification. 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): <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 --- 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 ]( 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 --- 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/ Related Skills Related Skill 1 Related Skill 2 Resources External Link 1 Documentation --- ### 🎨 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 : # ✅ 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 : # ✅ 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): ## What This Skill Does Creates production-ready React components with TypeScript, hooks, and tests in 3 steps. Level 2 for Common Paths (Quick Start): ## 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): ## 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: # In skill directory scripts/ ├── setup.sh # Initialization script ├── validate.js # Validation logic ├── generate.py # Code generation └── deploy.sh # Deployment script Reference from SKILL.md: ## Setup Run the setup script: ```bash ./scripts/setup.sh Validation Validate your configuration: 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: ## 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.