skill-creator

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

1. Description too vague - Add specific trigger keywords
2. Wrong location - Check path exactly matches conventions
3. Invalid YAML - Validate frontmatter syntax
4. 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