claude-skills/skills/wiki-maintainer/SKILL.md

name, description

name

description

wiki-maintainer

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

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