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

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](https://github.com/proffesor-for-testing/agentic-qe/blob/HEAD/.claude/skills/skill-builder/docs/API_REFERENCE.md)

### Examples

See [examples/](https://github.com/proffesor-for-testing/agentic-qe/blob/HEAD/.claude/skills/skill-builder/resources/examples/)

### Related Skills

- [Related Skill 1](#)
- [Related Skill 2](#)

### Resources

- [External Link 1](https://example.com)
- [Documentation](https://docs.example.com)

🎨 Content Best Practices

Writing Effective Descriptions

Front-Load Keywords:

# ✅ 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 (Overview):

## What This Skill Does
Creates production-ready React components with TypeScript, hooks, and tests in 3 steps.

Level 2 for Common Paths (Quick Start):

## Quick Start

Most common use case (80% of users)

generate-component MyComponent

Level 3 for Details (Step-by-Step):

## Step-by-Step Guide

### Creating a Basic Component
1. Run generator
2. Choose template
3. Customize options
[Detailed explanations]

Level 4 for Edge Cases (Reference):

## Advanced Configuration
For complex scenarios like HOCs, render props, or custom hooks, see [ADVANCED.md](docs/ADVANCED.md).

🛠️ Adding Scripts and Resources

Scripts Directory

Purpose: Executable scripts that Claude can run Location: scripts/ in skill directory Usage: Referenced from SKILL.md

Example:

# In skill directory
scripts/
├── setup.sh          # Initialization script
├── validate.js       # Validation logic
├── generate.py       # Code generation
└── deploy.sh         # Deployment script

Reference from SKILL.md:

## Setup
Run the setup script:

./scripts/setup.sh

## Validation

Validate your configuration:

node scripts/validate.js config.json

Resources Directory

Purpose: Templates, examples, schemas, static files Location: resources/ in skill directory Usage: Referenced or copied by scripts

Example:

resources/
├── templates/
│   ├── component.tsx.template
│   ├── test.spec.ts.template
│   └── story.stories.tsx.template
├── examples/
│   ├── basic-example/
│   ├── advanced-example/
│   └── integration-example/
└── schemas/
    ├── config.schema.json
    └── output.schema.json

Reference from SKILL.md:

## Templates
Use the component template:

cp resources/templates/component.tsx.template src/components/MyComponent.tsx

## Examples

See working examples in `resources/examples/`:

- `basic-example/` - Simple component
- `advanced-example/` - With hooks and context

🔗 File References and Navigation

Claude can navigate to referenced files automatically. Use these patterns:

Markdown Links

See [Advanced Configuration](docs/ADVANCED.md) for complex scenarios.
See [Troubleshooting Guide](docs/TROUBLESHOOTING.md) if you encounter errors.

Relative File Paths

Use the template located at `resources/templates/api-template.js`
See examples in `resources/examples/basic-usage/`

Inline File Content

## Example Configuration
See `resources/examples/config.json`:

{ "option": "value" }

Best Practice: Keep SKILL.md lean (~2-5KB). Move lengthy content to separate files and reference them. Claude will load only what's needed.

✅ Validation Checklist

Before publishing a skill, verify:

YAML Frontmatter:

• [ ] Starts with ---
• [ ] Contains name field (max 64 chars)
• [ ] Contains description field (max 1024 chars)
• [ ] Description includes "what" and "when"
• [ ] Ends with ---
• [ ] No YAML syntax errors

File Structure:

• [ ] SKILL.md exists in skill directory
• [ ] Directory is DIRECTLY in ~/.claude/skills/[skill-name]/ or .claude/skills/[skill-name]/
• [ ] Uses clear, descriptive directory name
• [ ] NO nested subdirectories (Claude Code requires top-level structure)

Content Quality:

• [ ] Level 1 (Overview) is brief and clear
• [ ] Level 2 (Quick Start) shows common use case
• [ ] Level 3 (Details) provides step-by-step guide
• [ ] Level 4 (Reference) links to advanced content
• [ ] Examples are concrete and runnable
• [ ] Troubleshooting section addresses common issues

Progressive Disclosure:

• [ ] Core instructions in SKILL.md (~2-5KB)
• [ ] Advanced content in separate docs/
• [ ] Large resources in resources/ directory
• [ ] Clear navigation between levels

Testing:

• [ ] Skill appears in Claude's skill list
• [ ] Description triggers on relevant queries
• [ ] Instructions are clear and actionable
• [ ] Scripts execute successfully (if included)
• [ ] Examples work as documented

Skill Builder Templates

Template 1: Basic Skill (Minimal)

---
name: "My Basic Skill"
description: "One sentence what. One sentence when to use."
---

# My Basic Skill

## What This Skill Does
[2-3 sentences describing functionality]

## Quick Start

Single command to get started

## Step-by-Step Guide

### Step 1: Setup

[Instructions]

### Step 2: Usage

[Instructions]

### Step 3: Verify

[Instructions]

## Troubleshooting

- **Issue**: Problem description
  - **Solution**: Fix description

Template 2: Intermediate Skill (With Scripts)

---
name: "My Intermediate Skill"
description: "Detailed what with key features. When to use with specific triggers: scaffolding, generating, building."
---

# My Intermediate Skill

## Prerequisites
- Requirement 1
- Requirement 2

## What This Skill Does
1. Primary function
2. Secondary function
3. Integration capability

## Quick Start

./scripts/setup.sh ./scripts/generate.sh my-project

## Configuration

Edit `config.json`:

{ "option1": "value1", "option2": "value2" }

## Step-by-Step Guide

### Basic Usage

[Steps for 80% use case]

### Advanced Usage

[Steps for complex scenarios]

## Available Scripts

- `scripts/setup.sh` - Initial setup
- `scripts/generate.sh` - Code generation
- `scripts/validate.sh` - Validation

## Resources

- Templates: `resources/templates/`
- Examples: `resources/examples/`

## Troubleshooting

[Common issues and solutions]

Template 3: Advanced Skill (Full-Featured)

---
name: "My Advanced Skill"
description: "Comprehensive what with all features and integrations. Use when [trigger 1], [trigger 2], or [trigger 3]. Supports [technology stack]."
---

# My Advanced Skill

## Overview
[Brief 2-3 sentence description]

## Prerequisites
- Technology 1 (version X+)
- Technology 2 (version Y+)
- API keys or credentials

## What This Skill Does
1. **Core Feature**: Description
2. **Integration**: Description
3. **Automation**: Description

---

## Quick Start (60 seconds)

### Installation

./scripts/install.sh

### First Use

./scripts/quickstart.sh

Expected output:

✓ Setup complete ✓ Configuration validated → Ready to use

---

## Configuration

### Basic Configuration

Edit `config.json`:

{ "mode": "production", "features": ["feature1", "feature2"] }

### Advanced Configuration

See [Configuration Guide](https://github.com/proffesor-for-testing/agentic-qe/blob/HEAD/.claude/skills/skill-builder/docs/CONFIGURATION.md)

---

## Step-by-Step Guide

### 1. Initial Setup

[Detailed steps]

### 2. Core Workflow

[Main procedures]

### 3. Integration

[Integration steps]

---

## Advanced Features

### Feature 1: Custom Templates

./scripts/generate.sh --template custom

### Feature 2: Batch Processing

./scripts/batch.sh --input data.json

### Feature 3: CI/CD Integration

See [CI/CD Guide](https://github.com/proffesor-for-testing/agentic-qe/blob/HEAD/.claude/skills/skill-builder/docs/CICD.md)

---

## Scripts Reference

| Script | Purpose | Usage |
| --- | --- | --- |
| `install.sh` | Install dependencies | `./scripts/install.sh` |
| `generate.sh` | Generate code | `./scripts/generate.sh [name]` |
| `validate.sh` | Validate output | `./scripts/validate.sh` |
| `deploy.sh` | Deploy to environment | `./scripts/deploy.sh [env]` |

---

## Resources

### Templates

- `resources/templates/basic.template` - Basic template
- `resources/templates/advanced.template` - Advanced template

### Examples

- `resources/examples/basic/` - Simple example
- `resources/examples/advanced/` - Complex example
- `resources/examples/integration/` - Integration example

### Schemas

- `resources/schemas/config.schema.json` - Configuration schema
- `resources/schemas/output.schema.json` - Output validation

---

## Troubleshooting

### Issue: Installation Failed

**Symptoms**: Error during `install.sh` **Cause**: Missing dependencies **Solution**:

Install prerequisites

npm install -g required-package ./scripts/install.sh --force

### Issue: Validation Errors

**Symptoms**: Validation script fails **Solution**: See [Troubleshooting Guide](https://github.com/proffesor-for-testing/agentic-qe/blob/HEAD/.claude/skills/skill-builder/docs/TROUBLESHOOTING.md)

---

## API Reference

Complete API documentation: [API_REFERENCE.md](https://github.com/proffesor-for-testing/agentic-qe/blob/HEAD/.claude/skills/skill-builder/docs/API_REFERENCE.md)

## Related Skills

- [Related Skill 1](https://github.com/proffesor-for-testing/agentic-qe/blob/HEAD/.claude/skills/skill-builder/../related-skill-1/)
- [Related Skill 2](https://github.com/proffesor-for-testing/agentic-qe/blob/HEAD/.claude/skills/skill-builder/../related-skill-2/)

## Resources

- [Official Documentation](https://example.com/docs)
- [GitHub Repository](https://github.com/example/repo)
- [Community Forum](https://forum.example.com)

---

**Created**: 2025-10-19 **Category**: Advanced **Difficulty**: Intermediate **Estimated Time**: 15-30 minutes

Micro-File Step Architecture (BMAD-006)

For complex skills that exceed 1,000 lines, use the micro-file step architecture to combat LLM "lost in the middle" context degradation. When a skill's SKILL.md grows beyond a certain threshold, the LLM loses critical details in the middle of the file. Splitting into step files ensures each step gets full attention.

When to Apply

Directory Convention

my-skill/ SKILL.md # Compact orchestrator (200-300 lines) steps/ 01-first-step.md # Self-contained step file 02-second-step.md 03-third-step.md...

Step File Format

Each step file MUST be self-contained and include:

1. Title with step number
2. Prerequisites listing what data is needed from prior steps
3. Instructions with complete details (no references back to SKILL.md)
4. Success Criteria as a checklist
5. Output describing what this step produces
6. Navigation with explicit Read tool instructions for the next step

Example step file:

# Step 3: Wait for Core Agent Results

## Prerequisites
- Step 2 completed (all core agents spawned)

## Instructions
STOP. Do not proceed until all three background tasks from Step 2 return.

When all agents complete, extract these metrics:
- Metric A from Agent 1
- Metric B from Agent 2
- Metric C from Agent 3

## Success Criteria
- [ ] All core agents completed
- [ ] All metrics extracted and recorded

## Output
Metrics summary for use in Step 4.

## Navigation
- On success: proceed to Step 4 by reading `steps/04-next-step.md`
- On failure: retry failed agents from Step 2

Orchestrator Format

The rewritten SKILL.md orchestrator MUST include:

1. YAML frontmatter (preserved exactly from original)
2. Title and overview (brief description of the skill)
3. Parameters section
4. Enforcement rules table
5. Step Execution Protocol with:

- Numbered step list with file paths - Explicit Read tool instructions (e.g., Read({file_path: "..."})) - Resume support via --from-step N

1. Agent/component inventory table
2. Quality gate thresholds (if applicable)
3. Key principle closing statement

The orchestrator should be 200-300 lines. All procedural detail lives in step files.

Key Rules

• Step files MUST be under 500 lines each
• Step files MUST NOT reference content in SKILL.md (self-contained)
• Step files MUST include explicit Read() instructions for the next step (Gap 9 fix)
• ALL original content MUST be preserved across step files -- nothing is deleted
• The orchestrator is a table of contents and control flow, not a content dump

Reference Implementation

See the QCSD swarm skills for working examples:

• qcsd-production-swarm/ -- 12 agents, 9 steps, feedback loop
• qcsd-refinement-swarm/ -- 10 agents, 9 steps, test idea rewriter
• qcsd-cicd-swarm/ -- 10 agents, 9 steps, deployment advisor
• qcsd-development-swarm/ -- 10 agents, 9 steps, defect predictor
• qcsd-ideation-swarm/ -- 9 agents, 8 steps, URL browser cascade

Examples from the Wild

Example 1: Simple Documentation Skill

---
name: "README Generator"
description: "Generate comprehensive README.md files for GitHub repositories. Use when starting new projects, documenting code, or improving existing READMEs."
---

# README Generator

## What This Skill Does
Creates well-structured README.md files with badges, installation, usage, and contribution sections.

## Quick Start

Answer a few questions

./scripts/generate-readme.sh

README.md created with:

- Project title and description

- Installation instructions

- Usage examples

- Contribution guidelines

## Customization

Edit sections in `resources/templates/sections/` before generating.

Example 2: Code Generation Skill

---
name: "React Component Generator"
description: "Generate React functional components with TypeScript, hooks, tests, and Storybook stories. Use when creating new components, scaffolding UI, or following component architecture patterns."
---

# React Component Generator

## Prerequisites
- Node.js 18+
- React 18+
- TypeScript 5+

## Quick Start

./scripts/generate-component.sh MyComponent

Creates:

- src/components/MyComponent/MyComponent.tsx

- src/components/MyComponent/MyComponent.test.tsx

- src/components/MyComponent/MyComponent.stories.tsx

- src/components/MyComponent/index.ts

## Step-by-Step Guide

### 1. Run Generator

./scripts/generate-component.sh ComponentName

### 2. Choose Template

- Basic: Simple functional component
- With State: useState hooks
- With Context: useContext integration
- With API: Data fetching component

### 3. Customize

Edit generated files in `src/components/ComponentName/`

## Templates

See `resources/templates/` for available component templates.

Learn More

Official Resources

• Anthropic Agent Skills Documentation
• GitHub Skills Repository
• Claude Code Documentation

Community

• Skills Marketplace - Browse community skills
• Anthropic Discord - Get help from community

Advanced Topics

• Multi-file skills with complex navigation
• Skills that spawn other skills
• Integration with MCP tools
• Dynamic skill generation

Created: 2025-10-19 Version: 1.0.0 Maintained By: agentic-flow team License: MIT