Skills and Reusable Instructions for Coding Agents

Your CLAUDE.md started with five lines. Now it has the release steps, the review checklist and how to add a blog post, and the agent reads all of it at the start of every session, even when you just want a typo fixed.

A skill fixes that. Your instruction file loads every session. A skill loads only when it's needed.

Claude Code's skills docs put it plainly: unlike CLAUDE.md, only a skill's description loads at the start, and the full content loads when the skill is used (Claude Code skills docs, read September 26, 2026). Codex and Cursor load skills the same way. So a ten-step release checklist costs almost nothing until someone asks for a release.

Below: what a skill looks like in each tool, a worked skill you can drop into a repo, how to make it work across tools, and how to decide between a skill and a line in the instruction file.

What a skill is

A skill is a folder with a SKILL.md file in it. The file starts with a short header (YAML frontmatter) holding at least a name and a description. Then come the instructions, in plain Markdown. The folder can also hold scripts, templates and reference files the instructions point to.

The format comes from the Agent Skills open standard, which is why the same folder works in more than one tool. Where each tool looks, as of September 2026:

Sources: Claude Code skills, Codex skills, Cursor skills.

All three tools will also start a skill on their own when your request matches its description. That makes the description the most important line in the file. It decides when the skill fires, and it's the only part the agent sees until then.

Slash commands became skills

If you wrote custom slash commands in Claude Code as .claude/commands/deploy.md, they still work. The skills docs call that the older format. A command file and a skill at .claude/skills/deploy/SKILL.md both give you /deploy.

Skills add three things: a folder for supporting files, starting on their own when the description matches, and extra header fields. For anything new, write a skill.

Worked example: a pre-merge check skill

The goal: type /pre-merge (or $pre-merge in Codex). The agent sums up your uncommitted changes, runs the project's checks, and tells you what it couldn't verify. It never commits.

Create .claude/skills/pre-merge/SKILL.md:

---
name: pre-merge
description: Checks the current uncommitted change before it is committed or merged. Summarizes the diff, runs lint and tests, and lists anything unverified. Use when the user asks if a change is ready, wants a pre-merge check, or asks what changed.
disable-model-invocation: true
allowed-tools: Bash(git diff *) Bash(git status *) Bash(npm run lint) Bash(npm test)
---

## Current change

!`git status --short`

!`git diff HEAD --stat`

## Steps

1. Read the full diff with git diff HEAD. Summarize it in two or three bullets.
2. Flag any file that looks outside the task the user described.
3. Run npm run lint, then npm test. Quote the last lines of any failure.
4. Check that every changed source file has a matching test change, or say
   why one isn't needed.
5. Report in this order: summary, check results, scope concerns, anything
   you could not verify. Do not commit, push, or edit files.

What each part does, per the Claude Code docs:

• description says what the skill does and when to use it. Claude reads this to decide whether the skill fits a request.
• disable-model-invocation: true means only you can start it. The docs suggest this for skills that change things, or that you want to run at a moment you choose, like deploy or commit. Leave it out if you want the agent to reach for the skill on its own.
• allowed-tools pre-approves those commands while the skill runs, so you aren't asked about every git diff. The approval ends after your next message.
• The ! lines run before the agent even starts reading. Claude Code runs each command when the skill starts and swaps the line for its output. So the agent begins with the current status and file list already in front of it. If one of these commands fails, the whole skill stops.

Start it with /pre-merge. You can add text after the command, and it lands in $ARGUMENTS inside the skill. So if step 2 mentioned $ARGUMENTS, /pre-merge signup form validation would let the agent compare the diff against "signup form validation".

Making the same skill work in Codex and Cursor

Copy the folder to .agents/skills/pre-merge/ and Codex and Cursor will find it. What carries over is the part the shared standard defines.

The Claude Code docs list the standard fields as name, description, license, compatibility, metadata, and allowed-tools. Fields such as disable-model-invocation, context, arguments, and paths are Claude Code extras. The docs suggest sticking to the standard fields when a skill needs to work elsewhere. Cursor's docs list disable-model-invocation and paths as optional fields of its own, so check each tool's page for the extras it supports.

The ! lines only work in Claude Code. In another tool they're just text. The portable version turns them into ordinary steps:

## Steps

1. Run git status --short and git diff HEAD --stat to see the change.
2. Read the full diff with git diff HEAD. Summarize it in two or three bullets.
...

That costs the agent one extra command and works everywhere.

If your team uses more than one tool, keep the portable skill in .agents/skills/. If you want the Claude Code extras too, add a slim copy with the same name in .claude/skills/. One more detail from the worktrees docs: when a worktree (a second working copy of the repo) has no .claude/skills of its own, Claude Code reads the one in the main copy. So skills you keep out of Git still load there.

Two more Claude Code options worth knowing

Run a skill in a helper agent. Add context: fork and the skill runs in a separate subagent, with the skill's instructions as its whole job. Pair it with agent: Explore for a skill that only reads and researches. All the skill's work stays out of your main conversation, and only the result comes back. The subagents page in this series covers when that separation is worth it.

Control who can start what. Permission rules accept Skill(name), so you can allow Skill(pre-merge) and deny Skill(deploy *). user-invocable: false is the opposite of disable-model-invocation: only Claude can load the skill. That suits background knowledge you'd never call by name.

Codex custom instructions: AGENTS.md

Codex's always-on instructions live in AGENTS.md. The Codex AGENTS.md guide explains how it finds them.

First it reads a global file from ~/.codex. Then it walks from the project root down to the folder you're working in, checking each folder for AGENTS.override.md, then AGENTS.md. It joins what it finds in that order, so a file closer to your working folder comes later and wins any conflict. It stops adding files once the total hits project_doc_max_bytes, which is 32 KiB by default.

That limit is handy. If your AGENTS.md is getting close to it, part of it is probably a procedure that belongs in a skill. The CLAUDE.md and AGENTS.md guide in this series covers how both files load in full.

When a skill beats a line in CLAUDE.md

The Claude Code docs split it into facts and procedures. Facts that never change, like your conventions, go in CLAUDE.md. Step-by-step procedures and big reference documents go in skills. In practice, move something into a skill when any of these is true:

• It has steps. "Run lint, then tests, then check the changelog" is a procedure. The agent needs it only when doing that task.
• It's long. A style guide, an API schema or a voice guide takes up the agent's attention on every turn when it sits in the instruction file. In a skill, it costs nothing until it's needed.
• It runs sometimes, not always. Release steps, a migration recipe, the checklist for a new blog post.
• You want to trigger it by name. A skill gives you /release. A paragraph in CLAUDE.md doesn't.
• It needs tools pre-approved. allowed-tools grants permissions for that one task only.

Keep it in the instruction file when it should shape every change: the package manager, the test command, naming conventions, "never commit to main". A one-line pointer in CLAUDE.md to a skill is fine and often helpful, for example "Before any article edit, load the content-voice skill."

And if a rule must hold no matter what the model decides, neither place is enough. That's a job for a hook.

To turn vague rules into checks the agent can run, see CLAUDE.md and AGENTS.md: what coding agents read.

Previous in the series: MCP servers for coding agents. Next: Headless and CI use of coding agents.