factory/skills/setup-wiki

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 — 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 detects a missing or non-canonical .wiki/ and delegates here via its Prerequisites section.
• 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 + six 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
├── contradictions/    ← surfaced tensions worth tracking long-term
└── open-questions/    ← unresolved questions raised during ingest/query

The six 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.

Rollback

• Greenfield: rm -rf .wiki/.
• Migrate: cp -r .wiki/.backup-<ts>/* .wiki/ and git reset HEAD .wiki/.

Install

From the repo root:

bash scripts/install.sh setup-wiki

Works on Windows under git-bash, Linux, macOS.

See also

• using-wiki — runtime policy for working with .wiki/.
• project-bootstrap — orchestrator that delegates here for new projects.
• Karpathy's LLM Wiki gist: https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f