Skill Builder Generic

---
name: skill-builder-generic
description: Universal guide for creating production-ready Claude Code skills for any project. Includes 6-step workflow (understand, plan, initialize, edit, package, iterate), progressive disclosure design, YAML frontmatter templates, validation scripts, reference organization patterns, and 10 community-proven innovations. Use when creating new Claude Code skills, converting documentation to skills, improving existing skills, or learning skill development best practices for any domain.
allowed-tools: Read, Write, Edit, Glob, Grep, Bash, WebSearch, WebFetch
---

# Universal Claude Code Skill Builder

## Philosophy & Overview

### What Are Claude Code Skills?

Skills are structured knowledge packages that extend Claude Code's capabilities for specific domains. They follow a standardized format:
- YAML frontmatter for metadata
- Markdown content for instructions
- Progressive disclosure for context optimization
- Optional references/, scripts/, and assets/ for bundled resources

### Why Skills Matter

**Without Skills**: Every task requires full context in conversation, repeated explanations, and no knowledge persistence across sessions.

**With Skills**: Domain knowledge is packaged once, invoked by name, loaded progressively, and reused across all projects.

### When to Create Skills

Create skills when:
- You have domain-specific knowledge to capture (design systems, API patterns, deployment workflows)
- You repeat similar instructions frequently (testing patterns, code review standards)
- You want to share knowledge with team or community
- You need consistent execution of complex workflows

Don't create skills when:
- Information is one-time use
- Task is better suited for inline conversation
- Knowledge changes too rapidly to maintain

### Core Principles

**Progressive Disclosure**: Keep SKILL.md lean, bundle details in references/
- SKILL.md: Always loaded (overview, quick start, key workflows)
- references/: Loaded on-demand (comprehensive guides, deep details)
- scripts/: Loaded when execution needed (automation, validation)

**Imperative/Infinitive Voice**: Write action-oriented instructions
- Good: "Create skill structure using workflow pattern"
- Bad: "You should probably think about creating a skill structure"

**Trigger Keywords**: Include discoverable terms in description
- Include: Task verbs (create, build, validate), domain terms (FHIR, deployment, testing)
- Context: Where skill applies (medical integration, API design, code review)

---

## 6-Step Creation Process

### Step 1: Understand Requirements

**Objective**: Clearly define what the skill should accomplish

**Questions to Answer**:
- What problem does this skill solve?
- Who will use this skill? (You, team, community)
- What domain knowledge must be captured?
- What workflows need to be documented?
- Are there existing skills to reference or patterns to follow?

**Output**: Clear problem statement and scope definition

**Example**:
```
Problem: Developers waste time figuring out Railway deployment for each project
Scope: Document Railway deployment workflow for Node.js + React apps
Users: Development team
Domain: Deployment, Railway, Docker, environment configuration
Patterns: Workflow-based (sequential steps)
```

**References**: See [references/converting-docs-to-skills.md](references/converting-docs-to-skills.md) for converting existing documentation

---

### Step 2: Plan Structure

**Objective**: Choose organizational pattern and plan file structure

**Choose Organizational Pattern** (see [4 Organizational Patterns](#4-organizational-patterns)):

1. **Workflow-based**: Sequential processes with clear steps
   - Use when: Deployment, API integration, testing workflows
   - Structure: Step 1 → Step 2 → Step 3 → Result

2. **Task-based**: Independent operations without order dependency
   - Use when: Utilities, troubleshooting guides, debugging
   - Structure: Task A, Task B, Task C (any order)

3. **Reference/Guidelines**: Standards, patterns, design systems
   - Use when: Design systems, coding standards, style guides
   - Structure: Concepts, guidelines, examples

4. **Capabilities-based**: Integrated feature suites with multiple entry points
   - Use when: Complex systems, multiple related workflows
   - Structure: Feature A, Feature B, Feature C (interconnected)

**Plan File Structure**:
```
skill-name/
├── SKILL.md (always)
├── references/ (if detailed guides needed)
│   ├── detailed-guide-1.md
│   └── detailed-guide-2.md
├── scripts/ (if automation needed)
│   └── helper-script.py
└── templates/ (if reusable patterns)
    └── template-file.md
```

**Progressive Disclosure Planning**:
- SKILL.md: <5,000 words (overview, quick start, key workflows)
- references/: Comprehensive details, long guides (10,000+ words okay)
- scripts/: Automation helpers (documented with --help)

**Output**: Organizational pattern chosen, file structure planned

**References**: See [references/reference-organization-strategies.md](references/reference-organization-strategies.md) for detailed planning

---

### Step 3: Initialize Skill

**Objective**: Create directory structure and scaffold files

**Manual Approach**:
```bash
# Create skill directory
mkdir -p .claude/skills/skill-name

# Create SKILL.md with frontmatter
cat > .claude/skills/skill-name/SKILL.md <<'EOF'
---
name: skill-name
description: [What it does]. Use when [triggers].
---

# Skill Name

## Overview
[Purpose in 1-2 sentences]

## Quick Start
[Basic usage]
EOF

# Create subdirectories if needed
mkdir -p .claude/skills/skill-name/references
mkdir -p .claude/skills/skill-name/scripts
```

**Automated Approach** (using scripts):
```bash
# Initialize with template
python scripts/init-skill.py skill-name --template workflow

# Initialize interactively
python scripts/init-skill.py skill-name --interactive
```

**YAML Frontmatter Template**:
```yaml
---
name: skill-name-in-hyphen-case
description: [What skill does in 1-2 sentences]. [Key features]. Use when [trigger scenarios with keywords].
---
```

**Description Formula**: What + Features + Triggers
- What: Primary purpose (1 sentence)
- Features: Key capabilities (optional, 1 sentence)
- Triggers: When to use with discoverable keywords (1 sentence)

**Output**: Directory structure created, SKILL.md scaffolded

**References**: See [references/yaml-frontmatter-complete-guide.md](references/yaml-frontmatter-complete-guide.md) for YAML details

---

### Step 4: Edit Content

**Objective**: Write comprehensive skill documentation

**SKILL.md Structure** (Workflow-based example):
```markdown
---
name: deployment-guide
description: Railway deployment workflow for Node.js + React apps...
---

# Deployment Guide

## Overview
Complete Railway deployment workflow for full-stack applications.

## Prerequisites
- Railway account
- GitHub repository
- Node.js project

## Workflow

### Step 1: Prepare Application
[Instructions]

### Step 2: Configure Railway
[Instructions]

### Step 3: Deploy
[Instructions]

### Step 4: Verify
[Instructions]

## Troubleshooting
Common issues and solutions. See [references/troubleshooting-guide.md](references/troubleshooting-guide.md) for comprehensive guide.

## References
- [Environment Configuration](references/environment-config.md)
- [Deployment Checklist](references/deployment-checklist.md)
```

**Writing Guidelines**:

1. **Use Imperative Voice**:
   - Good: "Configure environment variables"
   - Bad: "You should configure environment variables"

2. **Be Specific**:
   - Good: "Run `npm run build` to create production bundle"
   - Bad: "Build the application"

3. **Include Examples**:
   - Code blocks with actual examples
   - Before/after comparisons
   - Expected outputs

4. **Reference, Don't Duplicate**:
   - SKILL.md: Overview and workflow
   - references/: Detailed explanations
   - Link with: "See [references/file.md](references/file.md) for details"

**Output**: SKILL.md written, references created if needed

**References**: See [references/writing-style-imperative-guide.md](references/writing-style-imperative-guide.md) for writing standards

---

### Step 5: Package & Validate

**Objective**: Validate skill meets quality standards

**Validation Checklist**:

**YAML Frontmatter** (12 checks):
- [ ] Name in hyphen-case (no underscores, spaces, capitals)
- [ ] Description <1024 characters
- [ ] Description includes what skill does
- [ ] Description includes trigger keywords
- [ ] Description includes when to use
- [ ] Name matches directory name
- [ ] No optional fields with empty values
- [ ] Proper YAML syntax (no tabs, correct indentation)
- [ ] Description is complete sentence(s)
- [ ] Description specific (not vague)
- [ ] Trigger keywords discoverable
- [ ] Name descriptive and clear

**File Structure** (10 checks):
- [ ] SKILL.md exists and is primary file
- [ ] Directory structure clean (no unnecessary nesting)
- [ ] references/ used for detailed content (if applicable)
- [ ] scripts/ used for automation (if applicable)
- [ ] File names descriptive and consistent
- [ ] No duplicate content across files
- [ ] Cross-references working (links valid)
- [ ] Progressive disclosure followed
- [ ] Files organized logically
- [ ] No orphaned files

**Content Quality** (10 checks):
- [ ] SKILL.md <5,000 words
- [ ] Overview section clear and concise
- [ ] Quick start example included
- [ ] Imperative/infinitive voice used
- [ ] Code examples included where relevant
- [ ] No placeholder text (TODO, FIX, etc.)
- [ ] Terminology consistent
- [ ] Grammar and spelling correct
- [ ] Formatting consistent
- [ ] Content accurate and tested

**Automated Validation**:
```bash
# Validate skill structure
python scripts/validate-skill.py skill-name/

# Analyze description for trigger effectiveness
python scripts/analyze-description.py skill-name/

# Package skill for distribution
bash scripts/package-skill.sh skill-name/
```

**Output**: Skill validated, ready for use or distribution

**References**: See [references/validation-checklist-complete.md](references/validation-checklist-complete.md) for comprehensive validation

---

### Step 6: Iterate & Improve

**Objective**: Continuously improve skill based on usage

**Improvement Cycle**:

1. **Use skill in real scenarios**
   - Track what works well
   - Note confusion points
   - Identify missing information

2. **Gather feedback**
   - From team if shared
   - From own usage patterns
   - From Claude Code responses

3. **Identify improvements**
   - Add missing workflows
   - Clarify confusing sections
   - Enhance examples
   - Update for new patterns

4. **Update skill**
   - Edit SKILL.md
   - Update references
   - Add new examples
   - Re-validate

5. **Track evolution**
   - Version in git
   - Document changes
   - Share improvements

**Common Improvements**:
- Add troubleshooting section (most common)
- Include more examples (clarity)
- Expand quick start (easier onboarding)
- Reorganize for better flow (usability)
- Add scripts for automation (efficiency)

**Output**: Skill continuously improving over time

---

## Quick Start: 5-Minute Skill

Create a minimal but complete skill in 5 minutes:

### 1. Choose Name (30 seconds)
```bash
# Use hyphen-case, descriptive
my-skill-name  # Good
my_skill_name  # Bad (underscores)
MySkillName    # Bad (capitals)
```

### 2. Create Structure (1 minute)
```bash
mkdir -p .claude/skills/my-skill-name
cd .claude/skills/my-skill-name
```

### 3. Create SKILL.md (3 minutes)
```markdown
---
name: my-skill-name
description: Brief description of what skill does. Use when working on specific task or domain.
---

# My Skill Name

## Overview
One paragraph explaining purpose and value.

## Quick Start

### Basic Usage
1. First step
2. Second step
3. Third step

### Example
\`\`\`bash
# Example command or code
echo "Hello from skill"
\`\`\`

## When to Use
- Scenario 1
- Scenario 2
- Scenario 3

## References
- Link to external documentation if needed
```

### 4. Test (30 seconds)
```bash
# Test by invoking skill in Claude Code conversation
# "Use the my-skill-name skill to help with [task]"
```

### 5. Iterate
Add more content over time as you use the skill.

**Result**: Functional minimal skill in 5 minutes!

---

## 4 Organizational Patterns

### Pattern 1: Workflow-Based

**Use When**: Sequential processes with clear steps

**Structure**:
```markdown
## Workflow

### Step 1: [Action]
Instructions for step 1

### Step 2: [Action]
Instructions for step 2

### Step 3: [Action]
Instructions for step 3
```

**Examples**:
- Deployment workflows (prepare → configure → deploy → verify)
- API integration (authenticate → fetch → process → store)
- Testing workflows (setup → execute → validate → cleanup)

**Characteristics**:
- Order matters
- Each step builds on previous
- Clear progression
- Defined start and end points

**Best Practices**:
- Number steps clearly
- Include prerequisites at start
- Show expected outcomes for each step
- Provide troubleshooting per step

---

### Pattern 2: Task-Based

**Use When**: Independent operations without order dependency

**Structure**:
```markdown
## Tasks

### Task A: [Action]
Complete instructions for task A

### Task B: [Action]
Complete instructions for task B

### Task C: [Action]
Complete instructions for task C
```

**Examples**:
- Troubleshooting guides (different problems, different solutions)
- Utility collections (various independent tools)
- Command references (different operations)

**Characteristics**:
- Order doesn't matter
- Tasks are independent
- Can perform any subset
- Quick reference format

**Best Practices**:
- Make each task self-contained
- Use descriptive task names
- Include complete instructions per task
- Organize by category if many tasks

---

### Pattern 3: Reference/Guidelines

**Use When**: Standards, patterns, design systems, best practices

**Structure**:
```markdown
## Guidelines

### Guideline 1: [Concept]
Explanation and examples

### Guideline 2: [Concept]
Explanation and examples

## Reference

### Component A
Details and usage

### Component B
Details and usage
```

**Examples**:
- Design systems (colors, typography, components)
- Coding standards (style guide, patterns, conventions)
- API documentation (endpoints, parameters, responses)

**Characteristics**:
- Reference material
- Look-up format
- Examples and specifications
- Comprehensive coverage

**Best Practices**:
- Organize by category
- Include visual examples where applicable
- Provide usage examples
- Keep updated as standards evolve

---

### Pattern 4: Capabilities-Based

**Use When**: Integrated feature suites with multiple entry points

**Structure**:
```markdown
## Capabilities

### Capability A: [Feature]
How to use feature A
- Sub-feature 1
- Sub-feature 2

### Capability B: [Feature]
How to use feature B
- Sub-feature 1
- Sub-feature 2

## Integration
How capabilities work together
```

**Examples**:
- Complex systems (multiple interconnected features)
- Platforms (various ways to accomplish goals)
- Toolkits (collection of related capabilities)

**Characteristics**:
- Multiple features
- Features can be combined
- Flexible usage patterns
- Integration between features

**Best Practices**:
- Explain each capability clearly
- Show integration patterns
- Provide combination examples
- Include capability matrix

---

### Choosing the Right Pattern

**Decision Tree**:

1. **Is there a required sequence?**
   → Yes: **Workflow-based**
   → No: Go to 2

2. **Are operations independent?**
   → Yes: **Task-based**
   → No: Go to 3

3. **Is it primarily reference material?**
   → Yes: **Reference/Guidelines**
   → No: **Capabilities-based**

**Pattern Mixing**: You can combine patterns
- Primary pattern: Overall structure
- Secondary pattern: Individual sections

**Example**: Deployment skill might be:
- Primary: Workflow-based (deployment steps)
- Section: Reference (environment variables)
- Section: Task-based (troubleshooting)

---

## Progressive Disclosure Deep Dive

### The Three-Level System

**Level 1: SKILL.md** (Always Loaded)
- Size: <5,000 words ideal, <10,000 words maximum
- Content: Overview, quick start, primary workflows
- Purpose: Immediate context for Claude
- Loading: Automatic when skill invoked

**Level 2: references/** (On-Demand Loading)
- Size: Unlimited (10,000+ words okay)
- Content: Comprehensive guides, detailed explanations, specifications
- Purpose: Deep dives when needed
- Loading: Claude explicitly references when detail needed

**Level 3: scripts/** (Execution Loading)
- Size: Unlimited code
- Content: Automation scripts, validators, helpers
- Purpose: Executable tools
- Loading: When automation invoked

### When to Use Each Level

**Put in SKILL.md**:
- Skill overview and purpose
- Quick start guide
- Common workflows (80% use cases)
- Decision trees for choosing approaches
- Links to references for details

**Put in references/**:
- Comprehensive guides (>2,000 words)
- Detailed specifications
- In-depth explanations
- Reference tables and matrices
- Historical context
- Advanced techniques

**Put in scripts/**:
- Validation scripts
- Automation helpers
- Code generators
- Analysis tools
- Testing utilities

### Context Window Optimization

**Problem**: Large skills consume context window
**Solution**: Progressive disclosure

**Before Optimization** (Everything in SKILL.md):
```
SKILL.md: 15,000 words
Context used: ~30,000 tokens
Claude has: ~70,000 tokens remaining for work
```

**After Optimization** (Progressive disclosure):
```
SKILL.md: 3,000 words
references/: 12,000 words (loaded when needed)
Context used: ~6,000 tokens (initial)
Claude has: ~94,000 tokens remaining for work
```

**Result**: 5x context efficiency!

### Reference Linking Best Practices

**Good Reference Link**:
```markdown
For comprehensive YAML guide, see [references/yaml-frontmatter-complete-guide.md](references/yaml-frontmatter-complete-guide.md)
```

**What makes it good**:
- Clear description of what's in reference
- Full relative path
- Descriptive file name

**Bad Reference Link**:
```markdown
See the guide [here](references/guide.md)
```

**What's wrong**:
- Vague "here" link
- Non-descriptive file name
- Unclear what guide contains

---

## 10 Community Innovations

Patterns discovered from analyzing 40+ community skills:

### 1. Plan-Validate-Execute Pattern
**Innovation**: Explicit planning phase before execution
**Structure**:
```
1. Analyze requirements
2. Create plan
3. Validate plan with user
4. Execute plan
5. Validate results
```
**Benefit**: Fewer errors, user confidence, better outcomes

---

### 2. Feedback Loop Integration
**Innovation**: Built-in improvement cycles
**Structure**:
```
Execute → Measure → Analyze → Improve → Repeat
```
**Benefit**: Continuous improvement, self-correcting

---

### 3. Superpowers Workflow
**Innovation**: Multi-skill composition for complex tasks
**Structure**:
```
Skill A (research) → Skill B (plan) → Skill C (execute) → Skill D (validate)
```
**Benefit**: Compound capabilities, modular design

---

### 4. Size-Constrained Validation
**Innovation**: Automated checks for SKILL.md size
**Implementation**: Script validates <5,000 words, warns if exceeded
**Benefit**: Maintains context efficiency

---

### 5. Template-Driven Output
**Innovation**: Standardized output formats
**Structure**: templates/ directory with reusable formats
**Benefit**: Consistency, faster creation

---

### 6. Conditional Loading
**Innovation**: Load different references based on context
**Example**: Development vs Production guides
**Benefit**: Context-appropriate information

---

### 7. Domain-Specific Libraries
**Innovation**: Skill-specific helper libraries
**Example**: FHIR validation library for medical skills
**Benefit**: Reusable code, consistent validation

---

### 8. Category Organization
**Innovation**: Skills organized by category in repository
**Structure**: .claude/skills/[category]/[skill-name]/
**Benefit**: Easier navigation, logical grouping

---

### 9. Auto-Generated Documentation
**Innovation**: Scripts generate documentation from code
**Example**: API documentation from endpoint definitions
**Benefit**: Always up-to-date, reduced maintenance

---

### 10. Multi-Phase Validation
**Innovation**: Validation in multiple stages
**Phases**:
1. Syntax validation (YAML, Markdown)
2. Structure validation (files, organization)
3. Content validation (completeness, quality)
4. Functional validation (scripts work, links valid)
5. Integration validation (works with Claude)
**Benefit**: Comprehensive quality assurance

---

## Common Patterns Summary

**YAML Frontmatter**:
- name: hyphen-case, descriptive
- description: <1024 chars, what + triggers

**File Organization**:
- SKILL.md: <5,000 words
- references/: Detailed guides
- scripts/: Automation
- templates/: Reusable patterns

**Writing Style**:
- Imperative/infinitive voice
- Specific, actionable instructions
- Examples included
- Progressive disclosure

**Organizational Patterns**:
1. Workflow: Sequential steps
2. Task: Independent operations
3. Reference: Standards and guidelines
4. Capabilities: Integrated features

**See References**:
- [yaml-frontmatter-complete-guide.md](references/yaml-frontmatter-complete-guide.md)
- [writing-style-imperative-guide.md](references/writing-style-imperative-guide.md)
- [reference-organization-strategies.md](references/reference-organization-strategies.md)

---

## Automation Tools Overview

This skill includes 4 automation scripts:

### init-skill.py
**Purpose**: Initialize new skill with template
**Usage**:
```bash
python scripts/init-skill.py skill-name [--template PATTERN] [--interactive]
```
**Features**:
- Scaffolds directory structure
- Creates SKILL.md with frontmatter
- Supports 5 templates (minimal, workflow, task, reference, capabilities)
- Interactive mode for guided setup

---

### validate-skill.py
**Purpose**: Multi-phase skill validation
**Usage**:
```bash
python scripts/validate-skill.py skill-name/
```
**Validation Phases**:
1. YAML frontmatter (12 checks)
2. File structure (10 checks)
3. Content quality (10 checks)
4. Script functionality (10 checks)
5. Advanced validation (links, duplication, size)
**Exit Codes**: 0=pass, 1=fixable errors, 2=fatal errors

---

### analyze-description.py
**Purpose**: Analyze description for trigger effectiveness
**Usage**:
```bash
python scripts/analyze-description.py skill-name/
```
**Analysis**:
- Trigger keyword extraction
- Action verb detection
- Technology/domain term detection
- Specificity scoring (0-100)
- Improvement suggestions

---

### package-skill.sh
**Purpose**: Package skill for distribution
**Usage**:
```bash
bash scripts/package-skill.sh skill-name/
```
**Process**:
1. Validates skill
2. Creates zip archive
3. Excludes system files (.DS_Store, etc.)
4. Outputs to dist/

**See**: [references/script-integration-patterns.md](references/script-integration-patterns.md) for script development guide

---

## Troubleshooting Quick Fixes

### Issue: Claude doesn't invoke skill

**Causes**:
- Vague description lacking trigger keywords
- Name not discoverable
- Skill not in .claude/skills/ directory

**Fixes**:
1. Add trigger keywords to description
2. Use task-specific verbs (deploy, validate, analyze)
3. Include domain terms (FHIR, Railway, testing)
4. Verify skill location: .claude/skills/skill-name/SKILL.md

---

### Issue: SKILL.md too large

**Causes**:
- All details in SKILL.md
- Not using progressive disclosure

**Fixes**:
1. Move detailed guides to references/
2. Keep SKILL.md <5,000 words
3. Link to references for details
4. Use scripts/ for code examples

---

### Issue: Content feels duplicated

**Causes**:
- Repeating information across files
- Not using references properly

**Fixes**:
1. Consolidate duplicate content
2. Use single source of truth
3. Link to authoritative source
4. See [references/anti-patterns-and-fixes.md](references/anti-patterns-and-fixes.md)

---

### Issue: Validation fails

**Causes**:
- YAML syntax errors
- Missing required fields
- File structure issues

**Fixes**:
1. Run `python scripts/validate-skill.py skill-name/`
2. Check YAML indentation (spaces not tabs)
3. Verify name matches directory
4. Ensure description <1024 characters

---

### Issue: Skills not improving

**Causes**:
- No iteration process
- Not tracking feedback
- No usage analysis

**Fixes**:
1. Establish improvement cycle
2. Track usage patterns
3. Gather feedback regularly
4. Version in git for history
5. See [Step 6: Iterate & Improve](#step-6-iterate--improve)

---

## Next Steps

**To Learn More**:
- Read [references/yaml-frontmatter-complete-guide.md](references/yaml-frontmatter-complete-guide.md) for YAML details
- Read [references/progressive-disclosure-architecture.md](references/progressive-disclosure-architecture.md) for context optimization
- Read [references/validation-checklist-complete.md](references/validation-checklist-complete.md) for quality standards

**To Create Your First Skill**:
1. Follow [Quick Start: 5-Minute Skill](#quick-start-5-minute-skill)
2. Use [Step 1: Understand Requirements](#step-1-understand-requirements) to define scope
3. Apply [4 Organizational Patterns](#4-organizational-patterns) to choose structure
4. Build iteratively using [6-Step Process](#6-step-creation-process)

**To Use Templates**:
- See templates/ directory for 5 ready-to-use patterns
- Copy template matching your needs
- Customize for your domain

**To Validate Quality**:
- Run `python scripts/validate-skill.py skill-name/`
- Review [references/validation-checklist-complete.md](references/validation-checklist-complete.md)
- Analyze description with `python scripts/analyze-description.py skill-name/`

---

**Version**: 1.0
**Research**: 11 sources, 40+ community skills analyzed
**Last Updated**: October 25, 2025
**Skill Type**: Reference/Guidelines (meta-skill for creating skills)