name: skill-maker
description: Create, validate, and maintain Claude Code Agent Skills. Use when the user wants to add a skill, create a skill, make a skill, build a skill, or mentions skill creation. Also use when improving SKILL.md files, debugging skill discovery, or asking about skill best practices.
allowed-tools: Read Write Edit Bash Glob Grep

Skill Maker

Create discoverable, focused Agent Skills following the agentskills.io specification.

Core Principles

1. Skills are model-invoked: Claude decides when to use them based on context
2. Descriptions drive discovery: The description field determines when Claude activates the skill
3. Progressive disclosure: Main SKILL.md under 500 lines; detailed content in reference files
4. One capability per skill: Keep skills focused on a single domain

Quick Template

Every SKILL.md must begin with YAML frontmatter:

---
name: skill-name
description: What this skill does and when to use it. Include trigger terms.
---

# Skill Name

Brief introduction...

## Instructions

1. Step by step guidance...

## Examples

Concrete examples...

Frontmatter Specification

Required Fields

Optional Fields

Description Formula

[What it does] + [When to use it] + [Key trigger terms]

Good:

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

Bad:

description: Helps with documents

Creating a Skill

Step 1: Create Directory and File

mkdir -p ~/.claude/skills/skill-name

Personal skills (~/.claude/skills/): Individual workflows, experimental
Project skills (.claude/skills/): Team workflows, shared (committed to git)

Step 2: Write Frontmatter FIRST

Before any content, create lines 1-4:

---
name: skill-name
description: Clear description with what, when, and triggers
---

Step 3: Validate Frontmatter

head -n 10 ~/.claude/skills/skill-name/SKILL.md

Verify:
- Line 1: exactly ---
- Line 2: name: skill-name (matches directory)
- Line 3: description: ... (non-empty, on same line)
- Line 4: exactly ---
- Line 5: blank line

Step 4: Add Content

# Skill Name

Brief intro (1-2 sentences).

## Quick Start

Most common use case with example.

## Instructions

Step-by-step guidance:
1. First action
2. Second action
3. Handle results

## Examples

Concrete, copy-paste ready examples.

Step 5: Add Reference Files (Optional)

For skills with detailed content:

my-skill/
├── SKILL.md           # Under 500 lines
├── references/
│   ├── REFERENCE.md   # Detailed docs
│   └── EXAMPLES.md    # Extended examples
└── scripts/
    └── helper.py      # Utilities

Reference from SKILL.md:

For advanced usage, see [references/REFERENCE.md](references/REFERENCE.md).

Keep references one level deep. Claude loads files only when needed.

Using allowed-tools

Restrict which tools Claude can use (space-delimited):

---
name: safe-file-reader
description: Read files without making changes. Use for read-only file access.
allowed-tools: Read Grep Glob
---

Tool patterns are also supported:

allowed-tools: Bash(git:*) Bash(jq:*) Read Write

If omitted, Claude asks for permission as normal.

Workflow for Claude

When creating a skill:

1. Plan: Determine name, location, focus
2. Create: mkdir -p [path]/skill-name
3. Write frontmatter first: Lines 1-4 with name and description
4. Validate: head -n 10 to verify structure
5. Add content: Instructions, examples below frontmatter
6. Final check: Verify description is discoverable
7. Report: Confirm to user with name, location, description

Skill Locations

When to Create a Skill

Create a skill when:
- You repeat the same workflow multiple times
- You have domain-specific expertise to encode
- Your team needs consistent workflows

Don't create a skill when:
- It's a one-time task
- A slash command would be simpler
- The workflow is too broad (split into multiple skills)

Progressive Disclosure Guidelines

Keep SKILL.md under 500 lines. Move detailed content to references/.

Quick Reference

Create:

mkdir -p ~/.claude/skills/skill-name

Validate:

head -n 10 ~/.claude/skills/skill-name/SKILL.md

List skills:

ls ~/.claude/skills/*/SKILL.md
ls .claude/skills/*/SKILL.md

Debug:

claude --debug

Additional Resources

• Validation checklists
• Example skills
• Common mistakes
• Official spec