Skills

Agent skills and instruction files: what they change, and what they do not.

Findings

29 findings, each linking to its write-up and limits

  • GVP-1A two-sentence structured prompt recovered as many developer-only rules as the grilling skill35 of 75 (prompt) against 34 of 75 (grilling); 0 of 75 from the ticket alone
  • GVP-2Grilling did not pull ahead on nested tickets, because the first rule in each chain was rarely found3 of 30 (grilling) against 5 of 30 (prompt) and 0 of 30 (three questions)
  • GVP-3Capping the interview at three questions did well on simple tickets and fell behind with more unknowns19 of 25 on the few-unknown tickets (grilling 21), 6 of 20 on the many-unknown ticket (grilling 10), 0 of 30 on the nested tickets
  • GRL-1Grilling recovered every requirement that only the developer knew; working from the ticket recovered none5 of 5 rules in each of 3 runs (15 of 15 checks) against 0 of 15
  • GRL-2The gain came from the developer's corrections: grilling with "yes" to everything did no better than the ticket alone15 of 15 checks (answered) against 0 of 15 ("yes" to everything)
  • GRL-3Telling the agent "ask me anything you need to know first" produced no questions at all0 of 18
  • GRL-4Grill-with-docs's glossary and decision records made no measurable difference to a later ticket; they helped only when the rule was captured correctly and the next agent found it17 of 27 against 15 of 27
  • SEC-1With no safeguards, the agent shipped endpoints that worked but weren't secure in 14 of 80 runs, 9 of them with a real access hole18%
  • SEC-2A security skill, opened in every run, made no measurable difference−5 ptsNo measurable difference
  • SEC-3In an exploratory analysis after two faults in my test materials were fixed, a gate of public security tests beat the skill+11 ptsInterval excludes zero
  • SEC-4In 38 of 40 runs, across all four setups, an approver could approve or reject their own closure request38 of 40
  • SEC-5In 69 of 71 failed runs, the agent's closing line said its own checks had passed69 of 71
  • TSK-1A one-paragraph instruction to write a focused API test got the agent to write one that fails without its change and passes with it in 56 of 60 runs; given only the task, it wrote none56/60 vs 0/60
  • TSK-2Adding the repository's verification skill to the instruction did not help: 52 of 60 runs wrote a relevant test with the original skill and 54 with a revised one that puts the focused test first, against 56 with the instruction alone56, 52, 54 of 60
  • TSK-3A stop hook that checked for a relevant test when the agent tried to finish, and sent it back once if there was none, worked as well as the instruction: it blocked every run, and 58 of 60 then had a relevant test58/60
  • TSK-4Real tests of the change did not measurably raise the pass rate: 41 to 47 of 60 in the arms that wrote them, against 40 with no guidance; medium reasoning effort, with no tests, passed 49+15 ptsInterval excludes zero
  • ESK-1Reading is not doing: told to follow the verification skill, the agent read it in every run, but a test of its change was detected in only 15 of 60 runs (prompt) and 10 of 60 (AGENTS.md); most runs ran the skill's smoke-test example instead15/60 and 10/60
  • ESK-2Telling the agent to use its skills did not measurably raise the pass rate: 42 of 60 runs passed when told in the prompt and 43 when told in AGENTS.md, against 37 with no guidance and 39 with the guidance left to discover+8 to +10 pts, not significantNo measurable difference
  • ESK-3A one-line entry in AGENTS.md got the verification skill read as reliably as an instruction in the prompt; the pass rates were similar (43 and 42 of 60), and the experiment cannot tell whether placement matters60/60, 60/60, 3/60
  • ESK-4Being told cost about twice as much per correct change as no guidance: 1.98 times when told in the prompt and 1.77 times in AGENTS.md1.98×Interval excludes 1×
  • RSK-1Repository guidance left for the agent to discover did not measurably raise the pass rate: 40 of 60 runs passed, against 38 of 60 without it (p = 0.40)40 vs 38 of 60 · not measurableNo measurable difference
  • RSK-2The agent read the skills on building and on changing code in every run, but opened the skill on checking a change through the API in only 8 of 60, and a test of its own change was detected in 28/60
  • RSK-3Cost 1.29 times as much per correct change (1.01 to 1.55), against about 2.4 to 2.5 times for the Superpowers pack in earlier experiments1.29×Interval excludes 1×
  • VVS-1Medium reasoning effort, with no skills and no instruction, passed 49 of 60 runs against 36 of 60 at low effort: better on 9 tasks and worse on 1 (Holm p = 0.041)+21.7 ptsInterval excludes zero
  • VVS-2An instruction to check the change against the running application did not measurably raise the pass rate (39 of 60 against 36, Holm p = 0.67); the agent tried to start the app in 47 runs, but it got the app to answer in only 3+5.0 ptsInterval includes zero
  • VVS-3Superpowers again passed about as often as no skills (37 of 60 against 36) and cost the most per correct change: 7.0 cents, against 4.0 at medium effort and 2.8 with no skills at low effort7.0¢
  • SKT-1Neither skill pack reliably raised the pass rate: Superpowers passed 24 of 32 runs, the same as with no skills, and Pocock passed 27 of 32, a gap small enough to be chance (Holm p = 0.38)+9.4 ptsInterval includes zero
  • SKT-2Superpowers used about three times the tokens of no skills on the same task; it wrote tests in 23 of 32 runs, where the agent with no skills wrote none3.07×Interval excludes 1×
  • SKT-3In 28 of the 30 failed runs, the agent said its change worked; this held in every arm28/30

Experiments

8 experiments

Developer-only rules met, higher is better. Few flat unknowns, of 25: ticket only 0, grilling 21, structured prompt 21, three questions 19. Many flat unknowns, of 20: 0, 10, 9, 6. Nested unknowns, of 30: 0, 3, 5, 0.

Controlled trial · GVP

Grilling or a good prompt? Does the skill beat a two-sentence instruction?

Does Matt Pocock's grilling skill recover more of the rules only the developer knows than a short prompt that makes the agent list its open decisions and wait, or than an interview capped at three questions? Does grilling's branch-by-branch walk win where one answer opens new questions, and what does each cost the developer?

A follow-up to GRL. A two-sentence prompt asking the agent to list its open decisions with recommended answers, then wait, recovered as many of the rules only the developer knew as Matt Pocock's grilling skill (35 against 34 of 75), with about half the reading. Neither found rules the agent had no reason to suspect, and on tickets where one answer opens new questions, the first question was rarely asked. The developer was Claude following a fixed brief, not a real person.

Left-out requirements met on the Some and Lots tickets, higher is better. Only in the developer's head, of 15: grilling 15, grill-with-docs 9, ticket only 0, ask me anything 0, yes to everything 0. Findable in the repo, of 18: 17 or 18 in every arm.

Controlled trial · GRL

Grill me first? Does letting the agent interview you get you what you wanted?

When a coding agent interviews the developer before building (Matt Pocock's grilling skill), does it build more of what the developer actually wanted than working from the ticket, and is that from the skill, from being allowed to ask, or from the developer's answers? Do grill-with-docs's glossary and decision records help a later ticket?

Matt Pocock's grilling skill makes a coding agent interview the developer before it builds. On tickets that left out business rules, grilling recovered all five rules only the developer knew, in each of three runs; working from the ticket, a plain "ask me anything" and a developer who said yes to everything recovered none. Grill-with-docs's glossary and decision records made no measurable difference to the next ticket. The developer was Claude following a fixed brief, not a real person.

Proportion, 95% interval

Controlled trial · SEC

The endpoint worked. Was it secure?

When a coding agent adds endpoints to a Spring Boot API from ordinary tickets, how often are they working but insecure, and does a security skill, a security gate of public tests, or both make secure endpoints more likely?

A hosted coding agent added 320 endpoints to a multi-tenant Spring Boot API from ordinary tickets. The agent handled framework-level security well but repeatedly missed one business rule: in 38 of 40 closure-approval runs, an approver could approve their own request. A security skill changed nothing measurable. A gate of public tests improved the behaviours it named, but not that failure, and its edge over the skill rests on a corrected, exploratory result.

Difference in percentage points, 95% interval

Controlled trial · TSK

Telling the agent to test, with and without a skill

When the agent is told to write a focused API test of its change, does giving it the repository's verification skill help it write one that really checks the change, does the skill's design matter, and does a gate that checks for such a test work better than telling it?

One paragraph asking for a focused API test got the agent to write a real test of its change in 56 of 60 runs. Adding the repository's verification skill added nothing. A hook that sent the agent back once did as well. None of it made the changes measurably more correct.

Difference in percentage points, 95% interval

Controlled trial · ESK

Telling the agent to use its skills

With the same repository guidance in place, does telling the agent to use its skills, in the prompt or in AGENTS.md, raise the share of changes that pass independent acceptance tests?

Told to use the repository's skills, the agent read the verification skill every time, but mostly ran a smoke test instead of testing its change. Reading an instruction is not the same as carrying it out.

Difference in percentage points, 95% interval

Controlled trial · RSK

Repository skills

Does guidance written for one repository (an AGENTS.md and skills on how to build, test, verify and change it) raise the share of changes that pass independent acceptance tests, when the agent is left to discover it?

Guidance written for this repository, left for the agent to find, did not measurably make its changes more often correct; the agent rarely opened the part on checking its work.

Difference in percentage points, 95% interval

Controlled trial · VVS

Verification, skills or effort?

On tasks where the obvious change compiles but is wrong when the app runs, which gives more correct changes per dollar: a short instruction to verify, the Superpowers skill pack, or more reasoning effort?

Letting the agent think a little longer made its changes more often correct; an instruction to verify and a skill pack did not.

Difference in percentage points, 95% interval

Controlled trial · SKT

Skill packs across 16 tasks

On a varied set of real change tasks, do Superpowers or Matt Pocock's skills raise the share of changes that pass independent acceptance tests, and at what cost in tokens?

Two popular skill packs for coding agents did not reliably make the agent's changes more correct; one cost about three times as much.

Other topics: Measurement, Context, Verification, Safety and cost, Review, Briefs, Parallel, Harness