skill-builder
提供从零构建 Claude Code 技能的完整方法论,涵盖标准化 YAML 元数据定义、渐进式内容分层设计及规范化的目录组织,支持快速生成可被 Claude 自动识别与调用的生产级技能。
| 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
▼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:
- 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
▼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)
▼text复制代码~/.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)
▼text复制代码~/.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):
▼text复制代码~/.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):
▼text复制代码<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
- Scenario 1: How to...
- Scenario 2: How to...
Level 3: Detailed Instructions (For Deep Work)
Step-by-Step Guide
Step 1: Initial Setup
▼bash复制代码# Commands
Expected output:
▼text复制代码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
Examples
See examples/
Related Skills
Resources
▼text复制代码--- ### 🎨 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
▼text复制代码**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
▼text复制代码#### 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 componentadvanced-example/- With hooks and context
▼text复制代码--- ### 🔗 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.
Relative File Paths
▼markdown复制代码Use the template located at `resources/templates/api-template.js` See examples in `resources/examples/basic-usage/`
Inline File Content
▼markdown复制代码## Example Configuration See `resources/examples/config.json`: ```json { "option": "value" }
▼text复制代码**Best Practice**: Keep SKILL.md lean (~2-5KB). Move lengthy content to separate files and reference them. Claude will load only what's needed. --- ### ✅ Validation Checklist Before publishing a skill, verify: **YAML Frontmatter**: - [ ] Starts with `---` - [ ] Contains `name` field (max 64 chars) - [ ] Contains `description` field (max 1024 chars) - [ ] Description includes "what" and "when" - [ ] Ends with `---` - [ ] No YAML syntax errors **File Structure**: - [ ] SKILL.md exists in skill directory - [ ] Directory is DIRECTLY in `~/.claude/skills/[skill-name]/` or `.claude/skills/[skill-name]/` - [ ] Uses clear, descriptive directory name - [ ] **NO nested subdirectories** (Claude Code requires top-level structure) **Content Quality**: - [ ] Level 1 (Overview) is brief and clear - [ ] Level 2 (Quick Start) shows common use case - [ ] Level 3 (Details) provides step-by-step guide - [ ] Level 4 (Reference) links to advanced content - [ ] Examples are concrete and runnable - [ ] Troubleshooting section addresses common issues **Progressive Disclosure**: - [ ] Core instructions in SKILL.md (~2-5KB) - [ ] Advanced content in separate docs/ - [ ] Large resources in resources/ directory - [ ] Clear navigation between levels **Testing**: - [ ] Skill appears in Claude's skill list - [ ] Description triggers on relevant queries - [ ] Instructions are clear and actionable - [ ] Scripts execute successfully (if included) - [ ] Examples work as documented --- ## Skill Builder Templates ### Template 1: Basic Skill (Minimal) ```markdown --- name: "My Basic Skill" description: "One sentence what. One sentence when to use." --- # My Basic Skill ## What This Skill Does [2-3 sentences describing functionality] ## Quick Start ```bash # Single command to get started
Step-by-Step Guide
Step 1: Setup
[Instructions]
Step 2: Usage
[Instructions]
Step 3: Verify
[Instructions]
Troubleshooting
- Issue: Problem description
- Solution: Fix description
▼text复制代码### Template 2: Intermediate Skill (With Scripts) ```markdown --- name: "My Intermediate Skill" description: "Detailed what with key features. When to use with specific triggers: scaffolding, generating, building." --- # My Intermediate Skill ## Prerequisites - Requirement 1 - Requirement 2 ## What This Skill Does 1. Primary function 2. Secondary function 3. Integration capability ## Quick Start ```bash ./scripts/setup.sh ./scripts/generate.sh my-project
Configuration
Edit config.json:
▼json复制代码{ "option1": "value1", "option2": "value2" }
Step-by-Step Guide
Basic Usage
[Steps for 80% use case]
Advanced Usage
[Steps for complex scenarios]
Available Scripts
scripts/setup.sh- Initial setupscripts/generate.sh- Code generationscripts/validate.sh- Validation
Resources
- Templates:
resources/templates/ - Examples:
resources/examples/
Troubleshooting
[Common issues and solutions]
▼text复制代码### Template 3: Advanced Skill (Full-Featured) ```markdown --- name: "My Advanced Skill" description: "Comprehensive what with all features and integrations. Use when [trigger 1], [trigger 2], or [trigger 3]. Supports [technology stack]." --- # My Advanced Skill ## Overview [Brief 2-3 sentence description] ## Prerequisites - Technology 1 (version X+) - Technology 2 (version Y+) - API keys or credentials ## What This Skill Does 1. **Core Feature**: Description 2. **Integration**: Description 3. **Automation**: Description --- ## Quick Start (60 seconds) ### Installation ```bash ./scripts/install.sh
First Use
▼bash复制代码./scripts/quickstart.sh
Expected output:
▼text复制代码✓ Setup complete ✓ Configuration validated → Ready to use
Configuration
Basic Configuration
Edit config.json:
▼json复制代码{ "mode": "production", "features": ["feature1", "feature2"] }
Advanced Configuration
Step-by-Step Guide
1. Initial Setup
[Detailed steps]
2. Core Workflow
[Main procedures]
3. Integration
[Integration steps]
Advanced Features
Feature 1: Custom Templates
▼bash复制代码./scripts/generate.sh --template custom
Feature 2: Batch Processing
▼bash复制代码./scripts/batch.sh --input data.json
Feature 3: CI/CD Integration
See CI/CD Guide
Scripts Reference
| Script | Purpose | Usage |
|---|---|---|
install.sh | Install dependencies | ./scripts/install.sh |
generate.sh | Generate code | ./scripts/generate.sh [name] |
validate.sh | Validate output | ./scripts/validate.sh |
deploy.sh | Deploy to environment | ./scripts/deploy.sh [env] |
Resources
Templates
resources/templates/basic.template- Basic templateresources/templates/advanced.template- Advanced template
Examples
resources/examples/basic/- Simple exampleresources/examples/advanced/- Complex exampleresources/examples/integration/- Integration example
Schemas
resources/schemas/config.schema.json- Configuration schemaresources/schemas/output.schema.json- Output validation
Troubleshooting
Issue: Installation Failed
Symptoms: Error during install.sh
Cause: Missing dependencies
Solution:
▼bash复制代码# Install prerequisites npm install -g required-package ./scripts/install.sh --force
Issue: Validation Errors
Symptoms: Validation script fails Solution: See Troubleshooting Guide
API Reference
Complete API documentation: API_REFERENCE.md
Related Skills
Resources
Created: 2025-10-19 Category: Advanced Difficulty: Intermediate Estimated Time: 15-30 minutes
▼text复制代码--- ## Examples from the Wild ### Example 1: Simple Documentation Skill ```markdown --- name: "README Generator" description: "Generate comprehensive README.md files for GitHub repositories. Use when starting new projects, documenting code, or improving existing READMEs." --- # README Generator ## What This Skill Does Creates well-structured README.md files with badges, installation, usage, and contribution sections. ## Quick Start ```bash # Answer a few questions ./scripts/generate-readme.sh # README.md created with: # - Project title and description # - Installation instructions # - Usage examples # - Contribution guidelines
Customization
Edit sections in resources/templates/sections/ before generating.
▼text复制代码### Example 2: Code Generation Skill ```markdown --- name: "React Component Generator" description: "Generate React functional components with TypeScript, hooks, tests, and Storybook stories. Use when creating new components, scaffolding UI, or following component architecture patterns." --- # React Component Generator ## Prerequisites - Node.js 18+ - React 18+ - TypeScript 5+ ## Quick Start ```bash ./scripts/generate-component.sh MyComponent # Creates: # - src/components/MyComponent/MyComponent.tsx # - src/components/MyComponent/MyComponent.test.tsx # - src/components/MyComponent/MyComponent.stories.tsx # - src/components/MyComponent/index.ts
Step-by-Step Guide
1. Run Generator
▼bash复制代码./scripts/generate-component.sh ComponentName
2. Choose Template
- Basic: Simple functional component
- With State: useState hooks
- With Context: useContext integration
- With API: Data fetching component
3. Customize
Edit generated files in src/components/ComponentName/
Templates
See resources/templates/ for available component templates.
▼text复制代码--- ## Learn More ### Official Resources - [Anthropic Agent Skills Documentation](https://docs.claude.com/en/docs/agents-and-tools/agent-skills) - [GitHub Skills Repository](https://github.com/anthropics/skills) - [Claude Code Documentation](https://docs.claude.com/en/docs/claude-code) ### Community - [Skills Marketplace](https://github.com/anthropics/skills) - Browse community skills - [Anthropic Discord](https://discord.gg/anthropic) - Get help from community ### Advanced Topics - Multi-file skills with complex navigation - Skills that spawn other skills - Integration with MCP tools - Dynamic skill generation --- **Created**: 2025-10-19 **Version**: 1.0.0 **Maintained By**: agentic-flow team **License**: MIT









