The shape of a knowledge pack
A corpus is a directory and a handful of conventions. Every element below is committed, human-readable, and diff-friendly — no database, no build artifact. The examples on this page are the real finance-settlement pack, unedited.
Pack layout
A corpus lives under knowledge/ at the repo root. It holds one registry and one or more packs — each pack a self-contained Agent Skills folder: a required SKILL.md plus a references/ directory of documents.
A pack lists its own contents once, in its SKILL.md slug map; identity lives in the single root registry. One source of truth for ids — not one per folder.
Two-layer identity
Every reference carries two names, and keeping them separate is the load-bearing idea in the whole schema.
Portable and human-readable. Assigned by the pack author, stable as the pack travels between repos. Shape: NNN-topic.
Opaque and repo-unique. Assigned by the consuming project when a pack is registered — the token a spec actually cites. It means nothing on its own; the registry gives it meaning.
It's the DOI move. A paper has a human title and a stable, opaque DOI; you cite the DOI so the reference survives a retitle. Here the slug is the title — legible, pack-owned, potentially colliding across packs — and the KB-NNNN is the DOI: project-unique, citeable, immune to the slug being reused elsewhere. Two packs can both ship a 001-overview; only the registry decides which KB-NNNN each becomes here.
The root registry
knowledge/index.md is the one place ids are minted and editions pinned. It's an ordinary markdown table — eight columns, the resolver's source of truth. This is the real settlement registry:
| KB-NNNN | Marketplace | Plugin | Slug | Title | Edition | Path | Status |
|---|---|---|---|---|---|---|---|
| KB-0001 | spectastic-examples | finance-settlement | 001-us-equities-settlement-cycle | US equities settlement cycle | 2024-05-28 | finance-settlement/references/001-us-equities-settlement-cycle.md | |
| KB-0002 | spectastic-examples | finance-settlement | 002-fx-settlement-risk-pvp | FX settlement risk and PvP | 2022-07-08 | finance-settlement/references/002-fx-settlement-risk-pvp.md | |
| KB-0003 | spectastic-examples | finance-settlement | 003-books-of-record | Books of record — IBOR, ABOR, PBOR | 2024-01-15 | finance-settlement/references/003-books-of-record.md |
knowledge/ prefix. Points at the document that backs this id.Reference frontmatter
Each document under references/ opens with YAML frontmatter — its provenance. The slug lives here (pack-owned); the KB-NNNN deliberately does not (project-owned, in the registry). Real frontmatter from 001-us-equities-settlement-cycle.md:
| Field | Req | Meaning |
|---|
Never fabricate the content-hash. It's a hash of the document body — the integrity anchor that lets validation tell an edited reference from an intact one. It's computed, not typed. Authoring covers how →
Editions & supersession
A domain fact can change in the world — the settlement cycle really did move T+2 → T+1. The corpus models that as an edition, and it appends: the new edition becomes current in the registry, and the prior document is retained, never overwritten.
Retained editions live under references/superseded/ named <slug>@<edition>.md. The superseded document keeps its own frontmatter with status: superseded. Because it's still on disk, a citation pinned to the old edition still resolves — it just flags as stale rather than becoming a dead link. That's the point of edition-pinning: point-in-time correctness. A decision made in 2023 that cited the T+2 rule was correct then, and its citation still opens the rule as it stood. How staleness surfaces →
The SKILL slug map
A pack's SKILL.md is a standard Agent Skill file — a name/description header and instructions — plus one spectastic addition: a slug map table listing the pack's own references by slug, so an agent can see the menu before opening any document (progressive disclosure). Five columns:
| Slug | Title | Description | Edition | Path |
|---|---|---|---|---|
| 001-us-equities-settlement-cycle | US equities settlement cycle | Standard settlement cycle for US equities (T+1); prior T+2 retained. | 2024-05-28 | references/001-us-equities-settlement-cycle.md |
| 003-books-of-record | Books of record — IBOR, ABOR, PBOR | Investment, accounting, performance books and each one's cash basis. | 2024-01-15 | references/003-books-of-record.md |
The slug map uses the pack-relative path (references/…) and the pack-owned slug — no KB-NNNN. That's what keeps the pack portable: it says nothing about which project consumes it or what ids that project assigned.
Licensing
Every reference declares a license, and validation enforces an allowlist of permissive terms. A corpus is redistributable knowledge; the allowlist keeps a pack from quietly carrying content no one may lawfully republish.
Plain CC-BY-<version> is accepted too — but deliberately not the NC / ND / SA variants. Anything outside the list trips the corpus-license rule (a warning), so an unredistributable license is surfaced rather than slipping through silently. The intent is that references are hand-authored distillations or genuinely open material, with the source always named in origin / origin-url.
Discoverability
A pack meant to be published — offered to other projects — carries a marketplace.json manifest describing it. This is a publishing concern: a consumer repo that has merely imported packs does not keep a root marketplace.json; it keeps the registry. The manifest is how a pack announces itself to a marketplace, not how a project tracks what it uses.
Publishing and importing packs is the command reference's territory (corpus publish / corpus import). Here it's enough to know the manifest exists and which side of the fence it lives on.