Skill library versus cognitive unit library

An autonomy roadmap assumes one shelf: "the cognitive unit library." Known multi-step work still lives in worker scripts and agent prompts. Agents search cognitive units but reinvent procedures. Skills get demoed once, never published. Substitution rules apply to judgments while procedures drift unnamed. Platform teams feel productive because libraries exist and dashboards show package counts. Meta-agents still cannot compose invoice extraction or week composition from inventory because the procedure layer was never packaged. Mature autonomy needs two inventories with the same ecosystem but different packaging semantics.

Helpful context: Libraries of cognition defines packages. What is a cognitive unit and what is a skill define what each shelf holds. Do not rediscover known work explains why both shelves matter. This page helps platform owners decide packaging level.

Two shelves, two packaging logics

The confusion is understandable. Both shelves publish packages. Both use semantic versioning, owners, and suites. The difference is granularity and eval focus.

	cognitive unit library	Skill library
Packages	One open judgment	Known capability / procedure
Search answers	Which judgment do I need?	Which procedure should I invoke?
Eval focus	Decision quality on declared terrain	Order, seams, invariants, side effects
Substitution preserves	Judgment contract	Capability contract + procedure evidence
Typical caller	Agent loop, other Skills, application code	Agent, orchestrator, batch job
Meal example	AssessMealPracticality	Compose provisional week capability (when stabilised)
Invoice example	Field interpretation cognitive unit	Extract structured invoice Skill

An agent that searches only cognitive units stretches judgments into compounds or reinvents orchestration in prompts. An agent that searches only Skills hides judgments that still need independent ownership and eval, turning everything into an opaque procedure blob.

When to package at which level

The cognitive unit library is the right home when one open decision owns the consequence, when callers may need the judgment independently of a specific procedure, when evaluation is judgment-shaped (grader on decision quality, applicability guards on terrain), and when substitution swaps implementation behind one decision contract. In the Meal Companion grounding reference, GenerateCandidates, AssessMealPracticality, RecommendMealSubstitution, AskTargetedQuestion, and judge-library entries like JudgeWeekdayPracticality all fit this pattern.

The skill library is the right home when a settled multi-step trajectory repeats across products, when order and seam discipline matter as much as individual judgments, when side effects and authority span multiple steps with one capability name, and when procedure-level regression catches failures no single cognitive unit suite sees. Extract structured invoice (invoice intake) fits here, and compose provisional week would fit once procedure shape stabilises beyond agent-private ComposeWeek tactics.

Work stays agent-private when the trajectory is still experimental. InterpretWeek, ComposeWeek, and CritiquePlan in the Meal Companion may remain with the agent until promotion is deliberate. Agent-private cognitive units and domain libraries covers those placement decisions.

Autonomy consequence

The library unlocks autonomy when searchable evaluated parts exist as inventory. Meta-agents and composing agents select Skills for known work and cognitive units for remaining open judgments. Promoting settled trajectories on purpose, naming them, writing capability contracts, building procedure suites, assigning owners, and publishing, is how procedure-level autonomy becomes possible. Unstable paths stay in agent territory until packaging is earned. When a trajectory becomes a Skill describes that graduation path.

Search catalogs must expose inventory type as a first-class filter, as sealed and searchable develops. Inspect must distinguish capability contracts from judgment contracts, as runtime inspectability explains. Without those distinctions, agents confuse evaluation judges with production assessors, or invoke a multi-step Skill when a single judgment suffices.

Substitution semantics differ

Substitution rules apply to both shelves with different gates. cognitive unit substitution freezes the decision sentence, holes, and abstain/refer branches, with suite re-run on judgment distribution. Skill substitution freezes the capability contract (what the procedure promises end-to-end) and re-runs procedure suite on order, seam, invariant, and side-effect checks. cognitive units inside the Skill may substitute independently when their contracts allow, but Skill substitution does not silently swap internal cognitive units without procedure re-eval.

Confusing the two produces either fake mega-cognitive-cognitive units (multi-judgment prompts with one name) or opaque Skills that hide unmaintainable judgment blobs.

What this looks like in practice

In the Meal Companion, the domain cognitive units library holds meal judgments shared across product lines: GenerateCandidates, AssessMealPracticality, RecommendMealSubstitution. An optional skill library entry for "compose provisional week" appears when procedure shape stabilises beyond agent-private ComposeWeek. The judge library holds evaluation-shaped cognitive units separately.

In invoice intake, field-level cognitive units sit in the cognitive unit library: interpret vendor, match PO line, classify exception. Extract Structured Invoice as a Skill in the skill library composes them for enterprise intake. Agents search Skills for known intake and search cognitive units for remaining field judgments. Invoice intake overview describes this arrangement.

On the organisational shelf, AskTargetedQuestion lives in the organisational cognitive unit library as org policy, not domain meal logic. Skills may invoke it. They do not reimplement it.

Graduation from agent to library

The Meal Companion illustrates a deliberate graduation ladder. ComposeWeek begins agent-private because the Meal Planning Agent owns how candidates become a provisional plan while strategy still shifts. When composition stabilises, showing consistent order, known seams, and repeatable invariants, the platform publishes a Skill with capability contract and procedure suite. Until then, forcing Skill packaging would freeze experimental orchestration.

The same ladder applies to cognitive units inside agent strategy. CritiquePlan may remain private while weakness taxonomy shifts. When critique judgment stabilises as one bounded decision, it can publish to the domain or judge library depending on eval shape. Graduation is intentional promotion, not accidental accumulation of prompt length.

A Skill names a settled procedure. A cognitive unit names a settled judgment. Conflating them hides both.

The cognitive unit · Ch. 16

Invoice intake as second anchor

The books use invoice intake for arithmetic-rich composition: 400,000 invoices monthly, field interpretation cognitive units composed by extraction Skill. That example reinforces the two-shelf model. cognitive units remain pointable and independently evaluable. The Skill owns the multi-step capability name product teams search for. Meal Companion supplies judgment terrain. Invoice intake supplies procedure scale. Platform owners benefit from learning both rather than collapsing them into one inventory type.

Platform catalog design

Splitting catalog UI and search filters by inventory type keeps the two shelves from blending. Manifest schema differs: cognitive unit manifests emphasise decision sentence, judgment type, applicability, and judgment suite, while Skill manifests emphasise capability contract, procedure steps summary, seam invariants, procedure suite, and composed dependencies. Packages, not prompts applies to both, and neither shelf accepts Notion dumps.

Meta-agents benefit from querying the skill library first for known multi-step work, then the cognitive unit library for remaining open judgments, then the organisational library for conduct packages. Wrong default order reinvents procedures in prompts or stretches judgments into fake compound packages. Documenting search order in agent strategy works the same way HTTP clients document retry policy.

Governance across two shelves

Skill libraries and cognitive unit libraries serve different boundaries but share governance: sealed identity, suites, owners, and substitution rules. Mixing them in one browse UI without labels recreates confusion. Invoice intake may combine deterministic Skills with open cognitive units, and architecture docs benefit from showing which shelf each package lives on and why.

Publishing a cognitive unit happens when one open decision stabilises with suite evidence. Publishing a Skill happens when procedure order, seams, and side effects stabilise with procedure suite evidence. Graduation criteria prevent premature Skill publish that hides judgments needing independent ownership. Two shelves remain distinct even when one team owns both: publish judgment packages and procedure packages on different evidence bars.

What to do next

The practical first step is to split catalog UI and search filters by inventory type. Requiring procedure suites before Skill publish, in addition to cognitive unit greens inside, prevents premature packaging. Stopping the pattern of stretching multi-judgment prompts into fake compound packages requires awareness at architecture review. Documenting substitution policy per shelf makes platform expectations concrete.

See sharing judgment through libraries for the org publish model, Skill versus capability for conceptual grounding, packages, not prompts, and substitution rules.

Read next: Sharing judgment through libraries.