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

name, version, description

name	version	description
using-wiki	1.1.0	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/<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 | 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/<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.

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