Skill Creation Guide

Skill Directory Structure

skill-name/
├── SKILL.md          # Required: frontmatter + instructions
├── scripts/          # Optional: executable code (Python, Bash, JS)
├── references/       # Optional: documentation loaded on demand
└── assets/           # Optional: templates, images, data files for output

SKILL.md Format

Two parts: YAML frontmatter (metadata) + Markdown body (instructions).

---
name: my-skill
description: "What it does and when to use it. Include trigger keywords."
license: MIT
metadata:
  version: "1.0.0"
  author: your-name
---

# My Skill

Step-by-step instructions here...

Frontmatter Fields

Field	Required	Constraints
`name`	Yes	Max 64 chars. Lowercase, numbers, hyphens only. Must match folder name.
`description`	Yes	Max 1024 chars. What it does AND when to use it.
`license`	No	License name or reference to bundled LICENSE file.
`compatibility`	No	Max 500 chars. Environment requirements (tools, packages, network).
`metadata`	No	Key-value pairs (author, version, etc.).
`allowed-tools`	No	Space-delimited pre-approved tools. Experimental.

Name Rules

Lowercase letters, numbers, hyphens only
No leading/trailing/consecutive hyphens
Must match the parent directory name

Description Is the Trigger

The description is the primary mechanism Claude uses to decide when to activate the skill. All "when to use" information must be here — not in the body (which only loads after triggering).

Good:

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

Bad:

description: "Helps with PDFs."

Core Principles

1. Claude Is Already Smart

Only add context Claude doesn't already have. Challenge each line: "Does Claude need this?" and "Does this justify its token cost?" Prefer concise examples over verbose explanations.

2. Progressive Disclosure

Skills load in three stages:

Metadata (~100 tokens) — name + description, always in context for all skills
SKILL.md body (<5,000 tokens recommended) — loaded when the skill triggers
Bundled resources (unlimited) — loaded only when Claude needs them

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

3. Match Freedom to Fragility

Level	When	Example
High freedom (text instructions)	Multiple valid approaches	"Generate a REST API endpoint"
Medium freedom (pseudocode/parameterized)	Preferred pattern exists	"Follow this template but adapt to context"
Low freedom (specific scripts)	Fragile, consistency critical	"Run this exact script with these params"

Bundled Resources

`scripts/` — Executable Code

Use when deterministic reliability is needed or the same code gets rewritten repeatedly. Token efficient — may execute without loading into context.

`references/` — Documentation

Keeps SKILL.md lean. Claude loads these on demand. For files >10k words, include grep patterns in SKILL.md. Structure longer files with a table of contents. Keep references one level deep from SKILL.md.

`assets/` — Output Files

Templates, images, boilerplate code, fonts. Not loaded into context — used directly in output.

What NOT to Include

README.md, INSTALLATION_GUIDE.md, QUICK_REFERENCE.md, CHANGELOG.md
User-facing documentation
Setup/testing procedures
Process documentation about how the skill was created

The skill should only contain information an AI agent needs to do the job.

Creation Process

Clarify scope — Understand what the skill should do with concrete examples
Plan resources — Identify what scripts, references, and assets would help
Create the directory — mkdir -p skill-name/references
Write resources first — Implement scripts/, references/, assets/ files
Write SKILL.md — Frontmatter with strong description, then concise body instructions
Iterate — Use the skill on real tasks, notice struggles, refine

Detailed Reference

See specification.md for the full Agent Skills specification and validation rules.

skill-creation