The open agent-skills format, in one page: required frontmatter, how triggering actually works, the body structure that gets followed, directory conventions per agent, and a pre-publish checklist. Written from shipping and maintaining a 15-skill pack. Last updated: 2026.
A skill is a folder with a SKILL.md file — a markdown instruction unit that an AI coding agent loads when a task matches, giving it a domain workflow instead of a one-off prompt. The format started in Claude Code and is now an open specification (agentskills.io) implemented by Claude Code, Codex CLI, Gemini CLI, Cursor, Windsurf, opencode, Copilot and 70+ other agents.
The economics: a skill is procedural knowledge that installs once and fires forever. It is the closest thing the agent ecosystem has to a package.
--- name: pr-reviewer description: > Use this skill when reviewing a pull request, a branch diff, staged changes, or when the user asks to "review this" before committing or merging. Performs a systematic seven-dimension review instead of a superficial read, and classifies every finding as blocker / should-fix / nit. ---
| Field | Required | Rules |
|---|---|---|
name | yes | lowercase-kebab-case, must match the folder name |
description | yes | The trigger surface. Name the conditions in the user's words, not the architecture (see §3) |
allowed-tools | no | Restrict which tools the skill may invoke |
| license / metadata | no | Per-repo convention |
The agent decides when to load your skill almost entirely from the description field. Not from the body. Not from the folder name. The description is matched against the current task, so:
❌ "A powerful code review assistant that helps developers improve quality." — marketing copy; matches nothing.
✅ "Use when reviewing a pull request, a diff before committing, or when asked to check a change for problems." — mirrors the user's phrasing at the moment of need.
## When to Use — conditions + when NOT to fire
## Workflow — NUMBERED steps (ordered lists are
followed; prose gets summarized)
## Output format — the exact skeleton of the reply
## Anti-patterns — what NOT to do, explicitly
Numbered steps beat prose because agents execute ordered lists in order and summarize paragraphs. Anti-patterns are not decoration — telling the agent what not to do is what suppresses its sycophantic defaults ("looks good to me!").
Per-skill folder layout, discovered up to three levels deep:
skills/<name>/SKILL.md flat layout skills/<category>/<name>/SKILL.md catalog layout
Common install targets per agent: ~/.claude/skills/ (Claude Code), ~/.codex/skills/, .agents/skills/ (shared convention read by Gemini CLI and others), ~/.cursor/skills/, .opencode/skills/. Or skip the matrix entirely:
npx skills add <owner/repo> # picks your agents interactively npx skills add <owner/repo> --agent gemini-cli
1. name matches the folder, kebab-case
2. Description names ≥3 concrete trigger phrases in user language
3. Workflow is a numbered list; every step is an action, not a topic
4. Output format is a literal skeleton the agent can fill
5. Anti-patterns ≥3, each preventing an observed failure mode
6. No skill exceeds what its name promises (scope creep = false triggers)
7. Tested: the skill fires on the intended phrasing, stays silent on neighbors
See the format in working files: seven free, MIT-licensed example skills — review, debugging, testing, specs, commits, releases, AI-code review — each demonstrating every section above.
Get the 7 free skills Full writing guide →