Second Brain

/second-brain — Karpathy LLM Wiki workflow

Wraps an existing Second Brain in Obsidian (or any markdown-based vault). The wiki vault's schema doc (CLAUDE.md or AGENTS.md) is the authoritative schema — the skill orchestrates the operations the user has been doing manually.

Mental model

Three layers, each with a clear role:

raw/      →  wiki/         →  outputs/
sources      compiled         generated
                              artifacts

• raw/ — unprocessed source material. Articles, highlights, ideas, braindumps, tweets. Type-prefixed (article-, idea-, highlights-, braindump-, note-, resource-, tweet-). Never deleted — source of truth.
• wiki/ — AI-compiled topic pages. One page per concept, not per source. Interlinked via [[wikilinks]]. INDEX.md at root.
• outputs/ — generated artifacts from queries: research summaries, analyses, slide decks. Named descriptively.

Folders to leave alone during wiki ops: Projects/, Daily/, Templates/, Inbox/, Notes/, Tasks.md, Kanban.md, Home.md.

Step 1 — Load vault config + schema

1. Read references/vault-config.md for the vault path (default: ${SECOND_BRAIN_VAULT:-$HOME/Documents/SecondBrain}/)
2. Read the vault's schema doc — <vault>/CLAUDE.md or <vault>/AGENTS.md, whichever exists (if both, read both) — for the authoritative schema. If present, trust it over references/schema.md — the user's vault is the source of truth.
3. If neither exists, fall back to references/schema.md.

Step 2 — Parse mode

Step 3 — Run the mode

capture

Inputs: URL, pasted text, file path, or screenshot.

1. Detect type from content:
   • URL → article-
   • Pasted text with quoted highlights → highlights-
   • User's own thoughts / brainstorm → braindump- or idea-
   • Single tweet / X post → tweet-
   • PDF, video, podcast → resource-
   • Quick reference (recipe, command, fact) → note-
   • If ambiguous, ask.
2. Generate a descriptive filename: <type>-<kebab-case-topic>.md (e.g., article-andrew-wilkinson-tiny-manual.md). Use the source title or topic — not the URL slug.
3. Add metadata to the top:

   source: <URL if applicable>
   captured: YYYY-MM-DD

4. Save to <vault>/raw/.
5. If the source is a URL, fetch the article content (your agent's URL fetch, or agent-browser for auth-walled pages) and save the readable text — not just the URL.
6. Report path + a one-line summary of what was saved.

Don't compile into the wiki here — capture is fast intake. Compilation is a separate, deliberate pass.

compile

The expensive but valuable operation. Process unprocessed raw files into wiki pages.

1. Find unprocessed raw files: grep wiki/*.md for Sources sections; the raw files NOT listed are unprocessed.
2. Read each unprocessed raw file + the existing wiki/INDEX.md.
3. For each raw file:
   • Extract key concepts, facts, insights
   • Default: merge into an existing wiki page if the topic overlaps. Only create a new page if the concept doesn't fit anywhere.
   • One page per concept, not per source.
   • Use [[wikilinks]] for every related concept
   • Add the raw file under the wiki page's ## Sources section with a one-line note on what was drawn from it
4. Update wiki/INDEX.md:
   • Add new pages under their category (Creative / Health & Longevity / Faith & Personal Growth / Business / Personal Growth / Tech / Hobbies / Sci-Fi / Pets — or new category if needed)
   • One line per entry: - [[Page Name]] — brief description
5. Connections section is mandatory on every wiki page. If a new page has no connections, find one before saving.
6. Quality > quantity. If a page would be <100 words, hold the raw file for now and ask the user if it should be merged into an adjacent page.

Output: list of pages created/updated, what merged where, anything held for clarification.

query

Answer a question using ONLY the wiki/raw corpus. Different from deep-research (which goes external).

1. Read wiki/INDEX.md to identify potentially relevant pages
2. Read those pages + traverse [[wikilinks]] 1–2 hops
3. Compose the answer:
   • Cite wiki pages by name: "Per [[Microplastics Detox]]..."
   • If the wiki contradicts itself, surface both sides
   • If the wiki doesn't contain the answer, say so and offer to run /deep-research to expand
4. Save to outputs/<YYYY-MM-DD>-<question-slug>.md with:
   • The original question
   • The answer
   • List of wiki pages consulted
5. Show the answer in chat + path to the saved output
6. Optional render: if --render pdf or --render html was passed, pipe the output through pandoc using the shared stylesheet. See references/schema.md → "Publishing alternatives" for the commands.

lint

Health check the wiki.

Check:

1. Orphan pages — wiki/*.md that aren't in INDEX.md
2. Connection orphans — pages with no [[wikilinks]] to other pages
3. Unprocessed raw — raw files not listed under any wiki page's Sources
4. Stale pages — most recent source >6 months old AND topic is volatile (AI, marketing, finance, health protocols)
5. Topic gaps — concepts mentioned in 3+ pages without their own dedicated page
6. Contradictions — wiki pages making opposing claims without flagging it
7. Missing connections — pages on clearly related topics with no [[wikilink]] between them (suggest /sb connect)

Output: prioritized list. Most important first (broken structure beats stale content).

connect

Find pages that should be linked but aren't.

1. Build a topic map from INDEX.md + page summaries
2. For each page, find 2–5 other pages with thematic overlap
3. Check whether each candidate is already linked
4. Suggest the missing links — and if the user approves, edit the pages to add them to their ## Connections sections

search

Quick grep across wiki/ + raw/ for a term. Return matching files with a 2-line excerpt around the match. Faster than query when the user knows what page they're looking for.