Agent skills are procedures the harness can load

Every team has the reviewer everyone waits for: the one who notices the auth middleware moved, asks what happens when the token is missing, and runs the cheap focused check before commenting. That review quality does not scale, because it lives in one person's head and that person has meetings. A skill captures the repeatable part of the procedure and puts it where the agent's harness can load it, and this post walks what belongs inside one, who should execute it, and how you tell whether it works.

I don’t mean human skills in the generic sense. I mean Claude Code skills, Codex-style local skills, Superpowers, Matt Pocock’s skills repo, and the broader pattern showing up across agent tools. Several tools have landed on roughly the same primitive, and when independent systems converge like that, the pattern is usually load-bearing.

In the harness engineering post skills showed up as primitive 09 and got a paragraph. They deserve a full walk, because they look simple from the outside, sometimes literally a markdown file, and the system role they play is bigger than the packaging.

The repeatable part of the review

A skill is a reusable procedure the harness can load when a recurring class of work shows up. Repeatability is the main point: the agent should not have to rediscover what a serious PR review looks like every time someone asks for one.

The packaging varies: a folder with a SKILL.md, scripts, templates, examples, and test cases; a slash command; a runbook wrapped in an agent workflow. I don’t think the packaging is the important part. The job is the same everywhere: when this kind of task appears, give the agent the procedure, the constraints, the tools to prefer, the examples to copy, and the checks that prove the work actually happened.

In practice, skills are one of the ways a team starts moving review habits, release habits, writing habits, and debugging habits out of someone’s head and into the agent setup.

Prompt, instructions, tools

Here’s the running example for the rest of the post. A pull request changes authentication middleware, and the user asks the agent to review it before merge. Without a skill, that sentence is underspecified. What kind of review? Security, test coverage, maintainability, product behavior, regression, style? The strong reviewer brings a whole procedure to that one sentence: read the description, inspect the diff, find the risky files, compare changed behavior to existing tests, run focused checks, decide whether a finding blocks the merge. An agent can do all of that too, but only if the harness hands it the right working procedure.

The simplest fix is a better prompt: please review this PR carefully, look for bugs, missing tests, risky changes, and security issues. The model now has a little more shape around the task and is less likely to just summarize the diff, but the procedure still lives in the user’s head. The prompt doesn’t know how this repo structures auth, which test command is cheap enough to run, or that this team only wants findings backed by a file reference or a command output. If the same task keeps coming back and the procedure matters, prompting starts to feel like copy-pasting a checklist into every conversation.

The next move is instructions. The repo grows an AGENTS.md that says to prioritize correctness, security, test coverage, and regressions, avoid style-only comments, run focused tests when possible. The guidance now lives in the environment instead of being retyped. In the harness map this is primitive 01, and its limits are the ones I described there: instructions are passive. They can say “follow the review convention.” They cannot discover the changed files, choose the right test command, compare the PR against prior auth bugs, or produce a structured review report.

Then tools, primitive 04. The agent can run git diff, execute a test subset, read files, inspect CI, search the issue tracker. Tools let the model act. But the shell doesn’t know when to run pnpm test auth, git diff doesn’t know which files deserve deeper attention, and search doesn’t know which result matters. After all three steps, what’s missing for PR review is the procedure itself.

What the skill writes down

For the PR review example, the skill might say:

Use this skill when asked to review a pull request, inspect a diff,
or check code before merge.

Process:
1. Read the PR description and changed files.
2. Classify the change: auth, data model, UI, infra, tests, docs, or mixed.
3. Identify files where behavior changes before formatting-only files.
4. Search for existing tests around the changed behavior.
5. Run the cheapest focused verification command available.
6. Report only findings that include evidence.
7. Separate blocking issues from follow-up suggestions.
8. If verification cannot run, say exactly why.

That is already different from “review carefully.” The skill writes down the way a serious review should happen. It can include examples of good findings, the team’s preferred output format, scripts for fetching PR data or running the right test subset, and gotchas from prior reviews. The model still has to reason; the harness has just given it a better path through the work.

One procedure, any executor

In the harness map skills sit at primitive 09, right after subagents, and I like that ordering. Subagents let the harness split work into bounded loops: one worker explores the codebase, one verifies sources, one reviews a diff, one tests the UI. Delegation then creates its own problem. If every worker invents its own process, you get parallel inconsistency: one review agent checks tests, another only summarizes, a third comments on style, and one misses the auth boundary because it never searched the route map. Subagents give you more workers, and skills give those workers a shared way to work.

The distinction I use is simple. The skill is the procedure, and a subagent is one possible executor of it. If the problem is that the agent keeps inventing the process, write a skill. If the problem is that the work needs a separate context window, a narrower tool boundary, or parallel execution, use a subagent. For PR review the valuable reusable thing is the review method, and once it exists you can choose who runs it: the main agent directly, a review subagent that returns findings, or a split into security, frontend, and test-coverage specialists whose findings the main agent integrates. A review subagent without a review skill is just a fresh model loop with a vague job.

There’s a second placement question if you saw the memory deep dive, where skills appeared under procedural memory. Both placements are true; the two maps zoom at different levels. The harness map asks what the engineering primitives around the model are; there, skills get their own box because the harness can discover, load, and run them. The memory map asks what state survives to shape future work, and from that view a skill is procedural memory: stored knowledge about how work should happen. “This repo keeps auth middleware in src/server/auth” is a semantic fact. “Here is the review sequence to follow before merge” is procedure.

Loading only what the task needs

A skill folder can have a perfect checklist, scripts, examples, and gotchas, and none of it helps until the runtime puts the right material in front of the model. That’s context management, primitive 03: retrieval, ranking, summarization, compaction, and context assembly. For skills, the context builder has a very practical job. It sees “review this PR before merge,” compares that request against the available skill descriptions, decides the PR review skill matches, and loads the top-level SKILL.md, maybe only the trigger and the process at first. If the skill points at a deeper file like references/auth-review.md, the agent pulls it later, when the diff actually touches auth.

The pattern has a name, progressive loading, and the payoff is that the agent doesn’t need the database migration checklist when the change is a middleware refactor.

The authoring side of this is progressive disclosure, and it’s where skill writing usually goes wrong. It’s tempting to put every review rule into the main file: security rules, frontend rules, migration rules, API compatibility, test strategy, accessibility, performance. The model may technically fit all of it in context, but now a 40-line auth diff is competing with a giant review manual for the model’s attention. The better structure is a top-level skill with the general workflow that points to per-area reference files, scripts, and examples, so the agent opens auth-review.md when the diff touches auth and database-migrations.md when it touches a migration. The skill folder is a structured context source, and the context builder still decides which slice lands on the desk.

The anatomy of a good skill

The basic shape I’d aim for, still using PR review:

Trigger:      review this PR, inspect this diff, check before merge
Non-trigger:  summarize the PR, write release notes, implement the fix
Inputs:       PR URL, branch, local diff, changed files
Process:      read context, inspect diff, classify risk, check tests,
              run focused verification, report findings
Tools:        git diff, file reads, repo search, test runner, CI status,
              browser only when UI changes
Output:       findings first, with severity, file reference, evidence,
              and a suggested fix
Gotchas:      a diff summary is not a review; no style nits unless they
              affect correctness; never claim tests passed without
              running or inspecting them

The trigger and non-trigger matter more than people expect. If the trigger is too vague, the skill never loads. If it’s too broad, the skill shows up in tasks where it doesn’t belong. A PR review skill should not activate when the user only wants a changelog summary, and it should step aside when a narrower browser QA or migration-review skill is the better fit. The useful detail lives in the boundaries, the gotchas, the examples, and the verification.

Anthropic’s Claude Code team makes a similar point in their June 2026 skills write-up: the useful skills are focused artifacts that capture the parts the model tends to miss, the gotchas, the setup, the scripts, the references, and the distribution path. That matches what I see. A skill that only says “review carefully” is adding context without adding judgment.

Most serious agent setups now ship a skill-creator skill or something close to it. Use it, and don’t start by staring at a blank SKILL.md. Describe the workflow in plain language, when it should load, when it should not, what it should verify. Then review the draft the way you’d review code: is the trigger specific enough, does it say when not to load, does it ask for verification receipts, does it include an example of a good finding? Then test it on real PRs, because the skill-creator gets you a first draft, and the real work is finding where that draft overtriggers, undertriggers, or misses the behavior you actually wanted.

Same PR, two runs

Same PR, same model, same tools. Run one has no skill, and the agent reports that the PR refactors auth middleware into a shared helper, the code is cleaner, duplication is down, and maybe add tests for the helper. All of that might be true, and it’s still shallow.

Run two loads the PR review skill and follows the procedure. It reads the diff and sees requireAdmin now delegates to a shared helper. It searches for tests and finds coverage for invalid tokens but no denied-path test for missing tokens. It runs the focused auth command and notices one denied case still returns 200, because the helper treats an empty header differently from a missing one. The finding comes back looking like this:

P1: Missing-token requests can pass the admin guard.

File: src/server/auth/middleware.ts
Evidence: requireAdmin now delegates to parseAuthHeader, which returns
  an empty user object when the Authorization header is missing. The
  test suite covers invalid tokens, but not the missing-header path.
Verification: pnpm test auth -- --runInBand
Fix direction: treat missing Authorization as denied before building
  the user context; add a denied-path test for admin routes.

The skill hasn’t made the model all-knowing; it has made the review path much less accidental.

Evals for procedures

If skills are procedures, they should be tested like procedures. AgentSkills.io gives a practical frame I’d follow as written: create realistic test tasks, run them without the skill for a baseline, run them with the skill, capture outputs, timing, and token cost, write assertions for the objective checks, and use human review for the judgment-heavy parts.

For the PR review skill, an eval set might be five seeded PRs: an auth change missing its denied-path test, a database migration that drops a nullable default, a frontend change with a mobile overflow bug, an API response change that breaks a documented client, and a pure refactor with no behavior change. Some assertions are objective: the review identifies the changed auth boundary, distinguishes blocking findings from suggestions, includes a file reference for each finding, and never claims tests passed without verification evidence. Other parts need a human: was the finding useful, did it miss the real bug, did it bury the blocker under style comments? That’s fine. Evals don’t have to turn everything into pass or fail; they need to make the skill measurably better than a gut feel.

A skill can improve quality and still cost too much, so I’d measure at least five things: bug catch rate against the seeded issues, false positives, evidence quality, token cost, and trigger behavior. That last one is easy to underestimate. A great skill that never triggers is a document sitting on the side, and a broad skill that triggers everywhere becomes noise. The description is part of the system, not marketing copy. It should say when to use the skill and, just as important, when the skill is too broad for the current request.

How skills fail

The failure modes are worth naming, because each one looks reasonable while it’s happening.

Overbroad scope: one engineering skill covers review, testing, planning, debugging, deployment, and incident response, the model sees it everywhere, and it becomes a second system prompt with too many opinions. Undertriggering: the skill is useful but its description says “helps with quality,” the model never connects that to “review this PR,” and the skill sits unused. Stale procedure: the repo moves from Jest to Vitest, the skill still says npm test auth, the team changes the approval rule, and the old procedure keeps moving forward because it sounds official. Context bloat: the skill loads the whole manual every time, so a 40-line diff arrives with 8,000 words of review philosophy. And false confidence: the skill makes the work more repeatable without proving the work succeeded.

False confidence is why skills need to connect to verification, the proof layer from the harness map. When the skill says to check tests, it should ask for receipts: the command, the output, the CI link, or the reason verification wasn’t possible.

Living artifacts, and who owns them

Skills go stale because everything around them moves, so treat them as living artifacts. Anthropic’s write-up makes this observation from their side too: good skills often start small and improve as the model hits edge cases, and they track usage to spot undertriggering and to promote skills that earn real traction. A skill should not start as a 40-page process manual. Start with the recurring failure, add the first gotcha, run it on real work, and when the agent misses something, decide whether that miss belongs in the skill, in a script, in a test, in the repo instructions, or in the product itself.

Models also improve. A step that was necessary six months ago might be noise today: maybe the model now reads TypeScript diffs fine without the long explanation, maybe the old “always run this command” rule is too blunt now that the repo has a faster targeted runner. Maintaining a skill includes pruning it. A skill that only grows eventually becomes another stale context dump.

Then there’s ownership. At first skills feel lightweight: someone writes a markdown file, someone else adds a script, another person copies it into a different repo. Then you have 200 of them. Some excellent, some stale, some overlapping, some overtriggering, some that nobody owns. At that point you need a little operating discipline: a registry, owners, a promotion path from experimental to shared, evals for the important ones, usage signals that separate a skill nobody needs from a skill the model fails to discover, and deprecation, because old procedure has to leave the system at some point. For a PR review skill that might be as simple as: platform engineering owns it, the eval set is the seeded PRs, review cadence is monthly or after a test-runner change, promotion is repo-local first and org-wide after passing evals. It sounds heavy for a markdown file, until that file can influence whether code gets merged.

I run my own skill library for the publishing side of this channel, and it’s small enough that I’m the registry, the owner, and the deprecation process in one person. Teams don’t stay that lucky for long.

When a skill is the right tool

The rule of thumb I use: make a skill when four things are true. The task repeats. The procedure matters. Mistakes are expensive. And the right behavior isn’t obvious from the user’s prompt. PR review qualifies on all four, which is why it carried this post.

By contrast, don’t make a skill for every small preference. If the instruction is one sentence and applies globally, put it in the project instructions. If the agent needs a capability, make or expose a tool. If the work needs separation, create a subagent. If the workflow repeats and the judgment matters, that’s a skill. That routing keeps the harness from turning into a junk drawer.

The questions I’d leave with

Zoom back out and the review request touches almost every layer of the harness: instructions set the general behavior, context delivery brings in the diff and the CI logs, context management decides what’s visible, tools act, the environment bounds them, durable state carries prior lessons, orchestration decides when to stop or ask, subagents split the work, the skill provides the procedure, and the proof layer asks for receipts and feeds the misses back in.

So when an agent keeps failing at a recurring task, whether the model is smart enough is only the first question, and the layer walk from the harness post applies. For skills specifically, the questions get short: is this a one-off or a recurring workflow? If it recurs, does the procedure matter? Can you tell whether the skill beats the baseline? And who owns it when the repo, the model, or the workflow changes?

A skill is procedural memory the harness can load, and it’s how the agent stops rediscovering the same job every time. The standard I hold my own setup to is plain enough: the workflow doesn’t get to live in my head as a vibe. It goes somewhere the harness can find it, test it, and improve it.