Agent Skills and Harness Engineering

[!abstract] In one sentence Agent = Model + Harness. The scaffolding around the model (skills, AGENTS.md, hooks, tools, sandbox, a separate evaluator) matters as much as the model does, and the best scaffolding looks like a good delivery process.

Notes on two posts by Addy Osmani: Agent Harness Engineering (April 2026) and Agent Skills (May 2026).

Harness engineering: the “why”

• The harness is everything that isn’t the model: system prompt, AGENTS.md/CLAUDE.md, skills, tools and MCP servers, filesystem, git and sandbox, subagents and routing, hooks, observability. “If you’re not the model, you’re the harness.”
• The gap is often the harness, not the model. The same model scores very differently in different harnesses. One team moved a coding agent from the top 30 to the top 5 on Terminal Bench by changing only the harness.
• Work backwards from behaviour. Name the behaviour you want, then add the piece that produces it: durable work → git, safe execution → a sandbox, long tasks → planning, verification and context resets. A component without a named job shouldn’t exist.
• The ratchet. Every agent mistake becomes a permanent rule, hook or review check. For example, a merged PR with a skipped test leads to an AGENTS.md rule, a pre-commit grep for .skip(, and a review check. Remove scaffolding when a better model makes it unnecessary.
• Separate the generator from the evaluator. Agents grade their own work too kindly. Agree what “done” means before coding starts.
• Hooks for the non-negotiables: success is silent, failures are verbose. Keep AGENTS.md short, with every line traceable to a real failure: “pilot’s checklist, not style guide.”
• Fight context rot: compaction, offloading big tool outputs to disk, progressive disclosure, and full resets from a hand-off file.
• Failure modes to design for: stopping early, poor decomposition, incoherence across sessions, self-grading, context rot, destructive commands, prompt injection through tool descriptions, and claiming “finished” on broken code.

Agent skills: the “how”

Agents take the shortest path to “done” and skip the senior work that doesn’t show in the diff: specs, tests, scope control and reviewability. A skill is a markdown workflow (steps → checkpoints that produce evidence → an exit criterion), loaded only when relevant and chosen by a small router skill.

Phase	Command	Delivery-process equivalent
Define	/spec	Statement of work, acceptance criteria, Definition of Ready
Plan	/plan	Refinement, vertical slices, INVEST
Build	/build	Implementation in small slices
Verify	/test	Test pyramid, failing test first
Review	/review	~100-line PRs with Critical/Nit/Optional/FYI labels
Ship	/ship	CI/CD, feature flags, Definition of Done

Five principles:

• Process over prose.
• Anti-rationalisation tables, i.e. pre-written rebuttals: “too simple for a spec” → five lines is fine, zero is not; “tests pass, ship it” → passing tests are evidence, not proof.
• Verification is non-negotiable.
• Progressive disclosure.
• Scope discipline: “the single biggest determinant of whether an agent’s PR is mergeable.”

You can adopt these without installing anything:

• Write down your team’s rationalisations and their rebuttals.
• Turn long process documents into short checkpointed workflows.
• Make evidence the exit of every task.
• Add five non-negotiables to AGENTS.md: surface assumptions, stop on conflicting requirements, push back, prefer the boring solution, touch only what’s asked.

My take: agents as a delivery process

1. It’s easier to understand. If the agent works in the same phases as the team, anyone who knows the delivery process can review its output. Nobody needs a new mental model.
2. You catch problems in the right phase. Each phase ends in evidence, so when something goes wrong you can see which phase failed: a bad spec, a bad plan, a weak test or a missed review. Then you fix that phase (the ratchet) instead of blaming “the AI”.
3. It helps developers adopt AI. People trust a process they already run. Mapping skills onto existing ceremonies (ready, refinement, review, done) makes AI an accelerator of the team’s process, not a parallel one. It also helps with a common friction: tickets picked up before they’re ready. An agent that won’t build without acceptance criteria enforces readiness for you.
4. You can learn the backend deeply. The phase outputs (spec, plan, tests, review notes) and the agent’s reasoning are teaching material. A front-end developer can read the plan, ask the agent why it chose a queue or a transaction boundary, and challenge it, so every task becomes a lesson (Growing Frontend Engineers into Backend). The habit to keep is slowing down to understand, not just accepting the output.

Related ideas:

• The ratchet is the agent version of fitness functions.
• Skills are Golden Paths for agents.
• The generator/evaluator split is the idea behind Don’t Read the Code? Verifying AI-Written Code.
• Scope discipline and hooks are the executable-rules layer of A Safe Path for AI Agents in a Large Codebase.