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:
  • Good: "API Documentation Generator"
  • Good: "React Component Builder"
  • Good: "Database Schema Designer"
  • Bad: "skill-1" (not descriptive)
  • Bad: "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:
  • Good: "Generate OpenAPI 3.0 documentation from Express.js routes. Use when creating API docs, documenting endpoints, or building API specifications."
  • Good: "Create React functional components with TypeScript, hooks, and tests. Use when scaffolding new components or converting class components."
  • Bad: "A comprehensive guide to API documentation" (no "when" clause)
  • Bad: "Documentation tool" (too vague)