llm-wiki

What this skill does

# LLM Wiki

Build and maintain a personal knowledge base as plain markdown. You manage two directories: `raw/` (immutable source material) and `wiki/` (compiled knowledge you own). Sources land in `raw/`, you compile them into `wiki/` articles, and the wiki compounds over time. Everything is local markdown with YAML frontmatter, readable on GitHub and openable as an Obsidian vault. No servers, no databases, no embeddings.

Core idea (Karpathy): the LLM writes and maintains the wiki; the human chooses sources and asks questions. Knowledge is compiled once at ingest and kept current, not re-derived on every query. That is the difference from RAG, which retrieves raw chunks and re-synthesises on every question.

## Invocation

**Query is the default.** Ingest, Lint, Audit, and Critique are the four deliberate operations - each opted into by its verb or by a request that plainly calls for it. Anything else is a Query against the wiki: a bare question, "what do I know about X", "summarise everything on Y". You do not need a `query` keyword to query; it is what the skill does unless one of the four operations is clearly being asked for.

A leading mode argument routes straight to that operation:

- `ingest` (alias `add`) - Ingest. Any trailing text is the source: a URL, a path, or pasted content.
- `lint` - Lint. Health checks; needs no further input.
- `audit` - Audit. Trailing text names the article or topic to verify.
- `critique` (alias `scrutinise`) - Critique. Trailing text names the article, topic, or pasted content whose reasoning to examine.
- `query` (alias `ask`) - Query. Rarely needed as an explicit keyword, but it forces query handling when a question might otherwise look like one of the four operations above.

So `/llm-wiki lint` runs Lint and `/llm-wiki ingest https://...` ingests that URL. Otherwise treat the whole argument as a natural-language request: route it to Ingest, Lint, Audit, or Critique only when it clearly calls for one, and answer everything else as a Query.

### What's always required, and what's scenario-gated

Every operation, always: you act only on the user's request (never background-write); any write compiles from a source already in `raw/` (never straight from a live URL or external path), then updates `wiki/index.md` and appends `wiki/log.md`; you bump an article's `updated` whenever its content changes; and you replace outdated knowledge by superseding it, never by deleting or editing in place. These hold across all five operations.

Everything else is scenario-gated, and its detailed protocol lives in `references/` - the authoritative procedure, which SKILL.md only summarises. When the request or the situation matches one - a rich-format source, a distilled extract, a long or noisy source, a concept map, the gap register, local content, a lint, an audit, a critique - you MUST read the named reference and follow it before acting, rather than working from memory or assuming you know the format or the steps. If a section points at a reference, that pointer is an instruction to open it, not a citation to note. When unsure whether a reference applies, read it and decide; the cost of reading is small next to the cost of corrupting the wiki by guessing.

## Design philosophy

These principles decide what the wiki does and, just as much, what it leaves out. Follow them when a situation is not covered explicitly below.

- **Filter at ingest, not in retention.** Decide what is worth keeping, and strip secrets, when a source arrives. A clean ingest avoids most cleanup later.
- **Supersession, not decay.** Knowledge does not expire on a timer. When new information replaces old, mark the old article stale and point it at the replacement. Keep it. An old bug report or a superseded decision still explains why the current state exists.
- **Evidence, not confidence scores.** Never attach a number like `0.85` to a claim. State the support instead: which sources confirm it, which contradict it, when it was last confirmed. A reader can check links; they cannot check a float.
- **Git is the audit trail.** History, rollback, and "how did this get here" come from version control, not from bespoke versioning fields. Recommend the wiki live in a git repo.
- **Invocation-driven, human in the loop.** You act when the user asks. Do not set up background automation that writes to the wiki unsupervised. The user curates and directs; you do the bookkeeping.
- **Text-only and self-contained.** Plain markdown, relative links, YAML frontmatter. Readily available tools (grep, git, the agent's own file and web tools) are fine. External servers, vector stores, and embedding pipelines are not.

Deliberately excluded, and why: embedding or vector search and knowledge-graph databases (infrastructure the personal scale does not need; index plus grep covers it); numeric confidence scores (false precision); automatic forgetting or decay curves (they bury exactly the errors and superseded decisions you most need to remember); autonomous background writes (an unreviewed LLM corrupts the base silently); multi-agent sync and governance layers (out of scope for a personal wiki).

## Architecture

Three layers, all under the user's project root, plus an optional `local/` for personal content.

**raw/** - Immutable source material. You read, never modify. Organised by topic subdirectories, e.g. `raw/machine-learning/`. The source of truth.

**wiki/** - Compiled knowledge articles. You have full ownership. One level of topic subdirectories only: `wiki/<topic>/<article>.md`. Four special files:
- `wiki/README.md` - Orientation for anyone opening the wiki without this skill: what the structure is and the conventions that keep it sound. Mostly static; created at init.
- `wiki/index.md` - Global catalogue. One row per article, grouped by topic, with link, summary, and Updated date. The entry point for queries.
- `wiki/log.md` - Append-only operation log with a greppable prefix.
- `wiki/gaps.md` - Register of known unknowns: concepts the wiki references but has not written, and questions it cannot answer. "What we don't know yet" to the index's "what we know".

**local/** (optional) - Personal markdown kept out of git: meeting prep, drafts, working notes, private sources. A sibling of `raw/` and `wiki/`, excluded by the wiki `.gitignore`, present in the user's clone only. It is a scratch bench, exempt from the index, log, gaps, cascade, and audit. One rule governs it: `local/` may link into `wiki/` and `raw/`, but no committed file may ever link into `local/` (broken for other clones, and it leaks the path into git). Full rules, query behaviour, and the promotion path: `references/local-content.md`.

**SKILL.md** (this file) - The schema layer. Defines structure, format, and workflow. This is the most important file in the system: it is what makes a disciplined wiki maintainer rather than a generic chatbot. Templates live in `references/` relative to this file; read them when you need the exact format.

### File format

Every article and raw file starts with YAML frontmatter, then standard markdown. Frontmatter is machine-readable (the agent parses it; Obsidian shows it as Properties; the Dataview plugin can query it). The body uses standard markdown links so it renders everywhere, including GitHub, and still populates Obsidian's graph and backlinks panel.

Article frontmatter:

```yaml
---
title: Transformer Architectures
type: concept          # concept | entity | archive
topic: machine-learning
created: 2026-04-03
updated: 2026-04-03
status: current        # current | stale
superseded_by:         # relative path to replacement, set only when status: stale
tags: [transformers, attention]
aliases: []
---
```

- `updated` is the canonical "knowledge last changed" date. The index mirrors it; lint reads it. It changes when the article's content changes, not when the file is touched.
- `type: archive` marks crystallised query answers (see Query). Archives are point-in-ti