version: "1.0.2" name: karpathy-wiki-capture description: | Capture-authoring protocol for the main agent. Read on demand when a TRIGGER fires (per using-karpathy-wiki/SKILL.md). Defines how to format a capture, how to invoke bin/wiki capture, body-size floors, and the subagent-report workflow.

karpathy-wiki capture

You loaded this skill because a TRIGGER fired (per the loader). Your job is to write a capture file (or move a file into inbox/ for raw-direct ingest), then return to the user's task.

Single capture entry point

All chat-driven captures go through ONE command:

echo "$BODY" | bin/wiki capture \
  --title "<one-line title>" \
  --kind chat-only \
  --suggested-action create|update|augment

For chat-attached (a real file accompanies the conversation), pass the absolute path of that file via --evidence-path:

echo "$BODY" | bin/wiki capture \
  --title "<one-line title>" \
  --kind chat-attached \
  --suggested-action create|update|augment \
  --evidence-path /absolute/path/to/source/file.ext

Or for long bodies:

bin/wiki capture \
  --title "<one-line title>" \
  --kind chat-only \
  --suggested-action create \
  --body-file /tmp/body.md

--evidence-path is REQUIRED for --kind chat-attached and --kind raw-direct, REJECTED for --kind chat-only. The path lands verbatim in the capture's evidence: frontmatter and propagates to the manifest's origin field — the iron-rule contract that lets the ingester trace every wiki page back to its source.

bin/wiki capture handles wiki resolution (which wiki the capture goes to), prompts the user for setup if needed, writes every capture file, and asks the bounded dispatcher to drain the target queue. You do NOT write to .wiki-pending/ directly or launch a provider yourself.

Trigger

Triggers are listed in the loader (using-karpathy-wiki/SKILL.md). This skill assumes a trigger has fired and you're now writing.

Capture file format

See references/capture-schema.md for the canonical frontmatter schema. Key fields you set when invoking bin/wiki capture:

• --title: one-line title (becomes filename slug + capture title).
• --kind: chat-only (no file evidence) | chat-attached (file +

conversation delta) | raw-direct (you do NOT write this; it's for drop-zone ingestion).

• --suggested-action: create (new page) | update (replace

existing) | augment (add to existing).

The body is read from stdin OR --body-file <path>.

Body sufficiency

Per references/capture-schema.md:

A chat-only body must clear 1500 bytes with content, not filler. Required:

• Every durable CLAIM — fact, number, version, commit, percentage, decision.
• Every CONCRETE DETAIL the ingester cannot guess — exact URLs, package names, error messages, command snippets, code examples (5-15 lines), numeric thresholds, version ranges.
• Every DECISION made WITH its rationale — "we chose X because Y failed on Z" is a complete unit. "we chose X" alone is not.
• Every CONTRADICTION, GOTCHA, OR CAVEAT observed.
• SOURCES — doc URLs, arxiv IDs, GitHub repos with star counts as-of the session.

NOT in the body:

• Pleasantries, meta-commentary, "let me check", "good question".
• Process over output: wrong turns, reasoning trail, "I thought X but then Y". Keep the resolution; drop the detour.
• The user's questions verbatim — they're context, not content. Capture the ANSWER, not the question.

If the ingester rejects your capture (needs_more_detail: true), expand the re-queued body in place, remove both needs_more_detail and needs_more_detail_reason from frontmatter, and run wiki tick <wiki> --source manual. Marked captures remain durable but are not automatically retried. Do NOT ignore the rejection.

Subagent reports — DO NOT write a capture body

When a research subagent returns a file with durable findings, the report IS the capture. Move the file to <wiki>/inbox/:

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

wiki ingest-now triggers the same drift-scan + drain that SessionStart runs, but on demand. Use this when the user is still in the active session and wants the report ingested before they close the terminal.

Subagent-report bodies frequently exceed several KB; rewriting them as a chat-only capture body wastes tokens AND produces an inferior wiki page (the body summarizes what the file already says).

Mode change

If the user asks to change the wiki mode for this directory:

wiki use project    # captures go to ./wiki/ only
wiki use main       # captures go to ~/wiki/ only
wiki use both       # capture locally; selectively promote reusable knowledge

Confirm in one line. The mode is persisted in <cwd>/.wiki-config (project or both) or <cwd>/.wiki-mode (main-only). See references/capture-schema.md and the v2.4 spec for details.

both is project-first. The original capture is written only to ./wiki/. During ingest, the project ingester keeps project-specific knowledge local and uses the deterministic promotion helper only for reusable cross-project knowledge. The original capture is never copied verbatim to both queues.

Cwd unconfigured (0.2.9)

If bin/wiki capture aborts with stderr containing cwd unconfigured

• a wiki use project|main|both nudge, the cwd has no .wiki-config

or .wiki-mode. The body is preserved at the orphan path printed in the same stderr. Do NOT silently re-route or auto-pick — surface the choice to the user verbatim:

"This directory isn't configured for the wiki yet. Should this

capture go to: (a) a project wiki at ./wiki/ (scoped to this

repo), (b) the main wiki at ~/wiki/ (cross-project), or (c) both?"

After the user picks, run wiki use project|main|both and re-capture either by re-piping the body or by passing the orphan path:

bin/wiki capture --title "..." --kind chat-only \
  --suggested-action create --body-file <orphan-path>

Pre-0.2.9 the CLI silently auto-selected main-only and wrote <cwd>/.wiki-mode, stealing the choice from the user. The new abort makes the choice explicit.

Order matters: reply first, then capture

Reply to the user FIRST. The user is waiting; capture mechanics are not. After your reply emits, write any captures whose triggers fired (via bin/wiki capture).

Durable handoff before you stop

Each required bin/wiki capture command must return success before the foreground turn ends. Once it succeeds, the durable queue belongs to the scheduler and detached worker. Do not wait for .wiki-pending/ to drain and do not ingest queued work from the foreground session.

If the capture command fails, handle or surface that error before stopping. An empty queue cannot prove that no capture trigger was missed, so queue state is not a valid foreground turn-closure gate.

What's NOT in this skill

• The ingester's behavior (orientation, page format, manifest

protocol). That lives in karpathy-wiki-ingest/SKILL.md and is loaded by the detached runtime ingester only. The main agent never reads it.

• Iron laws and announce-line contract. Those live in the loader

(using-karpathy-wiki/SKILL.md) — single source of truth.