feat: migrate 12 personal skills + add build/install scripts
- skills/: editable sources for all 12 personal skills (caveman family, find-skills, project-bootstrap, task-status-wiki, using-context7, using-markitdown, wiki-maintainer, compress) - dist/: built .skill archives, committed (cross-machine deploy without needing zip on the target) - scripts/build.sh + build.ps1: zip skills/<name>/ into dist/<name>.skill; Windows fallback uses .NET ZipArchive (PS 5.1 Compress-Archive writes backslashes that break extraction on *nix) - scripts/install.sh: copy skills/<name>/ into ~/.claude/skills/<name>/ ($CLAUDE_SKILLS_DIR overrides target) - .wiki/source/repo-layout.md, build-notes.md: design + gotchas - .gitignore: keep dist/ tracked Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
127
skills/wiki-maintainer/SKILL.md
Normal file
127
skills/wiki-maintainer/SKILL.md
Normal file
@@ -0,0 +1,127 @@
|
||||
---
|
||||
name: wiki-maintainer
|
||||
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.
|
||||
Reference in New Issue
Block a user