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

...