vitya
e1e5bd1309
Six infra skills carry `version: 1.0.0` in frontmatter: project-bootstrap, setup-context7, task-status-wiki, using-context7, using-markitdown, wiki-maintainer. Bumped manually on SKILL.md edits; semver — MAJOR breaks contract, MINOR adds, PATCH wording. project-bootstrap gets a new Step 5.5 that writes .wiki/concepts/bootstrap-manifest.md per project — skill + version + role table read live from each delegated skill's frontmatter, not hardcoded. The file is overwritten on re-bootstrap; for history, git log. Why: when canonical layout for .wiki/ or .tasks/ changes, projects bootstrapped under the old version drift silently. The per-project manifest makes that drift debuggable instead of guesswork. Communication and discovery skills (caveman family, find-skills, active-platform) aren't versioned — their content is "good copy-paste" and snapshot mismatch isn't a layout problem. Wiki: .wiki/concepts/skill-versioning.md documents the convention; index.md and log.md updated. .tasks/STATUS.md tracks (a/b/c) progress. Setup/using split for wiki and tasks (commits b and c) follows. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
129 lines
6.2 KiB
Markdown
129 lines
6.2 KiB
Markdown
---
|
||
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.
|