knowledge

name	knowledge
description	Search and author KNOWLEDGE.md background-knowledge documents - frontmatter schema, search/check scripts, and the generated/verified lifecycle rules
disable-model-invocation	false
tags	["docs","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

Field	Required	Value
name	yes	stable id, kebab-case, unique across the repo. Never rename
type	yes	document kind: design-rationale / decision-table / constraints / reference (open vocabulary)
description	yes	noun-phrase list of what the document covers — the primary search signal. Not a sentence about the document
scope	yes	directory the knowledge applies to
keywords	no	5-10 terms; include code identifiers (class/function names)
sources	no	file/directory paths the content is grounded in — never PR or issue numbers
generated	yes	{by, at} — actor and date of the last meaningful change
verified	no	list of {by, at} — human review sign-off for the current content
status	no	draft / stable (default) / deprecated

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

Content	Home
Imperative rules	AGENTS.md
Rationale, decision tables, constraints, canonical examples	KNOWLEDGE.md
Human-facing component overview	README.md
Issue-scoped working notes	outside the repo