6# Skill Builder
7
8## What This Skill Does
9
10Creates 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).
11
12## Prerequisites
13
14- Claude Code 2.0+ or Claude.ai with Skills support
15- Basic understanding of Markdown and YAML
16- Text editor or IDE
17
18## Quick Start
19
20### Creating Your First Skill
21
22```bash
23# 1. Create skill directory (MUST be at top level, NOT in subdirectories!)
24mkdir -p ~/.claude/skills/my-first-skill
25
26# 2. Create SKILL.md with proper format
27cat > ~/.claude/skills/my-first-skill/SKILL.md << 'EOF'
28---
29name: "My First Skill"
30description: "Brief description of what this skill does and when Claude should use it. Maximum 1024 characters."
31---
32
33# My First Skill
34
35## What This Skill Does
36[Your instructions here]
37
38## Quick Start
39[Basic usage]
40EOF
41
42# 3. Verify skill is detected
43# Restart Claude Code or refresh Claude.ai
44```
45
46---
47
48## Complete Specification
49
50### 📋 YAML Frontmatter (REQUIRED)
51
52Every SKILL.md **must** start with YAML frontmatter containing exactly two required fields:
53
54```yaml
55---
56name: "Skill Name" # REQUIRED: Max 64 chars
57description: "What this skill does # REQUIRED: Max 1024 chars
58and when Claude should use it." # Include BOTH what & when
59---
60```
61
62#### Field Requirements
63
64**name** (REQUIRED):
65- **Type**: String
66- **Max Length**: 64 characters
67- **Format**: Human-friendly display name
68- **Usage**: Shown in skill lists, UI, and loaded into Claude's system prompt
69- **Best Practice**: Use Title Case, be concise and descriptive
70- **Examples**:
71 - ✅ "API Documentation Generator"
72 - ✅ "React Component Builder"
73 - ✅ "Database Schema Designer"
74 - ❌ "skill-1" (not descriptive)
75 - ❌ "This is a very long skill name that exceeds sixty-four characters" (too long)
76
77**description** (REQUIRED):
78- **Type**: String
79- **Max Length**: 1024 characters
80- **Format**: Plain text or minimal markdown
81- **Content**: MUST include:
82 1. **What** the skill does (functionality)
83 2. **When** Claude should invoke it (trigger conditions)
84- **Usage**: Loaded into Claude's system prompt for autonomous matching
85- **Best Practice**: Front-load key trigger words, be specific about use cases
86- **Examples**:
87 - ✅ "Generate OpenAPI 3.0 documentation from Express.js routes. Use when creating API docs, documenting endpoints, or building API specifications."
88 - ✅ "Create React functional components with TypeScript, hooks, and tests. Use when scaffolding new components or converting class components."
89 - ❌ "A comprehensive guide to API documentation" (no "when" clause)
90 - ❌ "Documentation tool" (too vague)
91
92#### YAML Formatting Rules
93
94```yaml
95---
96# ✅ CORRECT: Simple string
97name: "API Builder"
98description: "Creates REST APIs with Express and TypeScript."
99
100# ✅ CORRECT: Multi-line description
101name: "Full-Stack Generator"
102description: "Generates full-stack applications with React frontend and Node.js backend. Use when starting new projects or scaffolding applications."
103
104# ✅ CORRECT: Special characters quoted
105name: "JSON:API Builder"
106description: "Creates JSON:API compliant endpoints: pagination, filtering, relationships."
107
108# ❌ WRONG: Missing quotes with special chars
109name: API:Builder # YAML parse error!
110
111# ❌ WRONG: Extra fields (ignored but discouraged)
112name: "My Skill"
113description: "My description"
114version: "1.0.0" # NOT part of spec
115author: "Me" # NOT part of spec
116tags: ["dev", "api"] # NOT part of spec
117---
118```
119
120**Critical**: Only name and description are used by Claude. Additional fields are ignored.
121
122---
123
124### 📂 Directory Structure
125
126#### Minimal Skill (Required)
127```
128~/.claude/skills/ # Personal skills location
129└── my-skill/ # Skill directory (MUST be at top level!)
130 └── SKILL.md # REQUIRED: Main skill file
131```
132
133**IMPORTANT**: Skills MUST be directly under ~/.claude/skills/[skill-name]/.
134Claude Code does NOT support nested subdirectories or namespaces!
135
136#### Full-Featured Skill (Recommended)
137```
138~/.claude/skills/
139└── my-skill/ # Top-level skill directory
140 ├── SKILL.md # REQUIRED: Main skill file
141 ├── README.md # Optional: Human-readable docs
142 ├── scripts/ # Optional: Executable scripts
143 │ ├── setup.sh
144 │ ├── validate.js
145 │ └── deploy.py
146 ├── resources/ # Optional: Supporting files
147 │ ├── templates/
148 │ │ ├── api-template.js
149 │ │ └── component.tsx
150 │ ├── examples/
151 │ │ └── sample-output.json
152 │ └── schemas/
153 │ └── config-schema.json
154 └── docs/ # Optional: Additional documentation
155 ├── ADVANCED.md
156 ├── TROUBLESHOOTING.md
157 └── API_REFERENCE.md
158```
159
160#### Skills Locations
161
162**Personal Skills** (available across all projects):
163```
164~/.claude/skills/
165└── [your-skills]/
166```
167- **Path**: ~/.claude/skills/ or $HOME/.claude/skills/
168- **Scope**: Available in all projects for this user
169- **Version Control**: NOT committed to git (outside repo)
170- **Use Case**: Personal productivity tools, custom workflows
171
172**Project Skills** (team-shared, version controlled):
173```
174<project-root>/.claude/skills/
175└── [team-skills]/
176```
177- **Path**: .claude/skills/ in project root
178- **Scope**: Available only in this project
179- **Version Control**: SHOULD be committed to git
180- **Use Case**: Team workflows, project-specific tools, shared knowledge
181
182---
183
184### 🎯 Progressive Disclosure Architecture
185
186Claude Code uses a **3-level progressive disclosure system** to scale to 100+ skills without context penalty:
187
188#### Level 1: Metadata (Name + Description)
189**Loaded**: At Claude Code startup, always
190**Size**: ~200 chars per skill
191**Purpose**: Enable autonomous skill matching
192**Context**: Loaded into system prompt for ALL skills
193
194```yaml
195---
196name: "API Builder" # 11 chars
197description: "Creates REST APIs..." # ~50 chars
198---
199# Total: ~61 chars per skill
200# 100 skills = ~6KB context (minimal!)
201```
202
203#### Level 2: SKILL.md Body
204**Loaded**: When skill is triggered/matched
205**Size**: ~1-10KB typically
206**Purpose**: Main instructions and procedures
207**Context**: Only loaded for ACTIVE skills
208
209```markdown
210# API Builder
211
212## What This Skill Does
213[Main instructions - loaded only when skill is active]
214
215## Quick Start
216[Basic procedures]
217
218## Step-by-Step Guide
219[Detailed instructions]
220```
221
222#### Level 3+: Referenced Files
223**Loaded**: On-demand as Claude navigates
224**Size**: Variable (KB to MB)
225**Purpose**: Deep reference, examples, schemas
226**Context**: Loaded only when Claude accesses specific files
227
228```markdown
229# In SKILL.md
230See [Advanced Configuration](docs/ADVANCED.md) for complex scenarios.
231See [API Reference](docs/API_REFERENCE.md) for complete documentation.
232Use template: resources/templates/api-template.js
233
234# Claude will load these files ONLY if needed
235```
236
237**Benefit**: Install 100+ skills with ~6KB context. Only active skill content (1-10KB) enters context.
238
239---
240
241### 📝 SKILL.md Content Structure
242
243#### Recommended 4-Level Structure
244
245```markdown
246---
247name: "Your Skill Name"
248description: "What it does and when to use it"
249---
250
251# Your Skill Name
252
253## Level 1: Overview (Always Read First)
254Brief 2-3 sentence description of the skill.
255
256## Prerequisites
257- Requirement 1
258- Requirement 2
259
260## What This Skill Does
2611. Primary function
2622. Secondary function
2633. Key benefit
264
265---
266
267## Level 2: Quick Start (For Fast Onboarding)
268
269### Basic Usage
270```bash
271# Simplest use case
272command --option value
273```
274
275### Common Scenarios
2761. **Scenario 1**: How to...
2772. **Scenario 2**: How to...
278
279---
280
281## Level 3: Detailed Instructions (For Deep Work)
282
283### Step-by-Step Guide
284
285#### Step 1: Initial Setup
286```bash
287# Commands
288```
289Expected output:
290```
291Success message
292```
293
294#### Step 2: Configuration
295- Configuration option 1
296- Configuration option 2
297
298#### Step 3: Execution
299- Run the main command
300- Verify results
301
302### Advanced Options
303
304#### Option 1: Custom Configuration
305```bash
306# Advanced usage
307```
308
309#### Option 2: Integration
310```bash
311# Integration steps
312```
313
314---
315
316## Level 4: Reference (Rarely Needed)
317
318### Troubleshooting
319
320#### Issue: Common Problem
321**Symptoms**: What you see
322**Cause**: Why it happens
323**Solution**: How to fix
324```bash
325# Fix command
326```
327
328#### Issue: Another Problem
329**Solution**: Steps to resolve
330
331### Complete API Reference
332See [API_REFERENCE.md](docs/API_REFERENCE.md)
333
334### Examples
335See [examples/](resources/examples/)
336
337### Related Skills
338- [Related Skill 1](#)
339- [Related Skill 2](#)
340
341### Resources
342- [External Link 1](https://example.com)
343- [Documentation](https://docs.example.com)
344```
345
346---
347
348### 🎨 Content Best Practices
349
350#### Writing Effective Descriptions
351
352**Front-Load Keywords**:
353```yaml
354# ✅ GOOD: Keywords first
355description: "Generate TypeScript interfaces from JSON schema. Use when converting schemas, creating types, or building API clients."
356
357# ❌ BAD: Keywords buried
358description: "This skill helps developers who need to work with JSON schemas by providing a way to generate TypeScript interfaces."
359```
360
361**Include Trigger Conditions**:
362```yaml
363# ✅ GOOD: Clear "when" clause
364description: "Debug React performance issues using Chrome DevTools. Use when components re-render unnecessarily, investigating slow updates, or optimizing bundle size."
365
366# ❌ BAD: No trigger conditions
367description: "Helps with React performance debugging."
368```
369
370**Be Specific**:
371```yaml
372# ✅ GOOD: Specific technologies
373description: "Create Express.js REST endpoints with Joi validation, Swagger docs, and Jest tests. Use when building new APIs or adding endpoints."
374
375# ❌ BAD: Too generic
376description: "Build API endpoints with proper validation and testing."
377```
378
379#### Progressive Disclosure Writing
380
381**Keep Level 1 Brief** (Overview):
382```markdown
383## What This Skill Does
384Creates production-ready React components with TypeScript, hooks, and tests in 3 steps.
385```
386
387**Level 2 for Common Paths** (Quick Start):
388```markdown
389## Quick Start
390```bash
391# Most common use case (80% of users)
392generate-component MyComponent
393```
394```
395
396**Level 3 for Details** (Step-by-Step):
397```markdown
398## Step-by-Step Guide
399
400### Creating a Basic Component
4011. Run generator
4022. Choose template
4033. Customize options
404[Detailed explanations]
405```
406
407**Level 4 for Edge Cases** (Reference):
408```markdown
409## Advanced Configuration
410For complex scenarios like HOCs, render props, or custom hooks, see [ADVANCED.md](docs/ADVANCED.md).
411```
412
413---
414
415### 🛠️ Adding Scripts and Resources
416
417#### Scripts Directory
418
419**Purpose**: Executable scripts that Claude can run
420**Location**: scripts/ in skill directory
421**Usage**: Referenced from SKILL.md
422
423Example:
424```bash
425# In skill directory
426scripts/
427├── setup.sh # Initialization script
428├── validate.js # Validation logic
429├── generate.py # Code generation
430└── deploy.sh # Deployment script
431```
432
433Reference from SKILL.md:
434```markdown
435## Setup
436Run the setup script:
437```bash
438./scripts/setup.sh
439```
440
441## Validation
442Validate your configuration:
443```bash
444node scripts/validate.js config.json
445```
446```
447
448#### Resources Directory
449
450**Purpose**: Templates, examples, schemas, static files
451**Location**: resources/ in skill directory
452**Usage**: Referenced or copied by scripts
453
454Example:
455```bash
456resources/
457├── templates/
458│ ├── component.tsx.template
459│ ├── test.spec.ts.template
460│ └── story.stories.tsx.template
461├── examples/
462│ ├── basic-example/
463│ ├── advanced-example/
464│ └── integration-example/
465└── schemas/
466 ├── config.schema.json
467 └── output.schema.json
468```
469
470Reference from SKILL.md:
471```markdown
472## Templates
473Use the component template:
474```bash
475cp resources/templates/component.tsx.template src/components/MyComponent.tsx
476```
477
478## Examples
479See working examples in resources/examples/:
480- basic-example/ - Simple component
481- advanced-example/ - With hooks and context
482```
483
484---
485
486### 🔗 File References and Navigation
487
488Claude can navigate to referenced files automatically. Use these patterns:
489
490#### Markdown Links
491```markdown
492See [Advanced Configuration](docs/ADVANCED.md) for complex scenarios.
493See [Troubleshooting Guide](docs/TROUBLESHOOTING.md) if you encounter errors.
494```
495
496#### Relative File Paths
497```markdown
498Use the template located at resources/templates/api-template.js
499See examples in resources/examples/basic-usage/
500```
501
502#### Inline File Content
503```markdown
504## Example Configuration
505See resources/examples/config.json:
506```json
507{
508 "option": "value"
509}
510```
511```
512
513**Best Practice**: Keep SKILL.md lean (~2-5KB). Move lengthy content to separate files and reference them. Claude will load only what's needed.
514
515---
516
517### ✅ Validation Checklist
518
519Before publishing a skill, verify:
520
521**YAML Frontmatter**:
522- [ ] Starts with ---
523- [ ] Contains name field (max 64 chars)
524- [ ] Contains description field (max 1024 chars)
525- [ ] Description includes "what" and "when"
526- [ ] Ends with ---
527- [ ] No YAML syntax errors
528
529**File Structure**:
530- [ ] SKILL.md exists in skill directory
531- [ ] Directory is DIRECTLY in ~/.claude/skills/[skill-name]/ or .claude/skills/[skill-name]/
532- [ ] Uses clear, descriptive directory name
533- [ ] **NO nested subdirectories** (Claude Code requires top-level structure)
534
535**Content Quality**:
536- [ ] Level 1 (Overview) is brief and clear
537- [ ] Level 2 (Quick Start) shows common use case
538- [ ] Level 3 (Details) provides step-by-step guide
539- [ ] Level 4 (Reference) links to advanced content
540- [ ] Examples are concrete and runnable
541- [ ] Troubleshooting section addresses common issues
542
543**Progressive Disclosure**:
544- [ ] Core instructions in SKILL.md (~2-5KB)
545- [ ] Advanced content in separate docs/
546- [ ] Large resources in resources/ directory
547- [ ] Clear navigation between levels
548
549**Testing**:
550- [ ] Skill appears in Claude's skill list
551- [ ] Description triggers on relevant queries
552- [ ] Instructions are clear and actionable
553- [ ] Scripts execute successfully (if included)
554- [ ] Examples work as documented
555
556---
557
558## Skill Builder Templates
559
560### Template 1: Basic Skill (Minimal)
561
562```markdown
563---
564name: "My Basic Skill"
565description: "One sentence what. One sentence when to use."
566---
567
568# My Basic Skill
569
570## What This Skill Does
571[2-3 sentences describing functionality]
572
573## Quick Start
574```bash
575# Single command to get started
576```
577
578## Step-by-Step Guide
579
580### Step 1: Setup
581[Instructions]
582
583### Step 2: Usage
584[Instructions]
585
586### Step 3: Verify
587[Instructions]
588
589## Troubleshooting
590- **Issue**: Problem description
591 - **Solution**: Fix description
592```
593
594### Template 2: Intermediate Skill (With Scripts)
595
596```markdown
597---
598name: "My Intermediate Skill"
599description: "Detailed what with key features. When to use with specific triggers: scaffolding, generating, building."
600---
601
602# My Intermediate Skill
603
604## Prerequisites
605- Requirement 1
606- Requirement 2
607
608## What This Skill Does
6091. Primary function
6102. Secondary function
6113. Integration capability
612
613## Quick Start
614```bash
615./scripts/setup.sh
616./scripts/generate.sh my-project
617```
618
619## Configuration
620Edit config.json:
621```json
622{
623 "option1": "value1",
624 "option2": "value2"
625}
626```
627
628## Step-by-Step Guide
629
630### Basic Usage
631[Steps for 80% use case]
632
633### Advanced Usage
634[Steps for complex scenarios]
635
636## Available Scripts
637- scripts/setup.sh - Initial setup
638- scripts/generate.sh - Code generation
639- scripts/validate.sh - Validation
640
641## Resources
642- Templates: resources/templates/
643- Examples: resources/examples/
644
645## Troubleshooting
646[Common issues and solutions]
647```
648
649### Template 3: Advanced Skill (Full-Featured)
650
651```markdown
652---
653name: "My Advanced Skill"
654description: "Comprehensive what with all features and integrations. Use when [trigger 1], [trigger 2], or [trigger 3]. Supports [technology stack]."
655---
656
657# My Advanced Skill
658
659## Overview
660[Brief 2-3 sentence description]
661
662## Prerequisites
663- Technology 1 (version X+)
664- Technology 2 (version Y+)
665- API keys or credentials
666
667## What This Skill Does
6681. **Core Feature**: Description
6692. **Integration**: Description
6703. **Automation**: Description
671
672---
673
674## Quick Start (60 seconds)
675
676### Installation
677```bash
678./scripts/install.sh
679```
680
681### First Use
682```bash
683./scripts/quickstart.sh
684```
685
686Expected output:
687```
688✓ Setup complete
689✓ Configuration validated
690→ Ready to use
691```
692
693---
694
695## Configuration
696
697### Basic Configuration
698Edit config.json:
699```json
700{
701 "mode": "production",
702 "features": ["feature1", "feature2"]
703}
704```
705
706### Advanced Configuration
707See [Configuration Guide](docs/CONFIGURATION.md)
708
709---
710
711## Step-by-Step Guide
712
713### 1. Initial Setup
714[Detailed steps]
715
716### 2. Core Workflow
717[Main procedures]
718
719### 3. Integration
720[Integration steps]
721
722---
723
724## Advanced Features
725
726### Feature 1: Custom Templates
727```bash
728./scripts/generate.sh --template custom
729```
730
731### Feature 2: Batch Processing
732```bash
733./scripts/batch.sh --input data.json
734```
735
736### Feature 3: CI/CD Integration
737See [CI/CD Guide](docs/CICD.md)
738
739---
740
741## Scripts Reference
742
743| Script | Purpose | Usage |
744|--------|---------|-------|
745| install.sh | Install dependencies | ./scripts/install.sh |
746| generate.sh | Generate code | ./scripts/generate.sh [name] |
747| validate.sh | Validate output | ./scripts/validate.sh |
748| deploy.sh | Deploy to environment | ./scripts/deploy.sh [env] |
749
750---
751
752## Resources
753
754### Templates
755- resources/templates/basic.template - Basic template
756- resources/templates/advanced.template - Advanced template
757
758### Examples
759- resources/examples/basic/ - Simple example
760- resources/examples/advanced/ - Complex example
761- resources/examples/integration/ - Integration example
762
763### Schemas
764- resources/schemas/config.schema.json - Configuration schema
765- resources/schemas/output.schema.json - Output validation
766
767---
768
769## Troubleshooting
770
771### Issue: Installation Failed
772**Symptoms**: Error during install.sh
773**Cause**: Missing dependencies
774**Solution**:
775```bash
776# Install prerequisites
777npm install -g required-package
778./scripts/install.sh --force
779```
780
781### Issue: Validation Errors
782**Symptoms**: Validation script fails
783**Solution**: See [Troubleshooting Guide](docs/TROUBLESHOOTING.md)
784
785---
786
787## API Reference
788Complete API documentation: [API_REFERENCE.md](docs/API_REFERENCE.md)
789
790## Related Skills
791- [Related Skill 1](../related-skill-1/)
792- [Related Skill 2](../related-skill-2/)
793
794## Resources
795- [Official Documentation](https://example.com/docs)
796- [GitHub Repository](https://github.com/example/repo)
797- [Community Forum](https://forum.example.com)
798
799---
800
801**Created**: 2025-10-19
802**Category**: Advanced
803**Difficulty**: Intermediate
804**Estimated Time**: 15-30 minutes
805```
806
807---
808
809## Examples from the Wild
810
811### Example 1: Simple Documentation Skill
812
813```markdown
814---
815name: "README Generator"
816description: "Generate comprehensive README.md files for GitHub repositories. Use when starting new projects, documenting code, or improving existing READMEs."
817---
818
819# README Generator
820
821## What This Skill Does
822Creates well-structured README.md files with badges, installation, usage, and contribution sections.
823
824## Quick Start
825```bash
826# Answer a few questions
827./scripts/generate-readme.sh
828
829# README.md created with:
830# - Project title and description
831# - Installation instructions
832# - Usage examples
833# - Contribution guidelines
834```
835
836## Customization
837Edit sections in resources/templates/sections/ before generating.
838```
839
840### Example 2: Code Generation Skill
841
842```markdown
843---
844name: "React Component Generator"
845description: "Generate React functional components with TypeScript, hooks, tests, and Storybook stories. Use when creating new components, scaffolding UI, or following component architecture patterns."
846---
847
848# React Component Generator
849
850## Prerequisites
851- Node.js 18+
852- React 18+
853- TypeScript 5+
854
855## Quick Start
856```bash
857./scripts/generate-component.sh MyComponent
858
859# Creates:
860# - src/components/MyComponent/MyComponent.tsx
861# - src/components/MyComponent/MyComponent.test.tsx
862# - src/components/MyComponent/MyComponent.stories.tsx
863# - src/components/MyComponent/index.ts
864```
865
866## Step-by-Step Guide
867
868### 1. Run Generator
869```bash
870./scripts/generate-component.sh ComponentName
871```
872
873### 2. Choose Template
874- Basic: Simple functional component
875- With State: useState hooks
876- With Context: useContext integration
877- With API: Data fetching component
878
879### 3. Customize
880Edit generated files in src/components/ComponentName/
881
882## Templates
883See resources/templates/ for available component templates.
884```
885
886---
887
888## Learn More
889
890### Official Resources
891- [Anthropic Agent Skills Documentation](https://docs.claude.com/en/docs/agents-and-tools/agent-skills)
892- [GitHub Skills Repository](https://github.com/anthropics/skills)
893- [Claude Code Documentation](https://docs.claude.com/en/docs/claude-code)
894
895### Community
896- [Skills Marketplace](https://github.com/anthropics/skills) - Browse community skills
897- [Anthropic Discord](https://discord.gg/anthropic) - Get help from community
898
899### Advanced Topics
900- Multi-file skills with complex navigation
901- Skills that spawn other skills
902- Integration with MCP tools
903- Dynamic skill generation
904
905---
906
907**Created**: 2025-10-19
908**Version**: 1.0.0
909**Maintained By**: agentic-flow team
910**License**: MIT
911