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:

code

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

•
Workflow-based: Sequential processes with clear steps
- •Use when: Deployment, API integration, testing workflows
- •Structure: Step 1 → Step 2 → Step 3 → Result
•
Task-based: Independent operations without order dependency
- •Use when: Utilities, troubleshooting guides, debugging
- •Structure: Task A, Task B, Task C (any order)
•
Reference/Guidelines: Standards, patterns, design systems
- •Use when: Design systems, coding standards, style guides
- •Structure: Concepts, guidelines, examples
•
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:

code

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:

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

•
Use Imperative Voice:
- •Good: "Configure environment variables"
- •Bad: "You should configure environment variables"
•
Be Specific:
- •Good: "Run npm run build to create production bundle"
- •Bad: "Build the application"
•
Include Examples:
- •Code blocks with actual examples
- •Before/after comparisons
- •Expected outputs
•
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):

File Structure (10 checks):

Content Quality (10 checks):

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 for comprehensive validation

Step 6: Iterate & Improve

Objective: Continuously improve skill based on usage

Improvement Cycle:

•
Use skill in real scenarios
- •Track what works well
- •Note confusion points
- •Identify missing information
•
Gather feedback
- •From team if shared
- •From own usage patterns
- •From Claude Code responses
•
Identify improvements
- •Add missing workflows
- •Clarify confusing sections
- •Enhance examples
- •Update for new patterns
•
Update skill
- •Edit SKILL.md
- •Update references
- •Add new examples
- •Re-validate
•
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:

•
Is there a required sequence? → Yes: Workflow-based → No: Go to 2
•
Are operations independent? → Yes: Task-based → No: Go to 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):

code

SKILL.md: 15,000 words
Context used: ~30,000 tokens
Claude has: ~70,000 tokens remaining for work

After Optimization (Progressive disclosure):

code

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:

code

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:

code

Execute → Measure → Analyze → Improve → Repeat

Benefit: Continuous improvement, self-correcting

3. Superpowers Workflow

Innovation: Multi-skill composition for complex tasks Structure:

code

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:

•Syntax validation (YAML, Markdown)
•Structure validation (files, organization)
•Content validation (completeness, quality)
•Functional validation (scripts work, links valid)
•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:

•Workflow: Sequential steps
•Task: Independent operations
•Reference: Standards and guidelines
•Capabilities: Integrated features

See References:

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:

•YAML frontmatter (12 checks)
•File structure (10 checks)
•Content quality (10 checks)
•Script functionality (10 checks)
•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:

•Validates skill
•Creates zip archive
•Excludes system files (.DS_Store, etc.)
•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:

•Add trigger keywords to description
•Use task-specific verbs (deploy, validate, analyze)
•Include domain terms (FHIR, Railway, testing)
•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:

•Move detailed guides to references/
•Keep SKILL.md <5,000 words
•Link to references for details
•Use scripts/ for code examples

Issue: Content feels duplicated

Causes:

•Repeating information across files
•Not using references properly

Fixes:

•Consolidate duplicate content
•Use single source of truth
•Link to authoritative source
•See references/anti-patterns-and-fixes.md

Issue: Validation fails

Causes:

•YAML syntax errors
•Missing required fields
•File structure issues

Fixes:

•Run python scripts/validate-skill.py skill-name/
•Check YAML indentation (spaces not tabs)
•Verify name matches directory
•Ensure description <1024 characters

Issue: Skills not improving

Causes:

•No iteration process
•Not tracking feedback
•No usage analysis

Fixes:

•Establish improvement cycle
•Track usage patterns
•Gather feedback regularly
•Version in git for history
•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:

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