Stop Heroic Prompting: Switch to Skills
The real difference between a dev who fights their AI and a dev who gets clean code out of it, in 2026, fits in one line: stop betting on the perfect prompt, write "skills" instead. A skill is a reusable, project-specific instruction file — CLAUDE.md, AGENTS.md, a Cursor rule — that encodes your repo's conventions, tool patterns, and operational expectations. Where "heroic prompting" (the one-shot genius prompt you retype every session) makes you re-pay for the same context over and over, a skill freezes it once and the agent reloads it automatically. Simon Willison and much of the 2026 HN discourse call out this shift as the skill that separates seniors who actually master AI from everyone else. Concretely: you move from "I re-explain my architecture in every conversation" to "my agent already knows my conventions, my test commands, and my traps." The rest of this article shows you what to put in a skills file, a real before/after, and the mistakes to avoid.
What is a "skill," concretely?
A skill is not a prompt. A prompt lives and dies inside one conversation. A skill is a versioned artifact, committed to the repo, that the agent reads automatically at the start of a session or when it touches a given area of the code.
The formats you'll meet today:
CLAUDE.mdat the root (and per subfolder) for Claude Code.AGENTS.md, the format converging across several tools.- Cursor rules (
.cursor/rules), scoped by file glob.
The common thread, highlighted by Simon Willison and echoed across 2026 HN threads: these files encode your project's tacit knowledge. Not general prompting tricks — your repo's conventions. How you name migrations, which command runs the tests, why one module must never import another. The stuff you repeat to every new human teammate, frozen once for the agent.
Why heroic prompting doesn't scale
Heroic prompting is the clever dev's reflex: open a chat, write a thirty-line prompt explaining the context, the architecture, the constraints, and get a stunning result. It works. Once.
The problem is mechanical, not moral:
- You re-pay for context every session. The same paragraph about your architecture, retyped Monday, then Wednesday, then by a teammate who's never seen it.
- It's not reproducible. The genius prompt lives in your head or a browser tab. It isn't shared, versioned, or reviewed.
- It doesn't compose. Two heroic prompts don't add up; two skills do — the agent reads the root file plus the one in the relevant subfolder.
- It drifts. The repo evolves, your mental prompt doesn't. A committed skill updates in a PR, like everything else.
Heroic prompting optimizes one shot. Skills optimize the rate — every session starts from a correct baseline without you re-explaining anything.
| Criterion | Heroic prompting | Skills |
|---|---|---|
| Lifespan | One conversation | Versioned in the repo |
| Sharing | Individual, tacit | Whole team + the agent |
| Reproducibility | Low (depends on your memory) | High (file read every run) |
| Scaling | Linear (you retype) | Amortized (written once) |
| Review / history | None | In PRs, like code |
What to put in a good skills file
A good skill is short, specific, and actionable. Aim for the knowledge the agent cannot infer from the code alone. The sections that pay off most:
- Operational commands: how to build, test, lint, run a single test. The exact command, not "run the tests."
- Repo conventions: naming, folder structure, import style, your custom error handling.
- Architecture boundaries: "the
domainlayer never importsinfra," modules that must not talk to each other. - Tool patterns: which HTTP client, which logger, which date lib — and which ones are banned.
- Known traps: the flaky service, the migration you must run by hand, the field that lies about its name.
- Operational expectations: which branch to commit to, commit message format, what never gets pushed.
Two pro rules. One: be imperative and concrete — "use pnpm test -- <file> for a single test" beats "be careful with tests." Two: include only what's stable and non-inferable. Don't copy your package.json into the skill; the agent can read it. Encode what lives in your head, not what already lives in the repo.
Before / after: a real example
Before — you open a chat and type, for the umpteenth time:
"We're on a pnpm monorepo, the domain layer must never import infra, we test with vitest — for a single file it's
pnpm test -- path. Dates always go throughdate-fns, nevermoment. Don't touchlegacy/, it's frozen."
Ten minutes later, new session: you retype the same block. Your teammate doesn't write it — they don't know it — and the agent hands them code that imports infra from domain.
After — you write this once in CLAUDE.md:
## Build & test
- pnpm monorepo. Single-file test: `pnpm test -- <path>`.
- Runner: vitest. Do not add jest.
## Boundaries
- `domain/` NEVER imports `infra/`.
- `legacy/` is frozen: read-only, no edits.
## Conventions
- Dates: `date-fns` only. `moment` is banned.
From then on, every session — yours, your teammate's, the CI bot's — starts with these rules already in context. You retyped nothing. The day's prompt goes back to being what it should always have been: what you want to do now, not how the project works.
The mistakes that kill a skills file
- The novel. An 800-line skill nobody rereads becomes noise. Short and dense.
- The generic. "Write clean code," "follow best practices": zero value, the agent already knows. Be specific to your repo.
- The stale one. A wrong skill is worse than no skill: it actively derails the agent. Treat it like code, update it in PRs.
- The code duplicate. Copying things the agent can read (dependencies, types) bloats the file for nothing.
- The junk drawer. Everything in one root
CLAUDE.mdwhen a rule only concerns one subfolder. Scope it: one file per area when it makes sense.
Where to start this week
You don't need a big project. Open a CLAUDE.md (or AGENTS.md) at the root and write five lines: the exact test command, one architecture boundary, one known trap. Next time you catch yourself re-explaining something to the agent, don't type it into the chat — paste it into the file. The skill grows by sedimentation, one avoided friction at a time. That quiet habit is what separates, in 2026, the dev who prompts like a hero from the one who vibecodes like a pro.
FAQ
Isn't a skill just a long system prompt? No. A system prompt lives in one session; a skill is a versioned, committed file, reviewed in PRs and reloaded automatically on every run — by you, your team, and CI.
CLAUDE.md, AGENTS.md, Cursor rules: which do I pick?
Whichever your tool reads. Many teams keep the same content in several formats. AGENTS.md is trending toward a cross-tool standard; start with the one your primary agent reads and duplicate if needed.
Does this fully replace prompting? No — it cleans it up. Skills carry how the project works; your day's prompt carries what I want now. You'll always prompt, just shorter and sharper.