SKILL.md

$27

2. Create SKILL.md with proper format

cat > ~/.claude$skills$my-first-skill/SKILL.md

📂 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

- **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](https://github.com/ruvnet/ruflo/blob/HEAD/.agents/skills/skill-builder/docs/API_REFERENCE.md)

### Examples

See [examples/](https://github.com/ruvnet/ruflo/blob/HEAD/.agents/skills/skill-builder/resources$examples/)

### Related Skills

- [Related Skill 1](#)

- [Related Skill 2](#)

### Resources

- [External Link 1](https://github.com/ruvnet/ruflo/blob/HEAD/.agents/skills/skill-builder/https:/$example.com)

- [Documentation](https://github.com/ruvnet/ruflo/blob/HEAD/.agents/skills/skill-builder/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/ruvnet/ruflo/blob/HEAD/.agents/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/ruvnet/ruflo/blob/HEAD/.agents/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/ruvnet/ruflo/blob/HEAD/.agents/skills/skill-builder/docs/TROUBLESHOOTING.md)

## API Reference

Complete API documentation: [API_REFERENCE.md](https://github.com/ruvnet/ruflo/blob/HEAD/.agents/skills/skill-builder/docs/API_REFERENCE.md)

## Related Skills

- [Related Skill 1](https://github.com/ruvnet/ruflo/blob/HEAD/.agents/skills/skill-builder/..$related-skill-1/)

- [Related Skill 2](https://github.com/ruvnet/ruflo/blob/HEAD/.agents/skills/skill-builder/..$related-skill-2/)

## Resources

- [Official Documentation](https://github.com/ruvnet/ruflo/blob/HEAD/.agents/skills/skill-builder/https:/$example.com$docs)

- [GitHub Repository](https://github.com/ruvnet/ruflo/blob/HEAD/.agents/skills/skill-builder/https:/$github.com$example$repo)

- [Community Forum](https://github.com/ruvnet/ruflo/blob/HEAD/.agents/skills/skill-builder/https:/$forum.example.com)

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

---

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