Create new Claude Code Skills with proper YAML frontmatter, progressive disclosure structure, and complete directory organization. Use when you need to build custom skills for specific workflows, generate skill templates, or understand the Claude Skills specification.
npxskills add ruvnet/claude-flow--skill "Skill Builder"Loading…
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).
# 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
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
---
name (REQUIRED):
description (REQUIRED):
---
# ✅ 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.
~/.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!
~/.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
Personal Skills (available across all projects):
~/.claude$skills/
└── [your-skills]/
~/.claude$skills/ or $HOME/.claude$skills/Project Skills (team-shared, version controlled):
<project-root>/.claude$skills/
└── [team-skills]/
.claude$skills/ in project rootClaude Code uses a 3-level progressive disclosure system to scale to 100+ skills without context penalty:
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!)
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]
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.
---
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
# Commands
Expected output:
Success message
# Advanced usage
# Integration steps
Symptoms: What you see Cause: Why it happens Solution: How to fix
# Fix command
Solution: Steps to resolve
See API_REFERENCE.md
See examples/
---
### 🎨 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."
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
```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).
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
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:
```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
See working examples in resources$examples/:
basic-example/ - Simple componentadvanced-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.
Use the template located at `resources$templates$api-template.js`
See examples in `resources$examples$basic-usage/`
## 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
[Instructions]
[Instructions]
[Instructions]
### 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
Edit config.json:
{
"option1": "value1",
"option2": "value2"
}
[Steps for 80% use case]
[Steps for complex scenarios]
scripts$setup.sh - Initial setupscripts$generate.sh - Code generationscripts$validate.sh - Validationresources$templates/resources$examples/[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
.$scripts$quickstart.sh
Expected output:
✓ Setup complete
✓ Configuration validated
→ Ready to use
Edit config.json:
{
"mode": "production",
"features": ["feature1", "feature2"]
}
[Detailed steps]
[Main procedures]
[Integration steps]
.$scripts$generate.sh --template custom
.$scripts$batch.sh --input data.json
See CI/CD Guide
| 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$basic.template - Basic templateresources$templates$advanced.template - Advanced templateresources$examples$basic/ - Simple exampleresources$examples$advanced/ - Complex exampleresources$examples$integration/ - Integration exampleresources$schemas$config.schema.json - Configuration schemaresources$schemas$output.schema.json - Output validationSymptoms: Error during install.sh
Cause: Missing dependencies
Solution:
# Install prerequisites
npm install -g required-package
.$scripts$install.sh --force
Symptoms: Validation script fails Solution: See Troubleshooting Guide
Complete API documentation: API_REFERENCE.md
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
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
.$scripts$generate-component.sh ComponentName
Edit generated files in src$components/ComponentName/
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
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).