Skip to content

Write a skill

Last reviewed October 24, 2026

A good skill is short, specific and boring to read: one job, the steps to do it, and what to do when a step fails. This page covers the format, the two fields that decide whether your skill ever runs, and where to put the folder so your agent finds it.

The smallest valid skill

Make a folder named after the skill and put a SKILL.md in it. The file opens with YAML frontmatter, and only two fields are required: name and description. Everything after the frontmatter is the instructions. Here is a complete one:

writing-release-notes/SKILL.md
---
name: writing-release-notes
description: Drafts release notes from the git history since the last tag. Use when the user asks for release notes, a changelog entry, or a summary of what changed in a release.
license: MIT
metadata:
  author: your-name
  version: "1.0.0"
---

# Writing release notes

1. Find the previous release: `git describe --tags --abbrev=0`. If there is no tag, ask which commit the last release was.
2. List what changed since then: `git log <tag>..HEAD --oneline --no-merges`.
3. Group the changes under Added, Changed and Fixed. Leave out refactors, tests and dependency bumps unless they change behavior.
4. Write one line per change for someone who uses the software, not someone who wrote it.
5. Show the draft and ask before writing it to CHANGELOG.md.

The standard ships a validator. It checks the frontmatter and the folder name against the rules below:

shell
uvx --from "git+https://github.com/agentskills/agentskills#subdirectory=skills-ref" \
  skills-ref validate ./writing-release-notes
Valid skill: writing-release-notes

The rules for each field

  • name: 1 to 64 characters of lower-case letters, digits and hyphens, with no hyphen at either end and never two in a row. It must match the folder's name. Anthropic's products also refuse names containing "anthropic" or "claude" (best practices).
  • description: up to 1,024 characters saying what the skill does and when to use it. More on this below; it is the field that matters.
  • Optional: license, compatibility (system requirements, which most skills do not need), metadata (any string pairs, such as author and version) and allowed-tools, which pre-approves tools and is still experimental. The specification defines these six and no others.

Claude Code accepts more fields of its own, such as when_to_use and disable-model-invocation. Other agents ignore them, and claude.ai rejects a skill that has them, so leave them out of a skill you mean to share.

What the agent reads, and when

The agent loads every skill's name and description at the start, about a hundred tokens each. It reads the body of SKILL.md only when a task matches, and reads files in scripts/, references/ and assets/ only when the instructions send it there. The standard asks for a body under 500 lines and about 5,000 tokens, with anything longer moved to a reference file one level down (progressive disclosure).

The consequence is practical. Rarely needed detail, such as a long API table or the edge cases of a file format, belongs in references/, where it costs nothing until the one task that needs it.

Write the description the agent decides from

The agent picks a skill from its description alone. Say what the skill does, then when to use it, in the words a person would type. Put the main use first: Claude Code shortens descriptions when many skills compete for space (Claude Code skills).

The two main sources disagree on voice. Anthropic asks for the third person ("Drafts release notes"); the standard's own guidance favors an instruction ("Use this skill when") and encourages being pushy about when it applies (optimizing descriptions). The example above does both, one sentence each. Anthropic also suggests naming skills with a verb in -ing form (writing-release-notes), and avoiding names like helper or utils that say nothing.

Write the instructions

Number the steps. Give the exact command where there is one, and say why when a step is not obvious; agents follow reasons better than bare rules. Assume the agent is capable, and cut any line that tells it something it already knows. Anthropic's test is whether each paragraph earns its tokens. Above all, say what to do when a step cannot be done (no tag found, a file missing) and where to stop and ask before changing anything.

Where each agent looks for skills

Personal skills apply in every project; project skills live in the repository and travel with it.

AgentPersonalProject
Claude Code~/.claude/skills/.claude/skills/
Codex~/.agents/skills/.agents/skills/
Gemini CLI~/.gemini/skills/ or ~/.agents/skills/.gemini/skills/ or .agents/skills/
GitHub Copilot~/.copilot/skills/ or ~/.agents/skills/.github/skills/, .claude/skills/ or .agents/skills/
Cursor~/.cursor/skills/ or ~/.agents/skills/.cursor/skills/ or .agents/skills/ (also reads .claude/skills/)
OpenCode~/.config/opencode/skills/.opencode/skills/, .claude/skills/ or .agents/skills/

Antigravity reads .agents/skills/ in a project; its documentation and Google's own tutorials disagree on the personal folder, so check Antigravity's skills page for your version.

Let skill-creator do the scaffolding

In Claude Code, Anthropic's skill-creator drafts a skill from a conversation, writes test cases, and tunes the description against prompts that should and should not trigger it. It is a plugin, not built in:

Claude Code
/plugin marketplace add anthropics/claude-plugins-official
/plugin install skill-creator@claude-plugins-official

The next step uses it to check your skill does what you think.

Building something else? See the guides to a plugin or marketplace and an MCP server.