Knowledge

Purpose

KNOWLEDGE.md files hold background knowledge — rationale, decision tables, constraints — with a fixed frontmatter schema so they can be found without being read. This skill covers finding them and writing them.

When to use: before designing or reviewing in an unfamiliar area (search first) / when a decision or rationale worth keeping has been settled (author).

Search

python3 scripts/knowledge/search.py                # list all documents
python3 scripts/knowledge/search.py lookup rbac    # every term must match

Terms match name, type, keywords, description, and path (case-insensitive). Judge by the printed description; open only the files you actually need.

Frontmatter schema

Actor convention: <producer>/<version> for agents (e.g. claude-code/fable-5), human:<id> for people (e.g. human:hyeokjin).

Lifecycle rules

• A meaningful change (content, judgment, table) updates generated and removes verified — the sign-off applied to the old content. Typo and formatting fixes touch neither.
• verified is added only for a human review of the current content.
• Set status: deprecated before deleting a document, so inbound links get a window to migrate.
• Knowledge follows the rules: when an AGENTS.md change shifts a base assumption, or a migration a document describes as in-progress completes, update the affected document in the same change. Routine task-level edits are not a trigger — the test is whether the document's assumptions still hold.

Body structure

• The document's job is the package's background knowledge — what a newcomer must assume before touching the package. Local curiosities without that frame do not stand alone.
• Open with why the package exists — the reason it is defined as its own package and what role it plays for its consumers — before any specific topic.
• The heading is the claim: each section heading states one claim; the body backs it with 2-4 single-sentence bullets. Comparisons and enumerations use tables or list syntax — never a long paragraph. Prose paragraphs are allowed only in the opening section, two sentences at most.
• A parent document never restates knowledge a subpackage document owns — link it from the header pointer or where the context needs it. Every section must be knowledge about this package itself.

Size and splitting

• One KNOWLEDGE.md per package. The document follows the package structure — there are no per-topic knowledge files.
• Keep a document under ~200 lines and on one topic cluster. The description is the test: when it reads as two unrelated lists, the package is carrying two concerns.
• An oversized KNOWLEDGE.md is a package-design signal, not a documentation problem — split the package, or move the extra topic's knowledge into the subpackage's own KNOWLEDGE.md.

References and links

• Code references go in sources (paths only). Document-to-document references go in the body as relative markdown links, where the surrounding sentence says why the link matters. There is no frontmatter link list.
• No dangling links: CI fails on links to missing files. Mention a planned document in plain text, without a link.

Check before pushing

python3 scripts/knowledge/check.py

Validates the schema, scope/sources path existence, body links, name uniqueness, and the verified-not-older-than-generated invariant. knowledge-check.yml runs the same script on pull requests.

What goes where