factory/skills/using-wiki/README.md

using-wiki

Runtime policy for an LLM Wiki built on the Karpathy LLM Wiki pattern. Knowledge is compiled once and kept current across three layers, via three named operations, with strict file formats that keep the wiki parseable and grep-friendly.

using-wiki governs usage of an existing .wiki/. Initial creation and migration to canon are owned by setup-wiki.

Renamed from wiki-maintainer at v1.0.0.

When it triggers

• User says: "use project wiki", "query the wiki", "ingest this", or the Russian equivalents ("обнови вики", "проверь вики", "запроси вики", "заингесть").
• Any time the agent modifies a file under .wiki/ — the workflow and formats below are mandatory.
• If .wiki/ is missing or non-canonical, this skill delegates to setup-wiki before doing anything else.

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; it overrides this skill on conflict.

Three operations

Ingest

«заингесть X» — pull a raw source into the wiki.

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: update if exists, create if not. Flag contradictions explicitly with > **Противоречие:** источник A говорит X, источник B — Y. Never silently overwrite.
5. Update index.md.
6. Append one line to log.md.
7. Report: what was created, updated, contradicted.

One ingest may touch 10–15 pages. That's normal — that's why an LLM does it.

Query

A question answered from the wiki.

1. Read index.md first, drill into relevant pages.
2. Answer with citations as markdown links.
3. Compound the wiki. If the answer is a real synthesis, ask the user: "Сохранить как страницу wiki?" Good queries become durable pages under concepts/ or analyses/.
4. Append one line to log.md.

Lint

«проверь wiki» — health check.

Scan for:

• Contradictions between pages.
• Orphans (pages with no inbound links).
• Stale claims (raw source updated after the summary's ingested: date — check via git log -p).
• Concepts mentioned in prose but missing their own page.
• Empty / TODO sections.

Report as a punch list. Don't delete anything automatically. Append one line to log.md with the findings.

File formats (mandatory)

Page frontmatter

---
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 / non-Latin in filenames; keep the original title in H1 + frontmatter.
• entities/<name>.md, concepts/<name>.md, packages/<name>.md (no @org/ prefix), sources/<slug>.md, contradictions/<slug>.md, open-questions/<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.

Parse with: grep "^## \[" .wiki/log.md | tail -20.

index.md

Catalog, not narrative. One line per page: - [Title](path) — hook. Sections by type. 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 (%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 a new wiki page + log.md
Lint	(read only) + log.md
Bootstrap / migrate	(delegated to setup-wiki)

Common mistakes

• Editing raw/. Don't. Only allowed change: status blockquote on explicit request.
• Dumping raw content into sources/. Summaries are summaries. Link to raw, don't copy.
• Silent overwrites on contradictions. Flag them with a > **Противоречие:** block.
• Narrative log.md. "Today I added…" is wrong. Use ## [YYYY-MM-DD] ingest | <what>.
• Non-ASCII filenames. Breaks greppability and cross-platform. Transliterate.
• Forgetting index.md. Pages not listed there are invisible to future queries.
• Improvising layout when canon files are missing. Hand off to setup-wiki instead of patching ad-hoc.

When NOT to use

• The project has CLAUDE.md / AGENTS.md docs but no .wiki/ — that's regular documentation, not an LLM Wiki.
• The user wants a single-file README or ADR — this skill is for persistent, interlinked knowledge bases.
• One-off questions about code — read files directly, no wiki workflow needed.

Install

From the repo root:

bash scripts/install.sh using-wiki

Works on Windows under git-bash, Linux, macOS.

See also

• setup-wiki — companion, owns .wiki/ creation and canon migration.
• project-bootstrap — invokes setup-wiki for new projects.
• Karpathy's LLM Wiki gist: https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f