Skills hold knowledge and commands hold intent. Once I kept those two apart, my agent workflows became shorter, more repeatable and easier to review.
Disclosure: I'm the founder of AgentKrew, a kit for coding agents that I use as the example throughout. The ideas work without it, and I'll say where they stop working.
The trouble with one big prompt
A common starting point is one long prompt pasted at the start of every session: the conventions, the reminders, the list of things not to touch. It works for a while. Then it grows until nobody reads it, and the results shift with how it was phrased that day.
The fix is to stop treating instructions as one thing. Some of it is knowledge, such as how migrations are done here. Some of it is intent, such as "plan this feature." Mixing both in one prompt is what makes it fragile.
Skills: knowledge the agent pulls in
A skill is a reusable set of instructions for one job, such as how migrations are done, how auth is handled or how tests are written. The agent loads it when the task calls for it. The point is that you write the convention once instead of re-explaining it every session.
Rules I follow when writing one:
One job per skill. If you can't name the job in a few words, split it.
Reference, not orders. A skill says what the agent should know. What to do right now belongs elsewhere.
Project facts live here. Billing rules, naming conventions and the files never to touch all belong in a skill.
Short enough to review. When something goes wrong, you should be able to read the skill in a minute and find the cause.
Commands: one-word entry points
A command is the short thing you type to start a repeatable step: plan, review, test. It carries intent and points at the knowledge needed to carry it out.
Name the action, not the topic. "plan", "review" and "test" are commands. "migration notes" is a skill.
Keep commands thin. If a command is full of knowledge, move that knowledge into a skill and let the command call it.
One step each. If you can't describe what it does in a sentence, it is two commands.
A useful test: skills answer "what should the agent know?" and commands answer "what should it do now?"
Agents and workflows tie it together
Skills and commands still need someone to run them, and an order to run them in.
Agents are named specialists defined by role: tech lead, builder, reviewer, security auditor. Each has a routing description so the right one picks up the right work. A reviewer's job doesn't change when the tool running it does.
Workflows are fixed sequences, not improvisation. The tech lead plans, specialists build in parallel, and then a reviewer, a security auditor and a shipper act as gates before anything goes out.
Because the sequence is fixed, two runs of the same workflow follow the same steps. That predictability is the point: you review a plan and a gated result, not a stream of improvised decisions.
One source of truth for every tool
If you use more than one coding agent, instruction files drift. Two files that start identical slowly come to disagree. The cheapest fix is to keep AGENTS.md as the source and have CLAUDE.md point to it, so there is one place to edit.
AgentKrew takes the same idea further. The same kit renders to Claude Code, Codex and OpenCode, so the roles and workflows you define don't depend on which tool runs them.
End every workflow with a release gate
The last step of a workflow shouldn't be "looks good." It should be a check that runs the type check, the tests, lint and the build, and returns one of two answers: ready or blocked.
The gate works no matter which tool wrote the code, because it only looks at the result. It also gives the human a clear moment to step in. A blocked result tells you what failed before anything ships, instead of a green-looking diff that hides a problem.
A quick way to decide which piece you need
Each piece answers a different question. If you can't say which question an instruction answers, split it.
| Piece | Question it answers | Example |
|---|---|---|
| Skill | What should the agent know? | How migrations are done here |
| Command | What should it do now? | Plan, review, test |
| Agent | Who does it? | Reviewer, security auditor |
| Workflow | In what order? | Plan, parallel build, gate |
Limits, and where AgentKrew fits
Agents don't learn between sessions. A human teammate remembers the billing module after six months, while an agent starts fresh every time. Putting context in skills and files is a workaround, and you still maintain those files. Treat them like code and review changes to them.
A separate reviewer helps, but it doesn't replace tests you can trust. Whatever tool you use, check who writes the tests: if one pass writes the code and its own assertions, a green run proves very little.
AgentKrew is my attempt to package this structure: agents, skills, commands and workflows as one versioned, validated kit that renders to Claude Code, Codex and OpenCode, with updates that don't touch your own files. If you want to look at it, it's at agentkrew.com. I'd like to hear what's missing.
Top comments (1)
The "what should the agent know?" vs "what should it do now?" test is the cleanest version of this idea I've seen. One addition from running agents in production: version skills separately from commands — knowledge changes far more often than intent, and keeping them in one file means every billing-rule tweak regenerates a new command contract too. And yes to the release gate being result-checked only; a workflow that trusts its own steps instead of the output is the one that ships bugs fastest.