| name | kcp-author |
| description | Write or improve units in a KCP knowledge.yaml manifest — effective intents, triggers, relationships, audience targeting, negative-space (not_for), and temporal validity — and validate them. Use when editing a knowledge.yaml, when an agent keeps loading the wrong unit for a task, or when manifest queries return poor matches. |
Author effective KCP units
A manifest is only as good as its routing. The job is to make the right unit
win for the right question and never load for the wrong one.
When to use
Someone is editing a knowledge.yaml, query results are off (wrong unit, or no
match), or a manifest needs richer metadata (relationships, negative space,
validity windows).
What makes a unit route well
intent is the question, not the title. "How do I authenticate a
request?" beats "Auth docs". Agents match against this in natural language.triggers are the words that question contains. Include synonyms and the
domain terms a user would actually type (auth, login, oauth, token, sso).
Keep each ≤ 60 chars, ≤ 20 per unit.not_for prevents misfires (RFC-0015, §4.20). If a unit is tempting but
wrong for a class of task, say so: not_for: ["billing questions", "frontend routing"].
Add not_for_strict: true for a hard exclusion rather than a soft demotion.scope and audience narrow the field. audience: [agent] for
agent-only entry points; [human] for content agents should not surface.content_structure (RFC-0016, §4.19) lets RAG route before fetching:
primary: table | prose | code | …, density: sparse | normal | dense.
Relationships and ordering
depends_on: [id] — load these first (reading order).- A
relationships block expresses typed edges: enables, context,
supersedes, contradicts, depends_on, governs.
Temporal validity (when knowledge changes over time)
Use a temporal block (RFC-0010, §4.22) for policies and runbooks that expire
or are future-dated:
temporal:
valid_from: "2026-04-01"
valid_until: "2026-06-30"
superseded_by: deploy-v2
superseded_by must not form a cycle, and an expired valid_until should name
a superseded_by — the validator warns otherwise.
Always finish by validating
kcp validate
kcp query "<a real user question>"
Iterate until each obvious question returns the unit you intended. See
SPEC.md for the full field set; guides/ for worked examples.
