---
name: wiki-maintainer
version: 1.0.0
description: Use when a repo has a `.wiki/` directory following Karpathy's LLM Wiki pattern and the user asks to ingest a document, answer from the wiki, lint/health-check it, or says "заингесть", "обнови вики", "проверь вики", "запроси вики", "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`.
---

# wiki-maintainer

> Maintain 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.

## 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, treat it as a greenfield wiki and offer to bootstrap one (schema + empty index/log + `raw/README.md`).

## Three operations

### Ingest — «заингесть X»

1. Read the raw source fully.
2. Extract: entities, concepts, packages, cross-cutting patterns.
3. Create `sources/<slug>.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 | 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/...`.

### 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/<name>.md`, `concepts/<name>.md`, `packages/<name>.md` (no `@org/` prefix), `sources/<slug>.md`.

### `log.md` — append-only, grep-parseable

Every entry **must** start with:

```
## [YYYY-MM-DD] <operation> | <short description>
```

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). 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/<file>`.
- URL-encode spaces in paths (`%20`) and Cyrillic when needed.

## Quick reference

| Situation | Files touched |
|---|---|
| Ingest one doc | `sources/<slug>.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 empty wiki | `CLAUDE.md`, `index.md`, `log.md`, `overview.md`, `raw/README.md` + empty `entities/ concepts/ packages/ sources/` |

## 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 | <what>`.
- **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.
- **Bootstrapping a new wiki without asking for domain.** Directory layout depends on whether this is a code-project wiki, a research wiki, or a reading-companion wiki. Ask briefly before creating.

## 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.