Teach your agent once with agent skills

1. What a skill is

A skill is a folder with a SKILL.md file: a name and a description at the top, instructions below. Scripts, reference docs and templates can sit next to it.

What makes skills useful is how they load:

• At startup, the agent reads only each skill's name and description: about 100 tokens per skill.
• When a task matches, it reads the full SKILL.md.
• Only when the instructions call for them, it opens reference files or runs scripts. A script's output goes into the context, not its code.

So you can have dozens of skills without filling the context window. That's the difference to CLAUDE.md or AGENTS.md, which load in every session. Rules for every task go there; know-how for specific tasks goes into a skill.

Anthropic introduced skills in October 2025 and published them as an open standard that December, at agentskills.io. The same folder works in Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot and dozens of other agents.

2. What the standard looks like

Here's a complete skill that writes commit messages:

writing-commit-messages/
├── SKILL.md
├── scripts/
│   └── check_subject.sh
└── references/
    └── scopes.md

---
name: writing-commit-messages
description: Writes Conventional Commits messages from the staged git diff. Use when the user asks to commit, write or fix a commit message, or describe staged changes.
---

# Writing commit messages

1. Run `git diff --cached`. If nothing is staged, stop
   and say so.
2. Pick one type: feat, fix, docs, refactor, test or chore.
   Read `references/scopes.md` only if the change fits one
   of this repo's scopes.
3. Write `<type>(<scope>): <summary>` in the imperative,
   max 72 characters. In the body, explain why, not which
   files changed.
4. Run `scripts/check_subject.sh "<subject>"`. Fix what it
   reports and run it again until it prints OK.
5. Show the message. Only commit if the user asked for it.

## Gotchas

- A breaking change gets `!` after the type
  (`feat(api)!: ...`) and a `BREAKING CHANGE:` footer.

The frontmatter at the top has two required fields:

• name: lowercase letters, numbers and hyphens, up to 64 characters. It must match the folder name.
• description: up to 1,024 characters. It says what the skill does and when to use it. The agent decides whether to load a skill based on this text alone.

Optional fields are license, compatibility, metadata and the experimental allowed-tools. The body is plain Markdown with no fixed format. Keep it under 500 lines; move longer material into references/ and say when to read it.

3. How to write good skills

A skill is only as good as its description and its checks. Here's what I'd focus on:

• Write the description as a trigger. Say what the skill does and when to use it, in the words people actually type.
• Only write what the agent would get wrong. It already knows how to code. For every line, ask: would it get this wrong without it? If not, cut it.
• Be exact where mistakes are costly. Give exact commands for fragile steps like deploys or migrations, and just a direction where many approaches work. Offer one default, not a menu of options.
• Keep a gotchas list. It's often the most valuable part of a skill. Every time you correct the agent, add the correction there.
• Use scripts for repeatable work. A tested script is more reliable than code the agent writes on the spot, and it costs fewer tokens. Scripts must not wait for input, and they should print clear errors.
• Build in a check. Tell the agent how to verify its work: run the script, fix what it reports, repeat.
• Test the skill. Try a few prompts that should trigger it and a few similar ones that shouldn't. Compare the results with and without the skill.

4. Use skills in Claude Code

Put the skill folder in one of two places:

• .claude/skills/ in your project. Commit it, and your team gets it too.
• ~/.claude/skills/ for skills you want in every project.

Claude loads a skill when its description matches the task. To start one yourself, type its folder name as a command, like /writing-commit-messages. Custom slash commands are skills now, too.

For skills with side effects, like a deploy, add disable-model-invocation: true to the frontmatter. Then only you can start them. Fields like this are Claude Code extras, not part of the standard, so other agents may not understand them.

Shared skills come as plugins. To try Anthropic's examples:

/plugin marketplace add anthropics/skills
/plugin install example-skills@anthropic-agent-skills

5. Use skills in Codex

Codex looks for skills in .agents/skills/, in every folder from where you start it up to the repository root. Personal skills go in ~/.agents/skills/.

Codex picks skills automatically, too. To start one yourself, run /skills or mention it with a dollar sign, like $writing-commit-messages. Two helpers come built in: $skill-creator writes a new skill with you, and $skill-installer installs curated ones.

One skill for both agents

.agents/skills/ is becoming the shared folder: Codex, Cursor, Gemini CLI and GitHub Copilot read it. Claude Code doesn't yet. So keep your skills there and link each one into .claude/skills/:

mkdir -p .claude/skills
ln -s ../../.agents/skills/writing-commit-messages \
  .claude/skills/writing-commit-messages

Now both agents use the same file, and you maintain it in one place.