Karpathy Wiki Capture

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).