Skills
skills/adaptationio/skrillz/skill-builder-generic

skill-builder-generic

SKILL.md

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:

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:

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:

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

Weekly Installs
1
Repository
adaptationio/skrillz
Installed on
claude-code1