--- name: using-wiki version: 1.1.0 description: Policy skill for working with an existing `.wiki/` (Karpathy LLM Wiki pattern). Use when the user asks to ingest a document, answer from the wiki, lint/health-check it, or says "use project wiki", "обнови вики", "проверь вики", "запроси вики", "заингесть", "query the wiki". Also use when modifying any file under `.wiki/` — the workflow and formats below are mandatory, and project-specific conventions live in `.wiki/CLAUDE.md`. If `.wiki/` is missing or non-canonical, delegate to `setup-wiki` first (it has its own confirmation gate). Renamed from `wiki-maintainer` at v1.0.0. --- # using-wiki > Policy for maintaining an LLM Wiki (Karpathy pattern: https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). Knowledge is **compiled once and kept current** across three layers, via three named operations, with strict file formats that make the wiki parseable and grep-friendly. This skill governs *usage* of an existing wiki — initial creation and migration to canon are owned by `setup-wiki`. ## Prerequisites This skill assumes the project has a canonical `.wiki/` layout: `CLAUDE.md` (schema), `index.md` (catalog), `log.md` (op log), `overview.md`, `raw/README.md`, and the six content directories `entities/`, `concepts/`, `packages/`, `sources/`, `contradictions/`, `open-questions/`. If `.wiki/` is **missing**, or the layout is **non-canonical** (e.g. `SUMMARY.md` instead of `index.md`, or `source/` instead of `concepts/`/`sources/`, or `contradictions/`/`open-questions/` directories are absent) — invoke the `setup-wiki` skill first. It detects the situation (greenfield vs migrate) and creates or migrates the structure with its own confirmation gate. Only after `setup-wiki` finishes should this skill proceed with the operations below. ## Three layers (do not blur) 1. **Raw sources** — `.wiki/raw/` (or external paths registered in `raw/README.md`). **Immutable.** Read, never edit. The only exception is appending a `> Status` blockquote when the user explicitly asks for a status audit. 2. **Wiki** — everything else under `.wiki/`. Agent-owned. Entity / concept / package / source summary pages. 3. **Schema** — `.wiki/CLAUDE.md`. Project-specific conventions (what entities, what packages, naming). Always read it first if present; it overrides this skill when it conflicts. ## First step on every operation 1. Read `.wiki/CLAUDE.md` if it exists. 2. Read `.wiki/index.md` to locate relevant pages. 3. Only then act. If `.wiki/CLAUDE.md` is missing, the layout is incomplete — invoke `setup-wiki` rather than improvising. ## Three operations ### Ingest — «заингесть X» 1. Read the raw source fully. 2. Extract: entities, concepts, packages, cross-cutting patterns. 3. Create `sources/.md` (one summary page per source, ~50–150 lines). 4. For each affected entity/concept/package page: - If it exists → update it. **Flag contradictions explicitly** with `> **Противоречие:** источник A говорит X, источник B — Y`. Don't silently overwrite. - If not → create it. 5. Update `index.md` — add or move entries. 6. Append one line to `log.md` (format below). 7. Report to the user: what created, what updated, what contradictions found. **One ingest may touch 10–15 pages. This is normal — that's why LLMs do it.** ### Query — вопрос по wiki 1. Read `index.md` first, then drill into relevant pages. 2. Answer with citations as markdown links to wiki pages. 3. **Compound the wiki.** If the answer is a real synthesis (comparison, analysis, new connection) — ask the user: "Сохранить как страницу wiki?" Good queries become durable pages under `concepts/`, `analyses/`, or similar. 4. Append one line to `log.md`. ### Lint — «проверь wiki» Scan for: - **Contradictions** between pages. - **Orphans** — pages with no inbound links. - **Stale claims** — git `log -p` on the raw source shows it was updated after the summary's `ingested:` date. - **Missing entities** — concepts mentioned in prose but without their own page. - **Empty/TODO sections.** Report as a punch list. Don't delete anything automatically. Append one line to `log.md` summarizing the findings. ## File formats (MANDATORY) ### Page frontmatter ```yaml --- title: Человекочитаемое имя type: entity | concept | package | source | contradiction | open-question | overview tags: [short, tokens] sources: [../sources/foo.md, ../sources/bar.md] updated: 2026-04-21 --- ``` Source pages also carry `ingested: YYYY-MM-DD` and `raw_path: ../raw/...`. Contradiction pages also carry `status: open | resolved | accepted-divergence` and `affects: [../entities/x.md, ../concepts/y.md]`. Open-question pages also carry `status: open | answered | obsolete` and `touches: [../entities/x.md, ../sources/z.md]`. ### File naming - `kebab-case.md`, **Latin only**. Transliterate Cyrillic / other scripts in filenames (`план переписывания` → `ozon-client-rewrite.md`). Keep the original title in the H1 and frontmatter. - `entities/.md`, `concepts/.md`, `packages/.md` (no `@org/` prefix), `sources/.md`, `contradictions/.md`, `open-questions/.md`. ### `log.md` — append-only, grep-parseable Every entry **must** start with: ``` ## [YYYY-MM-DD] | ``` Operations: `ingest`, `query`, `lint`, `refactor`, `decision`, `init`. Parseable with: `grep "^## \[" .wiki/log.md | tail -20`. ### `index.md` Catalog, not narrative. One line per page: `- [Title](path) — hook.` Sections by type (entities / concepts / packages / sources / contradictions / open-questions). Update on every ingest. ### Cross-references - Wiki → wiki: relative markdown links, `[Name](../entities/x.md)`. - Wiki → code: relative path from repo root: `[foo.js](../../packages/api/foo.js)`. - Wiki → raw: `../raw/`. - URL-encode spaces in paths (`%20`) and Cyrillic when needed. ## Quick reference | Situation | Files touched | |---|---| | Ingest one doc | `sources/.md` (new) + 3–15 entity/concept/package pages + `index.md` + `log.md` | | Query | (read only) + optionally new wiki page + `log.md` | | Lint | (read only) + `log.md` | | Bootstrap / migrate to canon | (delegated to `setup-wiki`) | ## Common mistakes - **Editing `raw/`.** Don't. Only allowed: status blockquote when user explicitly asks. - **Dumping raw content into `sources/`.** Summaries are summaries. Link to raw, don't copy it. - **Silent overwrites.** When a new source contradicts an existing page, flag it with a `> **Противоречие:**` block; don't just overwrite. - **Narrative `log.md`.** `Today I added…` is wrong. Use `## [YYYY-MM-DD] ingest | `. - **Non-ASCII file names.** Breaks greppability and cross-platform. Transliterate. - **Forgetting `index.md`.** Pages not listed there are effectively invisible for future queries. - **Skipping contradictions in lint.** The wiki's value grows from surfaced tensions, not from false consensus. - **Improvising layout when canon files are missing.** If the wiki is missing or partial, hand off to `setup-wiki` instead of patching ad hoc. ## When NOT to use this skill - Project has CLAUDE.md / AGENTS.md docs but no `.wiki/` — that's regular project documentation, not an LLM Wiki. - User wants a single-file README or ADR — this skill is for persistent interlinked knowledge bases. - One-off questions about code — use regular file reading, not wiki workflow.