Skill Creator

Create modular Agent Skills that extend Claude's capabilities. Skills package expertise into discoverable folders containing instructions, scripts, and resources.

When to Use

"Create a skill for..."
"Make a new skill"
"Add a skill that..."
"How do I create a skill?"
"Document this workflow as a skill"

Quick Start: Create a Skill

1. Choose Location

# Personal skill (all projects)
mkdir -p ~/.claude/skills/my-skill

# Project skill (shared via git)
mkdir -p .claude/skills/my-skill

2. Create SKILL.md

---
name: my-skill
description: Brief description of what it does and when to use it.
---

# My Skill

## Instructions
Step-by-step guidance for Claude.

## Examples
Concrete usage examples.

3. Test It

Ask Claude a question that matches your description. Skills activate automatically based on context.

SKILL.md Structure

Required: YAML Frontmatter

---
name: lowercase-with-hyphens    # Max 64 chars, [a-z0-9-] only
description: What it does AND when to use it. Include trigger keywords.
---

Critical: The description field determines when Claude discovers and uses your skill.

Optional: Tool Permissions

---
name: safe-reader
description: Read-only file access. Use for code review without modifications.
allowed-tools: Read, Grep, Glob
---

When allowed-tools is set, Claude can only use those tools without asking permission.

Content Sections

# Skill Name

Brief overview.

## Prerequisites
Installation or setup if needed.

## CLI Reference
Commands with examples.

## Common Workflows
Step-by-step procedures.

## Best Practices
Guidelines and tips.

Skill Types

Type	Location	Scope	Shared
Personal	`~/.claude/skills/`	All your projects	No
Project	`.claude/skills/`	This repo	Yes (git)
Plugin	Via installed plugins	Per plugin	Via marketplace

Supporting Files

Add files alongside SKILL.md:

my-skill/
├── SKILL.md           # Required
├── reference.md       # Optional docs
├── examples/          # Optional examples
├── scripts/           # Optional utilities
│   └── helper.ts
└── templates/         # Optional templates

Reference from SKILL.md:

See [reference.md](reference.md) for details.

Run the helper:
` ` `bash
bun scripts/helper.ts
` ` `

Claude reads supporting files only when needed (progressive disclosure).

Writing Good Descriptions

Bad (too vague):

description: Helps with data

Good (specific triggers):

description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when working with Excel files, .xlsx format, or spreadsheet analysis.

Include:

What the skill does
When to use it
Key trigger words users might say

Complete Example

Create `~/.claude/skills/api-testing/SKILL.md`

---
name: api-testing
description: Test REST APIs with curl and analyze responses. Use when testing endpoints, debugging APIs, or validating HTTP requests.
---

# API Testing

Test and debug REST APIs from the command line.

## Prerequisites

` ` `bash
# Verify curl is available
curl --version
` ` `

## CLI Reference

### Basic Requests
` ` `bash
curl -X GET "https://api.example.com/users"
curl -X POST "https://api.example.com/users" \
  -H "Content-Type: application/json" \
  -d '{"name": "John"}'
` ` `

### With Authentication
` ` `bash
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.example.com/protected"
` ` `

### Save Response
` ` `bash
curl -o response.json "https://api.example.com/data"
` ` `

## Common Workflows

### Test Endpoint Health
` ` `bash
# Check status code
curl -s -o /dev/null -w "%{http_code}" https://api.example.com/health

# Measure response time
curl -w "Time: %{time_total}s\n" -o /dev/null -s https://api.example.com
` ` `

## Best Practices

1. **Use -s for scripts** - Silent mode hides progress
2. **Use -f to fail** - Exit non-zero on HTTP errors
3. **Use jq for JSON** - Pipe to `jq` for pretty output

Validation Checklist

Before considering complete:

SKILL.md has valid YAML frontmatter
Name is lowercase-with-hyphens (max 64 chars)
Description includes what AND when (max 1024 chars)
Instructions are clear and actionable
CLI commands have explanatory comments
Tested that Claude discovers and uses the skill

Troubleshooting

Claude doesn't use my skill

Description too vague - Add specific trigger keywords
Wrong location - Check path exactly matches conventions
Invalid YAML - Validate frontmatter syntax
Restart needed - Restart Claude Code after changes

Check skill loads

# Verify file exists
cat ~/.claude/skills/my-skill/SKILL.md

# List all skills
ls ~/.claude/skills/*/SKILL.md
ls .claude/skills/*/SKILL.md

Debug frontmatter

# View first 10 lines
head -n 10 ~/.claude/skills/my-skill/SKILL.md

Ensure:

Opening --- on line 1
Closing --- before content
No tabs (use spaces)
Strings with special chars are quoted

Study Existing Skills

# See all personal skills
ls ~/.claude/skills/*/SKILL.md

# Good examples to study
cat ~/.claude/skills/beads/SKILL.md     # Task tracking CLI
cat ~/.claude/skills/gemini/SKILL.md    # AI research CLI
cat ~/.claude/skills/github/SKILL.md    # gh CLI patterns

skill-creator