139 lines
7.5 KiB
Markdown
139 lines
7.5 KiB
Markdown
---
|
||
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/<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 | 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.
|