Wiki

Wiki — Persistent Knowledge Base Skill Family

Parent skill for building and maintaining file-based markdown knowledge bases. Routes operational work to reference files.

This is a slim parent — detailed protocols live in reference files. Read this file to understand WHAT wikis are and WHICH reference file handles WHICH operation. Read the reference files for HOW.

Runnable commands (#35)

The protocol files describe the contract; these perform the parts of it that are pure mechanism, so they are not re-derived by a model on every run:

W=~/.claude/skills/wiki/scripts/wiki_lint.py
python3 $W create --path ~/wikis/trading --name "Trading Research" --domain "systematic equity"
python3 $W lint   --wiki ~/wikis/trading        # exit 2 if anything fails or warns

create writes the skeleton and a WIKI.md carrying all 11 required sections, leaving sections 1 and 10 as deliberate placeholders — a wiki whose purpose and domain behaviour are unstated drifts into a folder of notes.

lint enforces the §3 frontmatter contract: required fields, closed enums, kebab-case slugs matching filenames, dates in order, and every source entry citable (a path plus one of pages/lines/anchor). A wikilink that resolves to nothing is an ERROR, because a wiki asserting connections it does not have is worse than no wiki. Staleness and a deprecated page with no successor are warnings, not errors — conflating the two teaches people to ignore the output.

ingest.py is deliberately absent. Reading a source and deciding what a page should SAY is comprehension, not mechanism, and a script pretending otherwise would produce confident, shallow pages. ingest.md remains the protocol the model follows.

1. Snapshot before: capture sha256sum, wc -l, stat -c '%Y %s' of the target file. Record the hash explicitly in the conversation/log.
2. Backup: cp -p <file> <file>.bak.YYYYMMDDTHHMMSSZ with a UTC-style timestamp suffix. Backups stay in-place under the wiki root — they survive cp -r and are git-trackable.
3. Compose edits in memory — Read the file, plan the modifications, but DO NOT write yet.
4. Re-check hash immediately before write: sha256sum again and compare against the snapshot. If different → abort the write, alert the caller with the divergent hashes, do NOT silently overwrite. The backup remains for forensics; the new state may contain useful work that must not be lost.
5. Apply edits atomically: prefer the harness's Edit tool (which does atomic replace) over cat > file. For larger rewrites, write to a sibling <file>.new, fsync, then mv to the final name.
6. Post-write confirmation: capture the new sha256sum + line count and log it. This creates an audit trail.

The protocol survives the "other session edited it without acquiring our lock" failure mode. The price is one extra sha256sum per write — negligible vs the cost of a silently-overwritten index.

What a Wiki Is

A wiki is a self-contained directory with three layers:

<wiki-root>/
  WIKI.md                 # Schema/conventions for THIS wiki
  index.md                # Master content catalog
  log.md                  # Chronological operations log
  raw/                    # IMMUTABLE source files (date-prefixed)
  wiki/                   # LLM-owned content layer (categorized pages)
  _templates/             # Per-wiki instance templates (customizable copy)
  _maintenance/           # Agent operational state (link-index, lint-history, tags)
  .wiki-meta.yaml         # Local registry backup
  .wiki.lock              # Single-writer lock (when present)

Layer ownership:

• raw/ — IMMUTABLE. Once deposited, never modified.
• wiki/ — LLM-owned. Agent writes; humans read. Human edits flagged on lint.
• WIKI.md + schema — CO-EVOLVED. Agent proposes, user approves.

Registry: ~/.wiki-registry.yaml (user home, not in ~/.claude/ — wikis are cross-tool).

Routing Table — Which Reference File For Which Task

Delegating to a reference file means: read that file into context, then follow its protocol. Do not re-derive logic here.

Domain Templates (6)

Two template locations — do not conflate:

• Master (this skill family): ~/.claude/skills/wiki/templates/<name>.md — canonical, updated by alf
• Per-wiki instance: <wiki-root>/_templates/<type>.md — copied at wiki creation, customizable per wiki

When NOT to Use This Skill

• Architecture mapping for AI consumption → use project-documentation (PROJECT.md, COMPONENT.md)
• Session operational log → use history.md (recent) + history/INDEX.md (archived) in the project root
• Personal user memory → use MEMORY.md auto-memory
• Live web search / RAG → wikis are compiled knowledge, not live search
• Small one-off notes → just use a markdown file, don't bootstrap a wiki

The wiki is for persistent domain knowledge that compounds across sources. Everything else has a better home.

Anti-Patterns