adaptationio/skill-builder-generic

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 for converting existing documentation

---

Step 2: Plan Structure

Objective: Choose organizational pattern and plan file structure

Choose Organizational Pattern (see 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 for detailed planning

---

Step 3: Initialize Skill

Objective: Create directory structure and scaffold files

Manual Approach:

# 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):

# 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:

---
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 for YAML details

---

Step 4: Edit Content

Objective: Write comprehensive skill documentation

SKILL.md Structure (Workflow-based example):

---
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 for details"

Output: SKILL.md written, references created if needed

References: See 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:

# 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 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)

# Use hyphen-case, descriptive
my-skill-name  # Good
my_skill_name  # Bad (underscores)
MySkillName    # Bad (capitals)

2. Create Structure (1 minute)

mkdir -p .claude/skills/my-skill-name
cd .claude/skills/my-skill-name

3. Create SKILL.md (3 minutes)

---
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)

# 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:

## 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:

## 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:

## 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:

## 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:

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:

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
• writing-style-imperative-guide.md
• reference-organization-strategies.md

---

Automation Tools Overview

This skill includes 4 automation scripts:

init-skill.py

Purpose: Initialize new skill with template Usage:

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:

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:

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 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 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

---

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

---

Next Steps

To Learn More:

• Read references/yaml-frontmatter-complete-guide.md for YAML details
• Read references/progressive-disclosure-architecture.md for context optimization
• Read references/validation-checklist-complete.md for quality standards

To Create Your First Skill:

1. Follow Quick Start: 5-Minute Skill
2. Use Step 1: Understand Requirements to define scope
3. Apply 4 Organizational Patterns to choose structure
4. Build iteratively using 6-Step 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
• 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)