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

Complete Specification

📋 YAML Frontmatter (REQUIRED)

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

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

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

📂 Directory Structure

Minimal Skill (Required)

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

Full-Featured Skill (Recommended)

Skills Locations

Personal Skills (available across all projects):

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):

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

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

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

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

Scenario 1: How to...
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/

Resources

 
---
 
### 🎨 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:

Be Specific:

Progressive Disclosure Writing

Keep Level 1 Brief (Overview):

Level 2 for Common Paths (Quick Start):

## Quick Start
```bash
# Most common use case (80% of users)
generate-component MyComponent

 
**Level 3 for Details** (Step-by-Step):
```markdown
## 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:
```bash
./scripts/setup.sh

Validation

Validate your configuration:

 
#### Resources Directory
 
**Purpose**: Templates, examples, schemas, static files
**Location**: `resources/` in skill directory
**Usage**: Referenced or copied by scripts
 
Example:
```bash
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:
```bash
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
```markdown
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`:
```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)
 
```markdown
---
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
```bash
# 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)
 
```markdown
---
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
```bash
./scripts/setup.sh
./scripts/generate.sh my-project

Configuration

Edit config.json:

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)
 
```markdown
---
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
```bash
./scripts/install.sh

First Use

Expected output:

Configuration

Basic Configuration

Edit config.json:

Advanced Configuration

See Configuration Guide

Step-by-Step Guide

1. Initial Setup

[Detailed steps]

2. Core Workflow

[Main procedures]

3. Integration

[Integration steps]

Advanced Features

Feature 1: Custom Templates

Feature 2: Batch Processing

Feature 3: CI/CD Integration

See CI/CD Guide

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:

Issue: Validation Errors

Symptoms: Validation script fails Solution: See Troubleshooting Guide

API Reference

Complete API documentation: API_REFERENCE.md

Resources

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

 
---
 
## Examples from the Wild
 
### Example 1: Simple Documentation Skill
 
```markdown
---
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
```bash
# 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
 
```markdown
---
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
```bash
./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

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](https://docs.claude.com/en/docs/agents-and-tools/agent-skills)
- [GitHub Skills Repository](https://github.com/anthropics/skills)
- [Claude Code Documentation](https://docs.claude.com/en/docs/claude-code)
 
### Community
- [Skills Marketplace](https://github.com/anthropics/skills) - Browse community skills
- [Anthropic Discord](https://discord.gg/anthropic) - 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

Skill Builder

What This Skill Does

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

Complete Specification

📋 YAML Frontmatter (REQUIRED)

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

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

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

📂 Directory Structure

Minimal Skill (Required)

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

Full-Featured Skill (Recommended)

Skills Locations

Personal Skills (available across all projects):

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):

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

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

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

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

Scenario 1: How to...
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/

Resources

 
---
 
### 🎨 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:

Be Specific:

Progressive Disclosure Writing

Keep Level 1 Brief (Overview):

Level 2 for Common Paths (Quick Start):

## Quick Start
```bash
# Most common use case (80% of users)
generate-component MyComponent

 
**Level 3 for Details** (Step-by-Step):
```markdown
## 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:
```bash
./scripts/setup.sh

Validation

Validate your configuration:

 
#### Resources Directory
 
**Purpose**: Templates, examples, schemas, static files
**Location**: `resources/` in skill directory
**Usage**: Referenced or copied by scripts
 
Example:
```bash
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:
```bash
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
```markdown
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`:
```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)
 
```markdown
---
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
```bash
# 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)
 
```markdown
---
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
```bash
./scripts/setup.sh
./scripts/generate.sh my-project

Configuration

Edit config.json:

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)
 
```markdown
---
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
```bash
./scripts/install.sh

First Use

Expected output:

Configuration

Basic Configuration

Edit config.json:

Advanced Configuration

See Configuration Guide

Step-by-Step Guide

1. Initial Setup

[Detailed steps]

2. Core Workflow

[Main procedures]

3. Integration

[Integration steps]

Advanced Features

Feature 1: Custom Templates

Feature 2: Batch Processing

Feature 3: CI/CD Integration

See CI/CD Guide

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:

Issue: Validation Errors

Symptoms: Validation script fails Solution: See Troubleshooting Guide

API Reference

Complete API documentation: API_REFERENCE.md

Resources

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

 
---
 
## Examples from the Wild
 
### Example 1: Simple Documentation Skill
 
```markdown
---
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
```bash
# 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
 
```markdown
---
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
```bash
./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

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](https://docs.claude.com/en/docs/agents-and-tools/agent-skills)
- [GitHub Skills Repository](https://github.com/anthropics/skills)
- [Claude Code Documentation](https://docs.claude.com/en/docs/claude-code)
 
### Community
- [Skills Marketplace](https://github.com/anthropics/skills) - Browse community skills
- [Anthropic Discord](https://discord.gg/anthropic) - 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

skill-builder

Documentation

Documentation

Skill Builder

What This Skill Does

Prerequisites

Quick Start

Creating Your First Skill

Complete Specification

📋 YAML Frontmatter (REQUIRED)

Field Requirements

YAML Formatting Rules

📂 Directory Structure

Minimal Skill (Required)

Full-Featured Skill (Recommended)

Skills Locations

🎯 Progressive Disclosure Architecture

Level 1: Metadata (Name + Description)

Level 2: SKILL.md Body

Level 3+: Referenced Files

📝 SKILL.md Content Structure

Recommended 4-Level Structure

Common Scenarios

Level 3: Detailed Instructions (For Deep Work)

Step-by-Step Guide

Step 1: Initial Setup

Step 2: Configuration

Step 3: Execution

Advanced Options

Option 1: Custom Configuration

Option 2: Integration

Level 4: Reference (Rarely Needed)

Troubleshooting

Issue: Common Problem

Issue: Another Problem

Complete API Reference

Examples

Related Skills

Resources

Progressive Disclosure Writing

🛠️ Adding Scripts and Resources

Scripts Directory

Validation

Examples

Relative File Paths

Inline File Content

Step-by-Step Guide

Step 1: Setup

Step 2: Usage

Step 3: Verify

Troubleshooting

Configuration

Step-by-Step Guide

Basic Usage

Advanced Usage

Available Scripts

Resources

Troubleshooting

First Use

Configuration

Basic Configuration

Advanced Configuration

Step-by-Step Guide

1. Initial Setup

2. Core Workflow

3. Integration

Advanced Features

Feature 1: Custom Templates

Feature 2: Batch Processing

Feature 3: CI/CD Integration

Scripts Reference

Resources

Templates

Examples

Schemas

Troubleshooting

Issue: Installation Failed

Issue: Validation Errors

API Reference

Related Skills