Narrow skills for coding agents beat broad ones

Give each coding-agent skill one job and you can review it. A skill for coding agents is a small, named instruction file that tells an agent what to do, where it may touch, and how to prove it finished. The moment one skill tries to do five things, its summary stays tidy while its diff quietly grows, and nobody can tell what actually happened. Narrow wins because narrow is checkable.

This holds across tools. Cursor, Anysphere's AI code editor, scopes skills in .mdc files. Claude Code and Codex CLI read their own instruction files. The shape is the same everywhere: the smaller the job, the easier the receipt.

Write a skill with exactly one job

Start the skill file with one sentence that names the job, then a scope, then the command that proves it. If you cannot fit the job in a line, you have two skills pretending to be one.

Here is the whole contract for a narrow skill, the kind a reviewer can hold in one read:

---
description: Update changelog entries (adapt globs to your repo)
globs:
  - 'CHANGELOG.md'
alwaysApply: false
---

Job: append one entry per merged PR to CHANGELOG.md.
Allowed paths: CHANGELOG.md only.
Forbidden paths: src/**, tests/**, package.json.
Verify: pnpm run changelog:lint

A skill this small produces a diff a reviewer can map line for line to the scope. A skill that "handles releases" produces a diff that wanders into source, config, and CI, and the summary papers over all of it. The public examples agree with this: skills in the OpenAI Skills repository are markdown files with one declared job each, and that constraint is the point.

Keep scope honest as the skill runs

A summary that reads well and omits its own diff is worse than no summary. So make the agent carry its boundaries in writing, not in memory.

In Cursor, that means keeping the allowed and forbidden paths explicit in the .mdc file and refusing undeclared MCP domains. One job keeps the allowed-paths line short enough to actually check against the diff. When a do-everything skill blurs that line, reviewers end up arguing after the fact about what was ever permitted.

In Claude Code, permissions are where broad skills bite. Broad skills ask for broad approvals, and bash approvals turn into muscle memory. The Claude Code getting started guide wires up hooks, but which hook wins is your decision: state hook precedence and human-eyes folders at the top of CLAUDE.md. A narrow skill needs fewer permissions, so that clause stays short and enforceable.

In Codex CLI, OpenAI's coding agent, scripted runs are easy to write and easy to merge green without proof. The Codex quickstart makes the scripting trivial, which means the receipt has to carry the weight. Have AGENTS.md mandate an intent line, then the command transcript, then a diff summary before any PR. One job per skill keeps that readable in a single sitting.

Check the four things before you merge

A skill run is reviewable when these four questions have file-backed answers, not vibes.

Hand the reviewer a short list, not a long story:

• Scopes in the PR body match the folders in the diff.
• Primary-doc links were smoke-checked after publishing edits.
• Any MCP connectors mentioned list their owners.
• The verification command's output is pasted or linked.

Some decisions never go on autopilot, however narrow the skill: threat models, customer promises, and anything with real blast radius stay with a human. The OWASP Top 10 for LLM applications is a fair map of what leaks through when that line blurs.

Common questions

• How should skills for coding agents be scoped? One job, stated in the first line of the skill file. One scope, written as allowed and forbidden paths. One verification command that proves the job finished. A skill earns reuse when a reviewer can hold the whole contract in a single read, which is only possible when the job is genuinely small.

• Why do broad agent skills fail review? Their receipts cannot stay honest. A skill with many jobs produces diffs that wander across scopes and summaries that compress away the detail reviewers need. Permission requests stop mapping to any clear purpose. The drift hides until review fails, and by then it is everywhere at once.

• What proves a skill run finished correctly? The transcript, not the summary. You want an intent line, the command transcript, and a diff summary, plus the output of the pinned verification command. If the skill delegated work, the child receipts should list every path touched and every test run. A confident summary proves nothing a reviewer can replay.

• Should I split a broad skill I already rely on? Yes, when its summaries are shrinking while its diffs grow. Split it into two narrow skills, each with its own job line, scope, and verification command, then run the old broad skill and the new pair on the same task. The version a stranger could audit is the one to keep.

Start with your broadest skill

Take the one skill that does the most and split it into two narrow ones today, each with its own job, scope, and verification command. Our training walks teams through shipping their first three narrow skills in a day, receipts included.