skill-builder

Skill Builder

What This Skill Does

Creates production-ready Claude Code Skills with proper YAML frontmatter, progressive disclosure architecture, and complete file$folder structure. This skill guides you through building skills that Claude can autonomously discover and use across all surfaces (Claude.ai, Claude Code, SDK, API).

Prerequisites

• Claude Code 2.0+ or Claude.ai with Skills support
• Basic understanding of Markdown and YAML
• Text editor or IDE

Quick Start

Creating Your First Skill

# 1. Create skill directory (MUST be at top level, NOT in subdirectories!)
mkdir -p ~/.claude$skills$my-first-skill

# 2. Create SKILL.md with proper format
cat > ~/.claude$skills$my-first-skill/SKILL.md << 'EOF'
---
name: "My First Skill"
description: "Brief description of what this skill does and when Claude should use it. Maximum 1024 characters."
---

# My First Skill

## What This Skill Does
[Your instructions here]

## Quick Start
[Basic usage]
EOF

# 3. Verify skill is detected
# Restart Claude Code or refresh Claude.ai

---

Complete Specification

📋 YAML Frontmatter (REQUIRED)

Every SKILL.md must start with YAML frontmatter containing exactly two required fields:

---
name: "Skill Name"                    # REQUIRED: Max 64 chars
description: "What this skill does    # REQUIRED: Max 1024 chars
and when Claude should use it."       # Include BOTH what & when
---

Field Requirements

name (REQUIRED):

• Type: String
• Max Length: 64 characters
• Format: Human-friendly display name
• Usage: Shown in skill lists, UI, and loaded into Claude's system prompt
• Best Practice: Use Title Case, be concise and descriptive
• Examples:
  • ✅ "API Documentation Generator"
  • ✅ "React Component Builder"
  • ✅ "Database Schema Designer"
  • ❌ "skill-1" (not descriptive)
  • ❌ "This is a very long skill name that exceeds sixty-four characters" (too long)

description (REQUIRED):

• Type: String
• Max Length: 1024 characters
• Format: Plain text or minimal markdown
• Content: MUST include:
  1. What the skill does (functionality)
  2. When Claude should invoke it (trigger conditions)
• Usage: Loaded into Claude's system prompt for autonomous matching
• Best Practice: Front-load key trigger words, be specific about use cases
• Examples:
  • ✅ "Generate OpenAPI 3.0 documentation from Express.js routes. Use when creating API docs, documenting endpoints, or building API specifications."
  • ✅ "Create React functional components with TypeScript, hooks, and tests. Use when scaffolding new components or converting class components."
  • ❌ "A comprehensive guide to API documentation" (no "when" clause)
  • ❌ "Documentation tool" (too vague)

YAML Formatting Rules

---
# ✅ CORRECT: Simple string
name: "API Builder"
description: "Creates REST APIs with Express and TypeScript."

# ✅ CORRECT: Multi-line description
name: "Full-Stack Generator"
description: "Generates full-stack applications with React frontend and Node.js backend. Use when starting new projects or scaffolding applications."

# ✅ CORRECT: Special characters quoted
name: "JSON:API Builder"
description: "Creates JSON:API compliant endpoints: pagination, filtering, relationships."

# ❌ WRONG: Missing quotes with special chars
name: API:Builder  # YAML parse error!

# ❌ WRONG: Extra fields (ignored but discouraged)
name: "My Skill"
description: "My description"
version: "1.0.0"       # NOT part of spec
author: "Me"           # NOT part of spec
tags: ["dev", "api"]   # NOT part of spec
---

Critical: Only name and description are used by Claude. Additional fields are ignored.

---

📂 Directory Structure

Minimal Skill (Required)

~/.claude$skills/                    # Personal skills location
└── my-skill/                        # Skill directory (MUST be at top level!)
    └── SKILL.md                     # REQUIRED: Main skill file

IMPORTANT: Skills MUST be directly under ~/.claude$skills/[skill-name]/. Claude Code does NOT support nested subdirectories or namespaces!

Full-Featured Skill (Recommended)

~/.claude$skills/
└── my-skill/                        # Top-level skill directory
        ├── SKILL.md                 # REQUIRED: Main skill file
        ├── README.md                # Optional: Human-readable docs
        ├── scripts/                 # Optional: Executable scripts
        │   ├── setup.sh
        │   ├── validate.js
        │   └── deploy.py
        ├── resources/               # Optional: Supporting files
        │   ├── templates/
        │   │   ├── api-template.js
        │   │   └── component.tsx
        │   ├── examples/
        │   │   └── sample-output.json
        │   └── schemas/
        │       └── config-schema.json
        └── docs/                    # Optional: Additional documentation
            ├── ADVANCED.md
            ├── TROUBLESHOOTING.md
            └── API_REFERENCE.md

Skills Locations

Personal Skills (available across all projects):

~/.claude$skills/
└── [your-skills]/

• Path: ~/.claude$skills/ or $HOME/.claude$skills/
• Scope: Available in all projects for this user
• Version Control: NOT committed to git (outside repo)
• Use Case: Personal productivity tools, custom workflows

Project Skills (team-shared, version controlled):

<project-root>/.claude$skills/
└── [team-skills]/

• Path: .claude$skills/ in project root
• Scope: Available only in this project
• Version Control: SHOULD be committed to git
• Use Case: Team workflows, project-specific tools, shared knowledge

---

🎯 Progressive Disclosure Architecture

Claude Code uses a 3-level progressive disclosure system to scale to 100+ skills without context penalty:

Level 1: Metadata (Name + Description)

Loaded: At Claude Code startup, always Size: ~200 chars per skill Purpose: Enable autonomous skill matching Context: Loaded into system prompt for ALL skills

---
name: "API Builder"                   # 11 chars
description: "Creates REST APIs..."   # ~50 chars
---
# Total: ~61 chars per skill
# 100 skills = ~6KB context (minimal!)

Level 2: SKILL.md Body

Loaded: When skill is triggered$matched Size: ~1-10KB typically Purpose: Main instructions and procedures Context: Only loaded for ACTIVE skills

# API Builder

## What This Skill Does
[Main instructions - loaded only when skill is active]

## Quick Start
[Basic procedures]

## Step-by-Step Guide
[Detailed instructions]

Level 3+: Referenced Files

Loaded: On-demand as Claude navigates Size: Variable (KB to MB) Purpose: Deep reference, examples, schemas Context: Loaded only when Claude accesses specific files

# In SKILL.md
See [Advanced Configuration](docs/ADVANCED.md) for complex scenarios.
See [API Reference](docs/API_REFERENCE.md) for complete documentation.
Use template: `resources$templates$api-template.js`

# Claude will load these files ONLY if needed

Benefit: Install 100+ skills with ~6KB context. Only active skill content (1-10KB) enters context.

---

📝 SKILL.md Content Structure

Recommended 4-Level Structure

---
name: "Your Skill Name"
description: "What it does and when to use it"
---

# Your Skill Name

## Level 1: Overview (Always Read First)
Brief 2-3 sentence description of the skill.

## Prerequisites
- Requirement 1
- Requirement 2

## What This Skill Does
1. Primary function
2. Secondary function
3. Key benefit

---

## Level 2: Quick Start (For Fast Onboarding)

### Basic Usage
```bash
# Simplest use case
command --option value

Common Scenarios

1. Scenario 1: How to...
2. Scenario 2: How to...

---

Level 3: Detailed Instructions (For Deep Work)

Step-by-Step Guide

Step 1: Initial Setup

# Commands

Expected output:

Success message

Step 2: Configuration

• Configuration option 1
• Configuration option 2

Step 3: Execution

• Run the main command
• Verify results

Advanced Options

Option 1: Custom Configuration

# Advanced usage

Option 2: Integration

# Integration steps

---

Level 4: Reference (Rarely Needed)

Troubleshooting

Issue: Common Problem

Symptoms: What you see Cause: Why it happens Solution: How to fix

# Fix command

Issue: Another Problem

Solution: Steps to resolve

Complete API Reference

See API_REFERENCE.md

Examples

See examples/

Related Skills

• Related Skill 1
• Related Skill 2

Resources

• External Link 1
• Documentation

---

### 🎨 Content Best Practices

#### Writing Effective Descriptions

**Front-Load Keywords**:
```yaml
# ✅ GOOD: Keywords first
description: "Generate TypeScript interfaces from JSON schema. Use when converting schemas, creating types, or building API clients."

# ❌ BAD: Keywords buried
description: "This skill helps developers who need to work with JSON schemas by providing a way to generate TypeScript interfaces."

Include Trigger Conditions:

# ✅ GOOD: Clear "when" clause
description: "Debug React performance issues using Chrome DevTools. Use when components re-render unnecessarily, investigating slow updates, or optimizing bundle size."

# ❌ BAD: No trigger conditions
description: "Helps with React performance debugging."

Be Specific:

# ✅ GOOD: Specific technologies
description: "Create Express.js REST endpoints with Joi validation, Swagger docs, and Jest tests. Use when building new APIs or adding endpoints."

# ❌ BAD: Too generic
description: "Build API endpoints with proper validation and testing."

Progressive Disclosure Writing

Keep Level 1 Brief (Overv

---

Content truncated.