Reasoning scaffolds (cognitive skills vs capability skills)

A reasoning scaffold is prompt material that prescribes how an agent thinks about a problem — a named framework, a persona, a fixed analytical sequence — as opposed to material that grants it something it could not otherwise do. Both ship through the same channel, [[agentskills-spec|SKILL.md]] files loaded on demand, which is why the distinction gets lost. It matters because the two make very different claims and only one of them is cheap to verify.

The two kinds

Capability skills hand the agent knowledge or procedure it lacks: an API’s conventions, a company’s deployment runbook, 817 security techniques (cybersecurity-skills), a domain’s file formats. The test is whether the agent can now do the thing. Progressive disclosure (agentskills-spec) is a token-budget mechanism serving these — measurable, mechanical.
Cognitive skills hand it a way of reasoning it already had access to: first-principles decomposition, a pre-mortem, Bayesian updating, “you are Charlie Munger.” The claim is that framing the reasoning improves the reasoning. Nothing new enters the context except the instruction to think in a shape.

A third kind: output-shape skills (2026-07-28)

i-have-adhd doesn’t fit either box, and neither does ponytail or renwei-writing. These prescribe the shape of the answer — action first, five items max, no preamble; the minimum code that works; the author’s voice preserved — while leaving the reasoning and the capability alone. Call them output-shape skills: they constrain the artifact, not the thinking behind it.

The distinction earns its keep because output shape is inspectable in a way reasoning isn’t. Whether an agent really ran a pre-mortem is unknowable from its response; whether it opened with a command instead of “Great question” is checkable by reading one line. i-have-adhd‘s pre-send check exploits exactly this — delete the announcing first sentence, the “anything else?” closer, the sidebar, the empty hedge, then test whether the first and last lines carry the next action and the current state. That’s a verifiable post-condition on the output, which is the property loop-engineering and this page’s own evidence both point at as the thing that works.

diagram-design (2026-08-06) is the category’s visual case, and it pushes the checkability point one step further: the rules it imposes are geometric (4px grid, 1px hairlines, one accent, a fixed three-font set), and it ships lint tools that check the output against them. Where i-have-adhd‘s pre-send check asks the model to inspect its own answer, a linter inspects the artifact from outside. Cheap to check becomes automatically checked — still saying nothing about whether the form is better, which remains the open half of every output-shape claim.

So the taxonomy is really about what the skill claims and how expensive the claim is to check: capability (can it now do X — mechanical), cognitive (does framing the thinking help — expensive, and so far unproven), output-shape (does the answer have this form — cheap). Note the ordering isn’t a quality ranking. A cheaply checkable form claim says nothing about whether the form is better; i-have-adhd built a whole eval harness precisely because “the output is now shorter” and “the output is now more useful” are different propositions.

Two encodings, one bet

The wiki has both encodings, arriving within a day of each other:

As skills — cc-thinking-skills: 39 frameworks (Munger, Meadows, Kahneman, Goldratt, Boyd) packaged as invocable skills with a router meta-skill in front.
As personas — auto-company: 14 agent definitions role-prompted as named experts, on the stated theory that injecting “Bezos’s Working Backwards, Munger’s Checklists, DHH’s Majestic Monolith” gives decisions “extreme business and engineering depth.”

A persona is a bundle of frameworks addressed by a person’s name; a thinking skill is one framework addressed by its own name. Same bet, different index.

The evidence, so far, is negative

cc-thinking-skills is the only source here that tested it. Length-controlled against a same-length placebo and replication-gated, zero of 39 skills showed a robust replicated accuracy gain; the best candidate (thinking-scientific-method, hypothesis-differential debugging) reached +5.3pp at p=0.061 on its primary run and was recorded as DIRECTIONAL-NOT-REPLICATED.

The honest scope of that result: it says a framework instruction doesn’t beat an equal-length placebo on scoreable accuracy. It says nothing about consistency between runs, about whether the reasoning is easier for a human to audit, or about open-ended work with no scoreable answer — which is most of what agents are pointed at. And the one framework that came closest is the one that prescribes a concrete falsifiable procedure (enumerate hypotheses, rank by likelihood × cheapness-to-check, make the cheapest discriminating observation) rather than a posture. That’s a thin signal, but it points the same way loop-engineering does: what helps is a checkable step, not an attitude.

Where it sits

Reasoning scaffolds are the authoring-time counterpart to loop-engineering‘s runtime structure. A loop improves output by iterating against a feedback signal; a scaffold tries to improve the single pass. When a scaffold has no feedback signal attached, the spoke’s own verification thesis predicts it will be hard to show it did anything — which is roughly what happened.

For self-improving-agents the distinction sets a ceiling: an agent that writes its own skills can genuinely extend its capabilities (new procedures, new knowledge), but an agent writing itself new ways to think is producing scaffolds whose value is currently unmeasured.

cc-thinking-skills · auto-company · agentskills-spec · agent-skills · loop-engineering · self-improving-agents · agent-loops-verification · superpowers · i-have-adhd · ponytail · renwei-writing · diagram-design