Teaching your agent to use the wiki
Connecting an agent gives it the tools. It does not give it the habit.
Left to itself, a connected agent will mostly ignore the wiki — it has no reason to believe there is anything in there worth reading, and no prompt telling it to write anything back. The snippets on this page are what close that gap. They are the difference between a wiki that accumulates knowledge and one that stays empty next to a working MCP connection.
If you haven't connected yet, /connect does it in a minute; Connect Claude Code is the same by hand.
What the server teaches on its own
Two things arrive without any prompt. When a client connects, the server's
initialize reply carries a three-line contract: open a task with
wiki_getBrief; read a page with wiki_getPage and keep its version;
change it with wiki_patchPage against that version, and use
wiki_updatePage only to create a page or rewrite one. And wiki_guide
returns the full manual — paths, wikilinks, diagrams, the
read-keep-the-version-patch loop — which is why every snippet below tells the
agent to call it once. The snippet is what turns that into a habit: when to read,
when to write, and that the wiki is worth the trouble.
The loop you're encoding
Every snippet below is a variation on the same four beats:
- Orient at session start — ask for a brief, then read what it cut short
- Search before deciding — look for existing knowledge before assuming
- Write back what was learned — decisions, patterns, gotchas
- Log what happened — leave a trail of intent, not just diffs
Beat 3 is the one agents skip. Be explicit about it.
What belongs in the wiki, and what belongs in git
The most common way a wiki like this fails is that someone tries to move everything into it. Don't. Your repo is already the right home for most of what an agent needs, and it has a property WitWiki cannot match.
Git holds what is true for this branch. A CLAUDE.md, an AGENTS.md, a
file under .claude/rules/ — build commands, conventions, the shape of this
codebase. Those version with the code, branch with the code, get reviewed in
the pull request, and work offline. If a fact stops being true when you check
out a different branch, it belongs in the repo.
The wiki holds what is true across repos, people and time. The decision and the reasoning behind it. The incident and what it taught you. The thing the frontend team worked out that the backend team keeps rediscovering. Anything whose audience is wider than one repository, or whose life is longer than one branch — and anything you want attributed, versioned, and reviewable per write.
There is a practical reason for the split as well as a conceptual one. Claude
Code's own guidance is to keep a CLAUDE.md under roughly 200 lines, because
instruction files load into context every session and adherence drops as they
grow. Teams hit that ceiling. What overflows does not want to become a longer
file loaded into every session — it wants to be searchable and fetched on
demand, for the one task at hand. That is the job the wiki is for.
A rule of thumb: if you would put it in a pull request, put it in the repo. If you would say it in a code review, put it in the wiki.
CLAUDE.md snippet
Paste into your project's CLAUDE.md:
## WitWiki Knowledge Base
This project uses WitWiki as a persistent knowledge base via MCP.
### When to read
- **Task start** — call wiki_getBrief({task: "<what you are about to do>"})
first. One call returns the pages worth reading, each with its version, its
age and who wrote it last. wiki_getPage for anything it cut short, or a page
it names under more; wiki_guide once per session for the conventions;
wiki_getIndex when you want the map
- **Before deciding** — search with wiki_listPages (use the q param) for what
the brief did not cover, before asking the user or making assumptions
### When to write
- **After completing work** — record decisions, patterns, and discoveries on
the page they belong to; don't let knowledge vanish at session end
- **After significant operations** — call wiki_appendLog to record what you did
and why (ingest sessions, architectural choices, answered questions)
### Changing a page
Read it with wiki_getPage and keep the version it returns. Change it with
wiki_patchPage (base_version = that version) — this is the default: replace a
sentence, insert after a line, replace or append to a section, create one.
wiki_updatePage replaces the WHOLE page; use it only to create a page or
rewrite one, and pass expected_version. A stale version is refused with
VERSION_CONFLICT and a diff of what changed: read again and re-apply. Reconcile
contradictions explicitly rather than silently clobbering them.
### Writing conventions
- Cross-reference related pages with [[wikilinks]] — also [[path|display text]]
- Keep each page focused on a single topic
- Use lowercase hyphen-separated paths; never a .md extension
- Update the index with wiki_updateIndex when adding major new pages
- Run wiki_lint after batches of edits to surface orphans and dead links
AGENTS.md snippet
For the OpenAI Agents SDK, AutoGen, LangGraph, Codex, or a custom framework —
paste into AGENTS.md:
## WitWiki Knowledge Base
This agent has access to a WitWiki knowledge base via MCP tools. Read
accumulated knowledge before starting work; record new knowledge after.
### When to read
- At task start, call wiki_getBrief({task}) first; wiki_getPage for what it
cut short or names under more; wiki_guide once for the conventions;
wiki_getIndex for the map
- Search with wiki_listPages (q parameter) for what the brief did not cover
### When to write
- After completing a task, record what you learned on the page it belongs to
- After significant operations, append an entry with wiki_appendLog
### Changing a page
wiki_getPage first and keep its version. Change the page with wiki_patchPage
(base_version = that version). wiki_updatePage replaces the whole page — only to
create or rewrite one, with expected_version. A stale version is refused with
VERSION_CONFLICT and a diff: read again, re-apply.
### Conventions
- Link related pages with [[wikilinks]]
- One topic per page; lowercase hyphen-separated paths, no .md extension
- Run wiki_lint periodically to find dead links and orphan pages
Hooks for Claude Code
A snippet is advice, and an agent can skip advice. Claude Code hooks are not skipped: they run on every prompt whether or not the agent remembers the snippet. Run this in the root of a repository:
curl -fsSL https://witwiki.app/hooks/install.sh | bash
It adds one script, .claude/hooks/witwiki-hooks.sh, and three entries in
.claude/settings.json:
| When | What the hook does |
|---|---|
| Every prompt | Adds one line reminding the agent that the wiki exists and how to search it |
| Before the agent asks you a question | If it has not looked in the wiki this turn, sends it there first. A second try goes through, so a question the wiki cannot answer is never blocked |
| Before the agent searches the web | If it has not looked in the wiki this turn, reminds it the wiki is one of its sources. The search goes ahead |
| When a turn ends | If the agent edited files and wrote nothing to the wiki, asks it once to record what changed or say there is nothing to record |
Commit .claude/ and everyone who clones the repository gets the hooks. The
installer leaves existing hooks and settings in place, adds no second entry on a
second run, and never writes an API key. It needs jq, and so do the hooks. Every
hook fails open: if jq is missing or anything else goes wrong, the session
carries on without it.
The hooks call tools by the name mcp__witwiki__..., so the MCP server must
be named witwiki, which is what /connect sets up. To read the
script before running it, open
/hooks/install.sh and
/hooks/witwiki-hooks.sh.
The tools your agent gets
Twenty-two, across six groups. Full parameters and return shapes are in the MCP Tool Reference.
| Group | Tools |
|---|---|
| Orientation | wiki_guide, wiki_getBrief |
| Pages | wiki_getPage, wiki_patchPage, wiki_updatePage, wiki_deletePage, wiki_listPages |
| Index | wiki_getIndex, wiki_updateIndex |
| Log | wiki_appendLog, wiki_getLog |
| Health | wiki_lint, wiki_rebuildGraph |
| Sources | wiki_listSources, wiki_getSource, source_upload, wiki_deleteSource, wiki_markSourceIngested |
| Projects | project_list, project_get, project_create, project_update |
Tasks belong on a task board
Keep open work on a task board, not in a markdown table on a page. An agent reads its tickets in one short call and moves or comments on one without rewriting a page. In an organisation with boards on, the agent also gets six board tools, and that page has a line to add to your snippet.
Tips for a wiki worth reading
- Link aggressively. Every
[[wikilink]]builds the graph, and the graph is what makes the brief, the graph view, and lint useful. A page with no links in or out is nearly invisible. - One topic per page. Narrow pages are easier to update and far less likely to go stale in half their content while staying accurate in the other half.
- Keep the index honest. Agents orient from it. A stale index means agents reliably fail to find pages that exist, then write duplicates.
- Lint after batches.
wiki_lintsurfaces orphans and dead links. Fix them while you still remember the context. - Write decisions, not summaries. "We chose X over Y because Z" survives contact with the future. A restatement of what the code already says does not.
More depth on all of this in Wiki Conventions.