write-wiki: Add to and Maintain the Knowledge Base
Step 0: Orient
Read ~/.claude/CLAUDE.md and find the ## Wikis section.
This tells you every known wiki and its path.
Also check for ./knowledgebase/index.md in the current working directory.
Step 1: Does a wiki exist for this context?
If yes: proceed to Step 2 with the matching wiki path.
If no wiki exists for the current project:
Ask the user once:
No wiki found for this project. Create one?
[1] General Knowledge: adds to the GK wiki named in the Wikis registry in ~/.claude/CLAUDE.md (reusable patterns across engagements)
[2] Project-specific: creates ./knowledgebase/ inside this project folder
Then bootstrap based on their choice (see Bootstrap section below) and proceed.
Step 2: Determine the operation
Infer from context; don't ask unless truly unclear.
| Intent |
Operation |
| User drops a URL, file, or paste of content |
ingest |
| User says "update", "add a page", "save this" |
ingest or update |
| User says "lint", "clean up", "audit" |
lint |
| User says "save this answer" after a read-wiki session |
ingest (save synthesis as a new wiki page) |
Operation: ingest
A new source arrives (URL, file, paste, meeting notes, runbook, design doc).
Save to raw/. Fetch the URL with WebFetch if needed; a YouTube URL goes through the watch skill for its transcript first. Save as raw/<slug>.md with a header block:
title: <title>
source: <url or "direct input">
date: <YYYY-MM-DD>
captured: <how>
Raw files are immutable. Never edit after saving.
Surface takeaways. Read the source. Tell the user the key points and which existing wiki pages it touches. Keep this brief; it is their curation moment.
Write a source summary page at wiki/<slug>.md: what it is, key claims, notable quotes with locations, [[links]] to entities and concepts it mentions.
Update touched pages. A single source typically touches 10-15 pages. For each relevant entity or concept page: strengthen, revise, or flag contradictions. Create new pages for important entities that don't have one yet. This integration step is the whole point. Do not skip it.
Update index.md. Add new pages (one line each, under the right section). Update changed entries.
Append to log.md:
## [YYYY-MM-DD] ingest | <Source title>
<one-line note of what changed, pages touched>
Operation: update
User wants to add a page, revise an existing one, or record operational knowledge (runbooks, decisions, configurations).
- Write or update the relevant
wiki/ page directly.
- Update
index.md if a new page was created.
- Append to
log.md.
Operation: lint
Health-check the wiki. Scan for and fix/report:
- Contradictions between pages
- Stale claims newer sources have superseded
- Orphan pages with no inbound
[[links]]
- Missing pages for concepts mentioned often but lacking their own page
- Missing cross-references between pages that should link
- Data gaps worth a web search to fill
Fix safe issues directly. Propose wholesale rewrites before acting. Append lint summary to log.md.
Bootstrap: creating a new wiki
Option 1: General Knowledge (path from the Wikis registry in ~/.claude/CLAUDE.md)
The GK wiki already exists. Its entry in the ## Wikis section of ~/.claude/CLAUDE.md must name
the wiki's actual index.md path. If the registry has no General Knowledge entry yet, ask the user
for that path once, then add:
- General Knowledge: `<absolute path to the GK wiki>\index.md` - reusable patterns across engagements
Then proceed with the ingest/update operation.
Option 2: Project-specific (./knowledgebase/)
Create the folder structure:
./knowledgebase/
CLAUDE.md <- vault config (sections, conventions)
index.md <- empty catalog with section headers
log.md <- bootstrap entry
raw/
wiki/
Seed knowledgebase/CLAUDE.md with project name, owner, focus, and section headers.
Default sections: Concepts, Entities, Topics, Sources, Implementation.
Make sure a fresh session reads the index. First check ~/.claude/settings.json for a
SessionStart hook that injects wiki indexes; if one is present, skip this step (harness-interview
says not to duplicate it). Otherwise update the project root CLAUDE.md (create it if
missing) with:
At session start, read ./knowledgebase/index.md for this project's accumulated knowledge.
Add an entry to the ## Wikis section in ~/.claude/CLAUDE.md:
- <Project Name>: `<absolute path>\knowledgebase\index.md` - <one-line description>
Append to knowledgebase/log.md:
## [YYYY-MM-DD] bootstrap | Wiki created
Project-specific wiki initialized. 0 pages.
The global SessionStart hook auto-injects this project's index.md from now on: it self-activates on any
folder that has ./knowledgebase/index.md, so no per-project hook wiring is needed.
Then proceed with the operation that triggered the bootstrap.
Principles (from Karpathy's design, honor them)
- Lazy, not eager. Don't mass-summarize. Grow where the user actually works.
- User curates, you maintain. They choose sources and ask questions. You do the bookkeeping.
- Cheap index, lazy drill-down. index.md stays small (one line per page).
- Plain markdown, Obsidian-compatible.
[[Wikilinks]] everywhere. No vector DB.
- Auto-write. Make edits directly. User's safety net is git diff. Confirm before deleting a page wholesale.
1---2name: write-wiki3description: Add to, update, or health-check a knowledge base wiki. Use when the user wants to ingest a new source (article, PDF, URL, meeting notes, runbook, design doc), update existing pages, lint the wiki for stale or orphaned content, or save a synthesis back to the wiki. Also the entry point for creating a new wiki: if no wiki exists for the current project, write-wiki asks whether to create a General Knowledge wiki (path from the Wikis registry in ~/.claude/CLAUDE.md) or a project-specific one (inside the current folder). Triggers on /write-wiki, /wiki, "add this to the wiki", "ingest this", "save this to the wiki", "update the wiki", "lint the wiki", "file this", "remember this source".4---56# write-wiki: Add to and Maintain the Knowledge Base78## Step 0: Orient910Read `~/.claude/CLAUDE.md` and find the `## Wikis` section.11This tells you every known wiki and its path.1213Also check for `./knowledgebase/index.md` in the current working directory.1415## Step 1: Does a wiki exist for this context?1617**If yes:** proceed to Step 2 with the matching wiki path.1819**If no wiki exists for the current project:**20Ask the user once:2122> No wiki found for this project. Create one?23> [1] General Knowledge: adds to the GK wiki named in the Wikis registry in `~/.claude/CLAUDE.md` (reusable patterns across engagements)24> [2] Project-specific: creates `./knowledgebase/` inside this project folder2526Then bootstrap based on their choice (see Bootstrap section below) and proceed.2728## Step 2: Determine the operation2930Infer from context; don't ask unless truly unclear.3132| Intent | Operation |33|---|---|34| User drops a URL, file, or paste of content | **ingest** |35| User says "update", "add a page", "save this" | **ingest** or **update** |36| User says "lint", "clean up", "audit" | **lint** |37| User says "save this answer" after a read-wiki session | **ingest** (save synthesis as a new wiki page) |3839## Operation: ingest4041A new source arrives (URL, file, paste, meeting notes, runbook, design doc).42431. **Save to raw/.** Fetch the URL with WebFetch if needed; a YouTube URL goes through the `watch` skill for its transcript first. Save as `raw/<slug>.md` with a header block:44 ```45 title: <title>46 source: <url or "direct input">47 date: <YYYY-MM-DD>48 captured: <how>49 ```50 Raw files are immutable. Never edit after saving.51522. **Surface takeaways.** Read the source. Tell the user the key points and which existing wiki pages it touches. Keep this brief; it is their curation moment.53543. **Write a source summary page** at `wiki/<slug>.md`: what it is, key claims, notable quotes with locations, `[[links]]` to entities and concepts it mentions.55564. **Update touched pages.** A single source typically touches 10-15 pages. For each relevant entity or concept page: strengthen, revise, or flag contradictions. Create new pages for important entities that don't have one yet. This integration step is the whole point. Do not skip it.57585. **Update index.md.** Add new pages (one line each, under the right section). Update changed entries.59606. **Append to log.md:**61 ```62 ## [YYYY-MM-DD] ingest | <Source title>63 <one-line note of what changed, pages touched>64 ```6566## Operation: update6768User wants to add a page, revise an existing one, or record operational knowledge (runbooks, decisions, configurations).69701. Write or update the relevant `wiki/` page directly.712. Update `index.md` if a new page was created.723. Append to `log.md`.7374## Operation: lint7576Health-check the wiki. Scan for and fix/report:77- **Contradictions** between pages78- **Stale claims** newer sources have superseded79- **Orphan pages** with no inbound `[[links]]`80- **Missing pages** for concepts mentioned often but lacking their own page81- **Missing cross-references** between pages that should link82- **Data gaps** worth a web search to fill8384Fix safe issues directly. Propose wholesale rewrites before acting. Append lint summary to `log.md`.8586## Bootstrap: creating a new wiki8788### Option 1: General Knowledge (path from the Wikis registry in `~/.claude/CLAUDE.md`)8990The GK wiki already exists. Its entry in the `## Wikis` section of `~/.claude/CLAUDE.md` must name91the wiki's actual `index.md` path. If the registry has no General Knowledge entry yet, ask the user92for that path once, then add:93```94- General Knowledge: `<absolute path to the GK wiki>\index.md` - reusable patterns across engagements95```96Then proceed with the ingest/update operation.9798### Option 2: Project-specific (`./knowledgebase/`)991001. Create the folder structure:101 ```102 ./knowledgebase/103 CLAUDE.md <- vault config (sections, conventions)104 index.md <- empty catalog with section headers105 log.md <- bootstrap entry106 raw/107 wiki/108 ```1091102. Seed `knowledgebase/CLAUDE.md` with project name, owner, focus, and section headers.111 Default sections: Concepts, Entities, Topics, Sources, Implementation.1121133. Make sure a fresh session reads the index. First check `~/.claude/settings.json` for a114 `SessionStart` hook that injects wiki indexes; if one is present, skip this step (harness-interview115 says not to duplicate it). Otherwise update the **project root** `CLAUDE.md` (create it if116 missing) with:117 ```118 At session start, read ./knowledgebase/index.md for this project's accumulated knowledge.119 ```1201214. Add an entry to the `## Wikis` section in `~/.claude/CLAUDE.md`:122 ```123 - <Project Name>: `<absolute path>\knowledgebase\index.md` - <one-line description>124 ```1251265. Append to `knowledgebase/log.md`:127 ```128 ## [YYYY-MM-DD] bootstrap | Wiki created129 Project-specific wiki initialized. 0 pages.130 ```131132The global `SessionStart` hook auto-injects this project's `index.md` from now on: it self-activates on any133folder that has `./knowledgebase/index.md`, so no per-project hook wiring is needed.134135Then proceed with the operation that triggered the bootstrap.136137## Principles (from Karpathy's design, honor them)138139- **Lazy, not eager.** Don't mass-summarize. Grow where the user actually works.140- **User curates, you maintain.** They choose sources and ask questions. You do the bookkeeping.141- **Cheap index, lazy drill-down.** index.md stays small (one line per page).142- **Plain markdown, Obsidian-compatible.** `[[Wikilinks]]` everywhere. No vector DB.143- **Auto-write.** Make edits directly. User's safety net is git diff. Confirm before deleting a page wholesale.
YogirajA