Skills That Keep the Wiki Honest

---
name: capture-fact
description: Use when somebody states a fact about this application that is not written down yet, how a part of it behaves, what a setting does, what a run of it produced, and it should become or extend a page in the knowledge base. Intake, one-place check, diff to approve, log line.
---

# Capture a fact into the knowledge base

Do these in order. Do not skip ahead to writing; every step before the write
exists to stop a page being minted that should have been an edit.

## Read the contract first

Open `knowledge-base/_schema.md` and read it before anything else. It states
the layers, the frontmatter, the provenance values and what each of them
obliges the body to carry.

Open it by that repo-root path, typed out. Not by a wikilink: a wikilink is a
convention between pages and resolves to nothing when a tool goes looking for a
file. Not from memory of what the schema says, either, including any memory
formed while reading this file.

Nothing in this skill restates a rule from the schema, and that is the point.
A rule copied here would be a second copy with no one checking it against the
first, and it would keep reading as true for as long as it took somebody to
change the schema and not know this file existed. This file holds the order of
the steps. The schema holds the rules.

## Decide the layer

Ask whether the thing said is a wiki fact at all.

- A fact about how this application behaves, that a reader would want and
cannot get quickly from the source: a page.
- A choice that was made, and the reasons it was made over the alternatives: a
decision record, not a page. The wiki cites it.
- A number or a line that the source already states plainly: leave it in the
source. A page that restates a source is a copy that will drift away from it.
- Something nobody has checked and cannot check right now: a question, filed as
one, not a page wearing a confident frontmatter.

## Find the page that already owns it

Search the wiki before writing. If a page already owns the concept, extend that
page. Do not mint a second page whose title is a synonym of the first.

If two pages could plausibly own it, the one whose concept it actually is takes
the fact, and the other one links to it. If the fact contradicts what a page
already says, stop and follow the schema's procedure for that; the disagreement
is the finding, and resolving it quietly destroys the only thing worth knowing.

## Write it in the owning page's register

Match the page you are editing: its sentence length, its heading shapes, how
much it explains before it asserts. A paragraph in a different voice reads as
an insertion, and a reader who notices the seam stops trusting the page either
side of it.

State the fact first and the evidence under the heading the schema names for
it.

## Set the frontmatter honestly

Copy the block from `knowledge-base/_template.md` rather than typing it from
memory. Fill every required field.

Pick the provenance tier for what actually happened, and not for what would
look better. If a command was run and its output read, say so and quote it. If
a file was read, cite it. If nothing was checked against a source, the schema
has a value that says exactly that, and it is the correct one. Claiming a tier
whose evidence is not in the body is the failure the field was added to catch.

## Run the lint

Run `npm run kb`. Read every finding it prints against the page you touched,
and fix what is yours. The lint checks a subset of the schema; a clean run is
not a claim that the page obeys the rest of it.

## Show the diff and wait

Show the person the exact diff you intend to write and the lint's output, then
stop and wait for them to say yes. Do not write first and offer to revert.

The person who stated the fact is the only one who can tell you that you wrote
down something subtly different from what they meant, and the moment they can
still tell you cheaply is before it is a file. This step is a habit in the
procedure rather than a permission rule because a permission rule can only ask
whether a file may be written; it cannot show anybody what is about to go in
it, and an approval prompt on an unseen edit trains a person to say yes.

## Append the log line

After the write lands, append one line to `knowledge-base/_log.md` in the form
that file states at its top, including its Why. The Why is the half that is
worth something later: what changed is visible in the history, and why it
changed is not.

If the fact was one somebody had already filed as an open question, move that
question to answered in `knowledge-base/_questions.md` in the same round.

---
name: kb-freshness-audit
description: Use when asked to audit the knowledge base, check whether the wiki has gone stale, or work out what needs re-verifying. Runs the lint, turns each finding into a question with an owner in the questions file, and changes no page.
---

# Audit the knowledge base and file what it turns up

This skill reads the wiki and writes to one file. It does not edit pages.

## Read the contract first

Open `knowledge-base/_schema.md` by that repo-root path and read it, then open
`tools/kb-lint.mjs`. The schema states the rules; the lint is the only thing
that checks them, and its header states what each of its findings means and
what its exit codes are.

Read both rather than trusting a summary of either, this file included. No
finding name, threshold or exit code is written down here, because a copy of
one here would go on reading as true after the lint changed.

## Run the lint

Run `npm run kb`. Note the exit code as well as the output, the two say
different things, and the lint's own header says which is which. A run that
prints nothing has told you something; read the header to know what.

## Turn each finding into a question

Every finding is somebody's question, and the useful move is naming who. For
each one, write a line in `knowledge-base/_questions.md` in the form that file
states at its top, under the section that matches how urgent it is.

The owner is the role that can actually answer it, which is usually the page's
own owner and not whoever ran the audit. Where a finding is answerable by
running something rather than by asking anybody, say so in the question, and
name the thing to run.

Do not open a second question for something already listed there. Extend or
re-date the line that exists.

## Change no page

Do not edit a page in the wiki from this skill. Not the dates, not the
frontmatter, not a sentence.

A finding is a claim that a page might now be wrong, and the only way to
retire it honestly is for somebody to check the fact against its source again.
An audit that edits the field it is auditing turns the whole scheme into
bookkeeping: every date current, every page passing, nothing re-checked. The
verification is the work, and it belongs to the owner, in a separate round,
through the capture skill.

## Report

Tell the person what the lint said, what you filed, and against whom. Then
stop. Filing the questions is the whole of this job.

# Open questions

One line per question, in the form
`YYYY-MM-DD | owner | the question, ending in a question mark | where it came from`.
The date is the day the question was raised, not the day it was last thought
about. The owner is one role that can answer it, never a list and never a
person's name. An answered question keeps its original line, gains
` -> the answer, and where it landed`, and moves to the last section rather
than being deleted.

This file starts with `_`, so it is machinery and not a page: no frontmatter,
no provenance, and the lint applies no page rule to it. That is on purpose and
argued in `docs/decisions/0111`. A question is the state a fact is in before it
has a provenance, and the file that holds questions cannot be asked for one.

Three sections, and a question sits in exactly one:

- **blocking**, work is stopped until somebody answers.
- **open**, worth answering, nothing is waiting on it.
- **answered**, kept for the record, with its answer on the line.

## blocking

## open

2026-08-30 | maintainer | Can two or more SDK subprocesses run at the same time under one shared `CLAUDE_CONFIG_DIR` without corrupting each other's session state? | `docs/decisions/0030` left the contents of a handed config directory unverified, `docs/decisions/0031` pins one directory for every session, and the roster lets more than one agent hold a session at once. Answerable only with an API key: run two agents concurrently and read what lands in the directory.

## answered

{
"name": "chat-workbench",
"version": "0.35.0",
"description": "The chat app the Build the Chat Plugin track builds: a multi-agent chat workbench with a schema-governed knowledge base.",
"author": {
  "name": "Learn Claude Code"
},
"skills": [
  "./.claude/skills/"
]
}