docs: add English READMEs for setup-wiki, setup-tasks, using-wiki, using-tasks
Each README mirrors the structure of the project-bootstrap one (title, when-it-triggers, behavior, hard rules, install, see-also). The four skills cross-link as setup ↔ using companion pairs and back to project-bootstrap. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
179
skills/using-wiki/README.md
Normal file
179
skills/using-wiki/README.md
Normal 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>
|
||||
Reference in New Issue
Block a user