Skill creation

A skill is a folder that holds a SKILL.md file. The agent loads the name and the description of every skill at startup. It loads the body only when a task matches the description. Write for that order: the description wins the trigger, and the body does the work.

Write a skill only when it pays

A skill costs context only when it triggers. A rule in AGENTS.md costs context in every session.

Workflow

Copy this checklist, and mark each step:

- [ ] 1 Find the gap
- [ ] 2 Name it
- [ ] 3 Write the description
- [ ] 4 Draft the body
- [ ] 5 Split, if the body is long
- [ ] 6 Test in a new session
- [ ] 7 Install it

1 — Find the gap. Do the task once with no skill. Write down what you had to supply: the commands, the flags, the order, the traps. That list is the skill. Do not write a skill for a problem you have not hit.

2 — Name it. Use lowercase letters, digits and single hyphens. Match the folder name exactly. Prefer a gerund (processing-pdfs) or a noun phrase (pdf-processing). Reject helper, utils and tools, because they say nothing. The words anthropic and claude are reserved.

3 — Write the description. This one line decides whether the skill ever runs. Give both parts: what the skill does, and when to use it. Write in the third person. Name the words the user will type, and the file types and commands they will touch. Add a negative clause when a neighbouring tool can steal the trigger.

# good
description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when
  the task mentions PDFs, forms, or document extraction.
# poor — no trigger, wrong person
description: I can help you with documents.

Agents under-trigger, so make the description direct.

4 — Draft the body. Write only what the agent does not already know. Cut every sentence that explains a well-known format, library or concept. Keep the house rules, the exact commands, the output shapes, and the failure modes.

Set the freedom to match the risk:

Give one default, and one escape hatch. Do not list five libraries that all work.

5 — Split, if the body is long. Keep SKILL.md under 500 lines. Move detail into references/<topic>.md, and link it from SKILL.md with a relative path. Keep every reference one level deep, because an agent reads a chain of links only in part. Add a contents list to a reference file longer than 100 lines. Put runnable code in scripts/, and templates in assets/. Say which you want: run scripts/check.py, or read references/api.md.

6 — Test in a new session. The description is a hypothesis. Test it:

• three real requests that must trigger the skill, in the words a user would use;
• one nearby request that must not trigger it;
• the whole procedure, done by an agent that has only the skill.

Watch where the agent stops, guesses, or reads the wrong file. Fix the skill, not the prompt.

7 — Install it. See the table below.

Frontmatter

---
name: my-skill              # required, matches the folder, max 64 characters
description: What it does, and when to use it.   # required, max 1024 characters
license: MIT                # optional
---

These six fields travel everywhere: name, description, license, compatibility, metadata, allowed-tools. Every other field is host-specific, and it can make packaging or upload fail. Use references/frontmatter.md for the full table and the host-specific fields.

Layout

my-skill/
├── SKILL.md            # required: the trigger and the procedure
├── references/         # optional: detail, read on demand
├── scripts/            # optional: code, run and not read
└── assets/             # optional: templates and data

Start with SKILL.md alone. Add a folder when the body gets too long, and not before. assets/SKILL.template.md in this skill holds a skeleton to copy.

Install

Put the folder in .agents/skills/<name>/. Codex, Cursor and OpenCode read that path. Claude Code reads .claude/skills/, so link it:

mkdir -p .claude/skills
ln -s ../../.agents/skills/my-skill .claude/skills/my-skill

Commit project skills. The agent then gets the same procedure as the team.

Review before you share

• The description gives what and when, in the third person.
• The name matches the folder, and holds no reserved word.
• The body is under 500 lines, and every reference is one level deep.
• Nothing in the body is common knowledge.
• One term per idea, used the same way throughout.
• No date-bound advice. Old behaviour goes in an "old patterns" section.
• All paths use forward slashes.
• Steps that can fail carry a check, and a way back.
• Three trigger tests pass, and one near-miss stays quiet.

Common faults

More

• references/frontmatter.md — every frontmatter field, and where each one is valid.
• assets/SKILL.template.md — the skeleton to copy for a new skill.