---
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](https://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:

```yaml
---
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**:
```yaml
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**:
```yaml
description: Helps with documents
```

## Creating a Skill

### Step 1: Create Directory and File

```bash
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:

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

### Step 3: Validate Frontmatter

```bash
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

```markdown

# 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:
```markdown
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):

```yaml
---
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:
```yaml
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**:
```bash
mkdir -p ~/.claude/skills/skill-name
```

**Validate**:
```bash
head -n 10 ~/.claude/skills/skill-name/SKILL.md
```

**List skills**:
```bash
ls ~/.claude/skills/*/SKILL.md
ls .claude/skills/*/SKILL.md
```

**Debug**:
```bash
claude --debug
```

## Additional Resources

- [Validation checklists](references/VALIDATION.md)
- [Example skills](references/EXAMPLES.md)
- [Common mistakes](references/MISTAKES.md)
- [Official spec](https://agentskills.io/specification)