Every team that tries to ship real work with AI agents hits the same wall. The agent is brilliant on Tuesday and mediocre on Thursday. It writes clean code on one PR and ships a mess on the next. It catches a security issue in one review and misses an obvious one an hour later.
Prompt engineering helps. But prompts are instructions you paste in once and forget. They do not structure how the agent thinks. They do not carry from task to task. They do not scale to a team of agents working on different problems at once.
What fixed it for me was building a skill framework. Not prompts. Structured behavioral guardrails that agents load contextually based on what phase of work they are in.
The Problem with Prompts Alone
A prompt tells an agent what to do right now. A skill tells the agent how to do something whenever a particular situation comes up. The difference matters more than it sounds.
Say you want agents to always reproduce a bug before fixing it. You can put that in the system prompt. Every agent sees it every time. But prompts get long, context windows fill up, and the agent learns to skim. The instruction sits there but the behavior drifts.
A skill is different. It loads only when relevant. An agent working on a bug fix loads the debugging-and-error-recovery skill. An agent reviewing a PR loads the code-review-and-quality skill. The instructions are fresh, focused, and tied to the task at hand.
The Five Phases
I organize skills around five phases of the development lifecycle. Every task an agent takes on falls into one or more of these phases, and the phase determines which skills load.
Build
Skills that govern how agents write new code: incremental implementation, scope discipline, API and interface design, frontend UI engineering, context engineering. These enforce good engineering habits at the moment of creation. An agent following these skills ships smaller diffs, resists scope creep, and designs interfaces before implementations.
Verify
Skills that govern correctness checks: test-driven development, debugging and error recovery, performance optimization. These run after implementation. An agent following these skills will write a failing test before fixing a bug, diagnose root causes rather than symptoms, and avoid premature optimization.
Review
Skills that govern quality gates: code review and quality, security and hardening, threat modeling, code health and maintainability. These run when an agent is reviewing its own work or another agent's PR. An agent following these skills catches issues that would otherwise slip through.
Ship
Skills that govern delivery: engineering fundamentals checklist, git workflow and versioning, review response, PR lifecycle, shipping and launch. These govern how an agent moves work from "looks done" to "actually merged." An agent following these skills writes clean commit histories, responds to review feedback systematically, and follows PR conventions.
Operate
Skills that govern production and ongoing work: graceful degradation, observability and monitoring, agent operating principles, scope discipline. These apply to work that touches production systems. An agent following these skills instruments its code, designs for partial failure, and knows when to stop and ask instead of pressing on.
Why Five Phases and Not Twenty
The hard part of building a skill framework is deciding how many skills is enough. Too few and the framework is too coarse to change behavior. Too many and agents spend more time loading skills than doing work.
Five phases emerged from observation. Every task an agent does maps cleanly to one of them. The skill count inside each phase varies (some phases have three skills, some have five) but the phase boundaries are stable. When I add a new skill, I know exactly where it goes.
Twenty-one skills is the count today. It will grow. Some skills will get merged as patterns consolidate. The number is not the point. The structure is.
The Most Load-Bearing Skills
If I had to pick the skills that changed agent behavior the most:
scope-discipline. Agents love to expand scope. "While I was in here, I also cleaned up..." becomes a 400-line PR when you asked for a 40-line fix. This skill explicitly forbids that pattern.incremental-implementation. Agents will happily write 500 lines before running a single test. This skill forces them to ship small increments with checkpoints.test-driven-development. Agents tend to write code that "looks right" and call it done. Forcing a failing test first eliminates an entire class of confidence-without-evidence bugs.debugging-and-error-recovery. Without this, agents see an error and try three random fixes. With this, they diagnose before changing anything.agent-operating-principles. Core behavioral rules that apply to everything: surface assumptions, stop when confused, do not be sycophantic, push back when warranted. This one is loaded almost always.
What Did Not Work
A few approaches I tried before landing on the skill framework:
Longer prompts. Cramming more instructions into the system prompt. Agents skim, ignore, or apply them randomly. Past about 2000 tokens the marginal value drops fast.
Example-driven few-shot. Showing the agent three examples of the desired behavior. Helps for pattern-matching tasks. Does not generalize. The agent pattern-matches the surface of the examples, not the underlying rule.
Rigid templates. Forcing the agent to fill in a structured template. Works when the task is structured. Breaks when anything unusual comes up and the template does not fit. Agents try to force the work into the template shape instead of doing the right thing.
Skills worked because they encode a process, not a template or an instruction. The process generalizes across tasks. The agent follows the process and makes its own judgment calls inside it.
The Unexpected Benefit
Skill frameworks give you a handle on agent behavior that prompts never did. If agents start shipping bugs in a new area, I add a skill or update an existing one. The change propagates to every agent immediately. No retraining, no prompt surgery on every team.
The framework also becomes an onboarding document for human engineers. The skills describe how good engineering actually works, written in a form that agents can load but humans can also read. New engineers on the team have started reading them before PR reviews.
The framework codifies the craft. That turns out to be valuable whether the reader is an agent or a person.