---
name: using-karpathy-wiki
description: |
  Auto-loaded by the SessionStart hook. Defines when to capture and routes the main agent or detached ingester to the appropriate on-demand skill.
---

<SUBAGENT-STOP>
If you were dispatched as a subagent for a task unrelated to wiki capture or ingest, skip this skill. The wiki rules apply to the main agent in the conversation; subagents doing isolated work (Explore, code-reviewer, codex:rescue, etc.) do not need to capture.
</SUBAGENT-STOP>

# karpathy-wiki — loader (read once per session, applies for the whole session)

You are operating in a project that uses the karpathy-wiki plugin. Durable knowledge surfaced in this conversation must be captured to a wiki so future sessions can find it.

## Announce when you act

When you write a capture, run an ingest, or answer from the wiki, prefix your reply with one line:

> **Using the karpathy-wiki skill to [capture this / ingest pending captures / answer from wiki].**

This is the ONLY wiki-mechanics text the user sees. Do not narrate orientation, capture authoring, dispatch mechanics, or state-machine progress. Do all the wiki work silently after the announce line.

## Instruction priority

If the user's `CLAUDE.md` / `AGENTS.md` or an explicit user instruction conflicts with the rules below, follow the user. The wiki rules override the default system prompt where they conflict, but **never** override the user's direct instructions.

## Iron laws

```
NO WIKI WRITE IN THE FOREGROUND
NO PAGE EDIT WITHOUT READING THE PAGE FIRST
NO SKIPPING A CAPTURE BECAUSE "IT DOESN'T LOOK WIKI-SHAPED"
NO ANSWERING ANY USER QUESTION WITHOUT ORIENTING FIRST
```

Captures go to `<wiki>/.wiki-pending/<timestamp>-<slug>.md`. The bounded dispatcher assigns each capture to the configured provider/model profile and ingests it in the background.

## Orient before answering — the read protocol

For ANY user message that is asking a QUESTION (vs requesting a code edit, file operation, or pure command), you must orient on the wiki BEFORE drafting the answer. Pre-classifying a question as "general knowledge" or "not wiki-relevant" is the forbidden rationalization Iron Rule 4 was written to forbid.

**Cost framing.** Orientation is a once-per-session investment:

- First wiki-eligible question of the session: read `<wiki>/schema.md` and the relevant `<wiki>/<category>/_index.md` (or root `<wiki>/index.md` for cross-category questions). Two file reads, ~10-30 KB total.
- Subsequent questions in the same session: the schema and index are already in your working memory; the marginal check is a candidate-count scan against the (already-read) `_index.md`. Near-zero cost.

Load `karpathy-wiki-read/SKILL.md` for the deterministic 6-step ladder (orient → count candidates → inline-read OR subagent OR web-search → cite). Do NOT skip the load because "this question seems trivial" — the iron rule is unconditional.

**Resist-table for the read protocol** (capture-side resist-table is below, after TRIGGER):

| Rationalization | Reality |
|---|---|
| "This is general knowledge / I know this from training" | Pre-classifying questions as wiki-irrelevant is the forbidden rationalization. The wiki's scope is whatever has been captured. You don't know without checking. Orient. |
| "This question is trivial; reading two files is overkill" | Orientation is once per session. After the first orient, the marginal cost on the next question is near-zero (a re-scan of the already-read `_index.md`). The "trivial question" carve-out is the same drift that dropped the read protocol in v2.4. |
| "Pure syntax question, the wiki won't cover this" | You cannot know without checking. If `_index.md` has zero matches, the read skill's Step F handles it (web search + capture the gap). The orient itself is what proves there are no candidates. |
| "User asked me to fix a bug, not answer a question" | Code-edit requests don't trigger the read protocol; question-shaped requests do. If unsure (e.g. "why isn't this working" — could be a question OR a debug request), orient. |
| "I already oriented earlier this session, I'll skip this time" | Correct! Re-use the schema and index you already have. Run only the candidate-count check on the new question's terms. The protocol's deterministic part (Step B) is the only thing that re-runs per question. |

## TRIGGER — when to capture

Write a capture when ANY of these fire (immediate-capture triggers):

- A research subagent or research agent completes or returns a file with durable findings.
- New factual information is found (web search, doc fetch, external fact surfaced in conversation).
- Session resolves a confusion — something neither of you knew before.
- A gotcha, quirk, or non-obvious behavior in a tool is discovered.
- A pattern is validated (approaches compared, one picked, with reasons).
- An architectural decision is made with explicit rationale.
- User pastes a URL or document for study.
- `<wiki>/inbox/` or `<wiki>/raw/` has unprocessed files.
- User says "add to wiki" / "remember this" / "wiki it" / "save this".
- Two claims contradict each other.

Also TRIGGER (orientation + citation): the user asks "what do we know about X" / "how do we handle Y" / "what did we decide about Z" / "have we seen this before" — or any question the wiki might cover.

## SKIP — when not to capture

- Routine file edits, syntax lookups, one-off debugging with trivial root causes.
- Time-sensitive data that must be fetched fresh.
- Questions clearly outside any wiki's scope.

Do NOT skip based on tone or shape. "This looks like casual chat", "there's no code here", "this isn't a wiki context" are forbidden rationalizations. If new factual information appeared, capture. Tone is not the trigger.

**Resist-table for capture triggers.** When you're about to skip a capture, check these red flags. Skipped captures are invisible — the user cannot observe them, so the discipline is yours alone.

| Rationalization | Reality |
|---|---|
| "The user will remember this" | The user will not remember. That's the whole point. |
| "It's too trivial for the wiki" | If a TRIGGER fires, capture. Lint and the ingester filter noise later. |
| "I'll capture it later" | Later means never. Capture now — invocation is milliseconds. |
| "I'm in the middle of another task" | Capture is non-blocking; `bin/wiki capture` writes a file and returns. The ingester runs detached. |
| "The user didn't ask me to save this" | Triggers fire automatically. No explicit user request is required — that's the loader's contract. |
| "I don't have a memory tool available" | This skill IS the memory tool. The loader's presence is the trigger. |
| "The file is already in a good place" | Filing ≠ capturing. Location is not organization. The capture extracts the durable concept from the file's context; the file alone doesn't. |

## What to do when a trigger fires

For chat-driven captures (the conversation IS the source, or you have a file alongside the conversation): load `karpathy-wiki-capture/SKILL.md` and follow it. The capture is written via `bin/wiki capture` (a subcommand of the existing `bin/wiki` CLI).

For research subagent reports (a file is the source): the agent's job is one command, NOT a hand-written capture body:

```bash
mv <subagent-report-path> <wiki>/inbox/<basename>
wiki ingest-now <wiki>          # or wait for next SessionStart
```

For ANY user question (including "what does the wiki know about X" questions, but also any other question per Iron Rule 4): load `karpathy-wiki-read/SKILL.md` and run the deterministic 6-step ladder. Do NOT load `karpathy-wiki-ingest/SKILL.md` — that's for the detached runtime ingester only and contains write-side machinery the main agent never needs.

## Mode change

If the user asks to change the wiki mode for this directory (phrases like "use project wiki here," "main only," "switch to both," "fork to main"), run:

```bash
wiki use project|main|both
```

Confirm the change in one line; do not over-narrate.

## What's NOT in this loader

The full operational details — capture format, body-size floors, dispatch mechanics, ingester orientation, page format, manifest protocol, commit conventions — live in the on-demand skills:

- `skills/karpathy-wiki-capture/SKILL.md` — load when you are about to write a capture.
- `skills/karpathy-wiki-read/SKILL.md` — load when you are about to answer a user question (Iron Rule 4).
- `skills/karpathy-wiki-ingest/SKILL.md` — loaded by the detached ingester via its provider prompt; the main agent never reads this.
- `skills/karpathy-wiki-doctor/SKILL.md` — detached census; `wiki doctor` launches it. The main agent never reads this.

If you do not know what to do at a particular step, load the on-demand skill — do not invent.