skill-builder-generic

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)

---

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

1. Task-based: Independent operations without order dependency

- Use when: Utilities, troubleshooting guides, debugging

- Structure: Task A, Task B, Task C (any order)

1. Reference/Guidelines: Standards, patterns, design systems

- Use when: Design systems, coding standards, style guides

- Structure: Concepts, guidelines, examples

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

[Purpose in 1-2 sentences]

[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

Complete Railway deployment workflow for full-stack applications.

• Railway account
• GitHub repository
• Node.js project

Step 1: Prepare Application

[Instructions]

Step 2: Configure Railway

[Instructions]

Step 3: Deploy

[Instructions]

Step 4: Verify

[Instructions]

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

• [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"

1. Be Specific:

- Good: "Run npm run build to create production bundle"

- Bad: "Build the application"

1. Include Examples:

- Code blocks with actual examples

- Before/after comparisons

- Expected outputs

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

1. Gather feedback

- From team if shared

- From own usage patterns

- From Claude Code responses

1. Identify improvements

- Add missing workflows

- Clarify confusing sections

- Enhance examples

- Update for new patterns

1. Update skill

- Edit SKILL.md

- Update references

- Add new examples

- Re-validate

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

---

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

One paragraph explaining purpose and value.

Basic Usage

1. First step
2. Second step
3. Third step

Example

\\\`bash

# Example command or code

echo "Hello from skill"

\\\`

• Scenario 1
• Scenario 2
• Scenario 3

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

---

Pattern 1: Workflow-Based

Use When: Sequential processes with clear steps

Structure:

```markdown

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

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

Guideline 1: [Concept]

Explanation and examples

Guideline 2: [Concept]

Explanation and examples

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

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

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

1. Are operations independent?

→ Yes: Task-based

→ No: Go to 3

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

---

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

---

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

---

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)

---

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

---

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)

---

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)