Knowledge-base authoring skill

skillsactive owner: philip · updated 2026-11-14

relates: onboarding · kb-retrieval-token-budget

Knowledge-base authoring skill

Teaches any AI agent the full KB authoring workflow so it can add or amend entries correctly on the first try — the amend path for humans and agents who cannot (or should not) hand-write frontmatter and projections.

Trigger

• "add this to the KB", "capture this learning", "amend the knowledge base", any task whose deliverable is a knowledge-base entry or PR against this repo.

Contract

• Location: skills/knowledge-base/SKILL.md in this repo.
• Version: 0.1.0.
• Install: copy skills/knowledge-base/ into the agent's skills dir (.agents/skills/), or unzip kb-skills.zip so <skills-dir>/knowledge-base/SKILL.md exists. See kb:start-here "Install the agent skills".
• Inputs: the knowledge to capture (diff, transcript, decision, research), repo clone access.
• Outputs: one or more entry files + regenerated machine/ projections, as a PR (SEC-02: never direct push).

How it works

1. Clone; read AGENTS.md, SPEC.md, types.dsl.
2. Search machine/index.dsl — amend an existing entry instead of duplicating.
3. Pick the type directory; read instructions/ai/<type>.md and templates/<type>.md.
4. Write one entry per file, flat frontmatter, cite sources, no secrets.
5. Run python3 scripts/compile.py in the same commit as the content change.
6. Verify: compile.py --check + unit tests; open a PR.

Rules

• machine/ is generated — never hand-edit.
• SPEC.md changes are new versions, not edits.
• Index-first consumption; load only the type files the task needs (kb:kb-retrieval-token-budget).

Anti-patterns

• Free-form markdown without frontmatter (compiler rejects).
• Duplicating an existing entry instead of amending (search index first).
• Committing content without regenerating machine/ (drift gate blocks).
• Including secrets or credentials (SEC-01 rejects).

Sources

• skills/knowledge-base/SKILL.md (this repo)
• onboarding/start-here.md, AGENTS.md, SPEC.md