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

| Field | Constraints | |-------|-------------| | name | Max 64 chars. Lowercase, numbers, hyphens only. No leading/trailing/consecutive hyphens. Must match directory name. | | description | Max 1024 chars. Non-empty. Include what it does, when to use, trigger terms. |

Optional Fields

| Field | Purpose | |-------|---------| | license | License name or reference to bundled file | | compatibility | Max 500 chars. Environment requirements | | metadata | Key-value mapping for additional properties | | allowed-tools | Space-delimited list of pre-approved tools |

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

| Location | Purpose | |----------|---------| | ~/.claude/skills/ | Personal skills | | .claude/skills/ | Project skills (git) |

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

| Level | Token Cost | Content | |-------|------------|---------| | Metadata | ~100 tokens | name and description (loaded at startup) | | Instructions | < 5000 tokens | SKILL.md body (loaded when activated) | | Resources | As needed | Reference files (loaded on demand) |

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