OpeItcLoc03/claude-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(hermes): mvp-coverage — 9 skills converted to Hermes format

Browse Source 
- mapping.yaml: 7 pending → auto (setup-tasks, using-tasks, setup-wiki,
  using-wiki, using-projects-meta, using-context7, project-bootstrap,
  recommend-dont-menu). pending count now 0.

- dist-hermes/ populated:
  software-development: project-bootstrap (+ assets)
  productivity: recommend-dont-menu, setup-tasks, using-tasks
  research: setup-wiki, using-wiki
  mcp: using-context7, using-projects-meta

- active-platform replace-rule verified: Windows+PowerShell → Linux+bash
  in body SKILL.md (frontmatter description unchanged by design).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
vitya
2026-05-07 09:21:56 +03:00
parent 27026c5e0e
commit 82f82a2036
19 changed files with 2738 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

101
dist-hermes/research/setup-wiki/README.md Normal file
View File

@@ -0,0 +1,101 @@
# setup-wiki
One-time skill that creates or migrates a project's `.wiki/` to the
canonical Karpathy LLM Wiki layout. The runtime policy for working *inside*
that wiki lives in [`using-wiki`](../using-wiki/) — `setup-wiki` is the only
place that creates or rearranges the file structure.
Canonical layout reference:
<https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f>
## When it triggers
- User says: "set up wiki", "init wiki", "create wiki", "migrate wiki to canon",
"wiki layout broken", or the Russian equivalents ("настрой вики",
"инициализируй вики", "wiki сломана").
- [`using-wiki`](../using-wiki/) detects a missing or non-canonical `.wiki/`
and delegates here via its Prerequisites section.
- [`project-bootstrap`](../project-bootstrap/) Step 3 delegates here when
initializing a new project.
## Modes
`setup-wiki` chooses one of three modes after a discovery scan:
| Mode | Trigger | Action |
|---|---|---|
| **greenfield** | No `.wiki/` exists | Create the canonical layout from scratch. |
| **noop** | `.wiki/` already canon (all five canon files + four content dirs) | Report and exit — no writes. |
| **migrate** | `.wiki/` exists with non-canon files (`SUMMARY.md`, `WORKFLOW.md`, `source/`) or missing canon files | Move legacy files (e.g. `source/*.md` → `concepts/*.md` via `git mv`), create missing canon files, drop a timestamped `.backup-*/` next to it. |
Migration **does not auto-rewrite** existing concept content — it only moves
files and prepends minimal frontmatter when missing. Real edits stay your
job.
## What canon means
```
.wiki/
├── CLAUDE.md ← schema: project-specific wiki conventions
├── index.md ← catalog of pages by type
├── log.md ← append-only op log
├── overview.md ← single project overview
├── raw/
│ └── README.md ← raw/ is immutable; this file documents that
├── entities/ ← entity pages (people, services, modules)
├── concepts/ ← design decisions, recurring ideas
├── packages/ ← code packages
└── sources/ ← one summary per ingested source
```
The four content directories each get a `.gitkeep` so git tracks them.
## Hard rules
- **Never auto-mutate.** Phase 1 (discovery) and Phase 2 (plan) always pause
for explicit confirmation. A trigger phrase grants permission to inspect,
not to write.
- **Never touch `raw/` content during migration.** `raw/` is immutable; only
the `.gitkeep` placeholder may be removed when `raw/README.md` replaces it.
- **No re-runs that overwrite a canon wiki.** Phase 1 detection guards
this — `noop` mode bails out cleanly.
- **No invented domain conventions.** The schema's "Domain conventions"
section stays a stub for the user to fill in.
## Procedure (high-level)
1. **Phase 0** — environment sanity (project root, platform check).
2. **Phase 1** — discovery (greenfield / noop / migrate).
3. **Phase 2** — plan + confirm. Wait for explicit "ok"/"go"/"поехали".
4. **Phase 3** — backup (migrate only) → `.wiki/.backup-YYYYMMDD-HHMMSS/`.
5. **Phase 4a/4b** — greenfield create or migrate.
6. **Phase 5** — verify (canon files present, dirs exist, no leftover
non-canon, frontmatter on migrated pages).
7. **Phase 6** — final report; if invoked from `project-bootstrap`, return
silently.
Full procedure with templates and the migration shell snippet lives in
[`SKILL.md`](SKILL.md).
## Rollback
- Greenfield: `rm -rf .wiki/`.
- Migrate: `cp -r .wiki/.backup-<ts>/* .wiki/` and `git reset HEAD .wiki/`.
## Install
From the repo root:
```bash
bash scripts/install.sh setup-wiki
```
Works on Windows under git-bash, Linux, macOS.
## See also
- [`using-wiki`](../using-wiki/) — runtime policy for working with `.wiki/`.
- [`project-bootstrap`](../project-bootstrap/) — orchestrator that delegates
here for new projects.
- Karpathy's LLM Wiki gist:
<https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f>

284
dist-hermes/research/setup-wiki/SKILL.md Normal file
View File

@@ -0,0 +1,284 @@
---
name: setup-wiki
version: 1.0.0
description: Creates or migrates a project's `.wiki/` to the canonical Karpathy LLM Wiki layout — `CLAUDE.md` schema, `index.md`, `log.md`, `overview.md`, `raw/README.md`, plus empty `entities/`, `concepts/`, `packages/`, `sources/`. Use when the user says "set up wiki", "init wiki", "настрой вики", "инициализируй вики", "create wiki", "migrate wiki to canon", "wiki сломана", "wiki layout broken", or whenever `using-wiki` detects a missing or non-canonical `.wiki/`. Two modes — greenfield (no wiki) and migrate (existing non-canonical layout). Confirmation gate before writing. Cross-platform.
---
# setup-wiki
> Creates or migrates a `.wiki/` to canon. The canonical layout is documented at https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f and enforced by `using-wiki`. This skill is the *only* place that creates or rearranges those files.
## When to use
- User explicitly asks: set up / init / migrate / create wiki.
- `using-wiki` runs and detects a missing or non-canonical `.wiki/` — its Prerequisites delegate here.
- `project-bootstrap` Step 3 delegates here when initializing a new project.
## Out of scope
- Editing existing wiki *content* (that's `using-wiki`'s job).
- Anything outside `.wiki/`.
## Hard rule: don't auto-mutate
The procedure mutates the project's `.wiki/`. **Pause for explicit confirmation between Phase 1 (discovery) and Phase 2 (plan).** A trigger phrase is permission to inspect, not to write.
## Procedure
### Phase 0 — Environment sanity
- Confirm current working directory is a project root (has `.git/` ideally, or at minimum is a place the user wants a wiki).
- Detect platform; pick file paths accordingly. Wiki paths are POSIX-style (`.wiki/...`) on every OS.
### Phase 1 — Discovery
Inspect `.wiki/`:
- **No `.wiki/`** → mode = `greenfield`.
- **`.wiki/` exists AND has all of:** `CLAUDE.md`, `index.md`, `log.md`, `overview.md`, `raw/README.md`, plus directories `entities/`, `concepts/`, `packages/`, `sources/` → mode = `noop` (already canon; report and exit).
- **`.wiki/` exists but missing some canon files OR has non-canon files** (`SUMMARY.md`, `WORKFLOW.md`, `source/`) → mode = `migrate`.
Report findings to the user as a short summary:
```
Mode: greenfield | noop | migrate
Has: <list of canon files present>
Missing: <list>
Non-canon: <list>
```
### Phase 2 — Plan + confirm
Show the plan in one block:
**Greenfield:**
```
Will create .wiki/ with canonical layout:
CLAUDE.md (schema), index.md, log.md, overview.md
raw/README.md
entities/, concepts/, packages/, sources/ (with .gitkeep)
```
**Migrate:**
```
Will rename:
source/*.md → concepts/*.md (via git mv when in a git repo, plain mv otherwise)
Will create:
CLAUDE.md, index.md, log.md, overview.md, raw/README.md
entities/, packages/, sources/ (with .gitkeep)
Will delete:
SUMMARY.md, WORKFLOW.md, raw/.gitkeep, source/ (after moves)
Will not touch existing files in raw/ — they're immutable sources.
```
Wait for explicit confirmation ("ok", "go", "поехали"). Anything else → stop.
### Phase 3 — Backup (migrate only)
In migrate mode only, copy each file we will rename/delete to `.wiki/.backup-YYYYMMDD-HHMMSS/`. (Greenfield has nothing to back up.)
If git is available, the rename history is also recoverable via `git reflog`, but a filesystem backup is belt-and-suspenders.
### Phase 4a — Greenfield create
Create the canonical layout. Each file gets the content shown below; the project name comes from the parent directory's basename.
**`.wiki/CLAUDE.md`** (schema):
```markdown
# Wiki Schema — <project>
Project-specific wiki conventions. Read this before any wiki operation.
This wiki follows Karpathy's LLM Wiki pattern:
**https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f**
The `using-wiki` skill enforces the workflow and file formats. This file overrides the skill where they conflict.
## Page types
- `entities/` — discrete things this project tracks (people, services, modules).
- `concepts/` — recurring ideas, design decisions, gotchas.
- `packages/` — code packages this project produces or consumes.
- `sources/` — one summary page per ingested external doc; carries `ingested:` and `raw_path:`.
- `overview.md` — single project-wide overview.
## Naming
- `kebab-case.md`, **Latin only**. Transliterate Cyrillic in filenames; keep the original title in the H1 + frontmatter.
## Domain conventions
<!-- Fill in as the project takes shape — what counts as an entity here, which packages exist, naming idioms specific to this codebase. -->
```
**`.wiki/index.md`** (catalog):
```markdown
# Wiki Index
Catalog of all wiki pages. One line per page, organized by type. Updated on every ingest / new page.
## Overview
- [overview.md](overview.md) — project overview
## Entities
<!-- (none yet) -->
## Concepts
<!-- (none yet) -->
## Packages
<!-- (none yet) -->
## Sources
<!-- (none yet) -->
```
**`.wiki/log.md`** (op log; backfill an `init` line dated today):
```markdown
# Wiki Log
Append-only operation log. Format:
\`\`\`
## [YYYY-MM-DD] <op> | <one-line description>
\`\`\`
Operations: `init`, `ingest`, `query`, `lint`, `refactor`, `decision`.
Parseable: `grep "^## \[" .wiki/log.md | tail -20`.
---
## [<today>] init | wiki bootstrapped via setup-wiki@<version>
```
**`.wiki/overview.md`**:
```markdown
---
title: <project> overview
type: overview
updated: <today>
---
# <project> — overview
<!-- Replace with a high-level description: what this project does, who it's for, the main components. -->
```
**`.wiki/raw/README.md`**:
```markdown
# Raw Sources
**Immutable.** Read, never edit. The only allowed modification is appending a `> Status:` blockquote when the user explicitly asks for a status audit.
Place raw inputs here — articles, transcripts, PDFs, screenshots — exactly as they came in. The agent reads from `raw/`, writes summaries into `../sources/`, and never modifies raw files.
For large or path-sensitive sources outside the repo, register them here:
\`\`\`
- short-name → /absolute/path/to/source
\`\`\`
```
**Empty `.gitkeep`** in each of `entities/`, `concepts/`, `packages/`, `sources/` so git tracks the dirs.
### Phase 4b — Migrate
If migrate mode: combine creation (for missing canon files) with file moves (for non-canon).
```bash
# 1. Create missing directories
mkdir -p .wiki/concepts .wiki/entities .wiki/packages .wiki/sources
# 2. Move source/* → concepts/* (use git mv if in a git repo)
if git rev-parse --git-dir >/dev/null 2>&1; then
for f in .wiki/source/*.md; do
[ -e "$f" ] && git mv "$f" ".wiki/concepts/$(basename "$f")"
done
git rm -f .wiki/SUMMARY.md .wiki/WORKFLOW.md .wiki/source/.gitkeep .wiki/raw/.gitkeep 2>/dev/null
else
mv .wiki/source/*.md .wiki/concepts/ 2>/dev/null
rm -f .wiki/SUMMARY.md .wiki/WORKFLOW.md .wiki/source/.gitkeep .wiki/raw/.gitkeep
fi
rmdir .wiki/source 2>/dev/null
# 3. Create missing canon files (CLAUDE.md, index.md, log.md, overview.md, raw/README.md)
# using the templates from Phase 4a, but skip files that already exist.
# 4. Add .gitkeep to entities/, packages/, sources/
touch .wiki/entities/.gitkeep .wiki/packages/.gitkeep .wiki/sources/.gitkeep
```
For migrated `concepts/*.md` pages, **do not rewrite their content** — just prepend a minimal frontmatter if missing:
```yaml
---
title: <derived from existing H1>
type: concept
updated: <today>
---
```
Build `index.md` with one entry per migrated `concepts/<file>.md`, derived from the file's H1 and any one-liner the agent can extract.
Append a line to `log.md`:
```
## [<today>] refactor | wiki migrated to canon via setup-wiki@<version>
```
### Phase 5 — Verify
After writes, confirm:
- All canon files exist: `CLAUDE.md`, `index.md`, `log.md`, `overview.md`, `raw/README.md`.
- Four content directories exist (with at least `.gitkeep` or content).
- No leftover non-canon files (`SUMMARY.md`, `WORKFLOW.md`, `source/`).
- For migrate mode: every migrated page has frontmatter with `type: concept`.
If anything's off — restore from `.wiki/.backup-*` and report.
### Phase 6 — Report
Print final state:
```
✅ Wiki ready at .wiki/.
Mode: greenfield | migrate
Files: 5 canon + 4 dirs + N migrated concept pages
Backup (if migrate): .wiki/.backup-<ts>/
Next steps for the user:
• Edit .wiki/overview.md to describe the project
• Edit .wiki/CLAUDE.md "Domain conventions" with project-specific rules
• Read using-wiki SKILL.md if unfamiliar with the workflow
```
If invoked from `project-bootstrap`, return control silently — bootstrap continues with its remaining steps.
## Rollback
1. `rm -rf .wiki/` (greenfield rollback) OR `cp -r .wiki/.backup-<ts>/* .wiki/` (migrate rollback).
2. If a git repo, `git reset HEAD .wiki/` to unstage moves.
3. Tell user what failed.
## Common mistakes
- **Touching `raw/` content during migration.** `raw/` is immutable — only the `.gitkeep` placeholder may be removed (and that only because `raw/README.md` replaces it).
- **Skipping confirmation on greenfield.** Yes, even greenfield needs the gate — the user might be running this skill in the wrong directory.
- **Re-running on already-canon wiki and rewriting files.** Phase 1 detection guards this; bail out at `noop` mode.
- **Inventing project-specific Domain conventions in `CLAUDE.md`.** The schema's "Domain conventions" section is intentionally a stub — let the user fill it as they accumulate domain knowledge.
## Cross-platform notes
The procedure is platform-agnostic. `mkdir -p`, `mv`, `git mv`, `cp -r`, `rm -rf`, `touch` work in git-bash on Windows the same as on Linux/macOS. Wiki paths use forward slashes throughout.

179
dist-hermes/research/using-wiki/README.md Normal file
View File

@@ -0,0 +1,179 @@
# using-wiki
Runtime policy for an LLM Wiki built on the
[Karpathy LLM Wiki 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 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`](../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`](../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
```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 / 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`.
### `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`](../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`](../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
bash scripts/install.sh using-wiki
```
Works on Windows under git-bash, Linux, macOS.
## See also
- [`setup-wiki`](../setup-wiki/) — companion, owns `.wiki/` creation and
canon migration.
- [`project-bootstrap`](../project-bootstrap/) — invokes `setup-wiki` for
new projects.
- Karpathy's LLM Wiki gist:
<https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f>

134
dist-hermes/research/using-wiki/SKILL.md Normal file
View File

@@ -0,0 +1,134 @@
---
name: using-wiki
version: 1.0.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 four content directories `entities/`, `concepts/`, `packages/`, `sources/`.
If `.wiki/` is **missing**, or the layout is **non-canonical** (e.g. `SUMMARY.md` instead of `index.md`, or `source/` instead of `concepts/`/`sources/`) — 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 | 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 / 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.