Claude Skill

second-brain

When you want to capture into, compile, query, lint, or connect your personal Second Brain. Wraps the Karpathy LLM Wiki schema (Obsidian or any markdown vault) — raw/ (unprocessed sources), wiki/ (AI-compiled interlinked topic pages), outputs/ (generated artifacts). Tool-agnostic

LLM Mart · 0 points · 6 views 0 listing impressions 0 install-command copies
Virus-scanned Reviewed automatically before listing.

Full trust report

Download coreyhaines31-makerskills-skills_second-brain-1868b81.zip · 10 KB
coreyhaines31/makerskills 819 67 forks MIT Updated 20d ago
Part of coreyhaines31/makerskills — 18 skills

Install

skills CLI npx skills add https://github.com/coreyhaines31/makerskills/tree/main/skills/second-brain
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install coreyhaines31-makerskills@llmmart
Git git clone https://github.com/coreyhaines31/makerskills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole coreyhaines31/makerskills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

/second-brain — Karpathy LLM Wiki workflow

Wraps an existing Second Brain in Obsidian (or any markdown-based vault). The wiki vault's CLAUDE.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 <vault>/CLAUDE.md for the authoritative schema. If present, trust it over references/schema.md — the user's vault is the source of truth.
  3. If no <vault>/CLAUDE.md, fall back to references/schema.md.

Step 2 — Parse mode

Invocation Mode
/sb capture / /second-brain capture / "capture this" / "save this to my brain" capture
/sb compile / "compile the wiki" / "process raw notes" compile
/sb query <question> / "ask my brain X" / "what does my brain say about Y" query
/sb lint / "lint the wiki" / "health check my brain" lint
/sb connect / "find connections" / "suggest wikilinks" connect
/sb search <term> / "search my notes for X" search

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 (via WebFetch or agent-browser for auth-walled) 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.

Multi-writer git sync (remote agents)

When the vault is git-backed to a hosted remote (GitHub/GitLab), the remote becomes a capture API for agents that don't have filesystem access — cloud agents, scheduled jobs, other machines. Any agent that can reach the git host's API (directly, or through an MCP integration layer like Executor) can read the wiki and capture into raw/ by committing to the default branch.

The discipline that keeps writers from diverging:

  1. Local sessions pull before writing: git pull --rebase --autostash at the start of any vault work, push after committing. Never assume local is current — a remote agent may have committed since the last session.
  2. Obsidian users: install the community Git plugin with auto-pull on an interval (~10 min) and pull-on-startup, but leave its auto-commit/auto-push off — sessions and agents own commits, which keeps history semantic instead of a stream of "vault backup" noise.
  3. Remote agents commit append-mostly: new files in raw/ with descriptive commit messages. Append-mostly writes to distinct files make conflicts rare, and rebase absorbs interleaved writers cleanly.

Verify the loop once end-to-end when setting it up: remote commit via API → local pull → file appears in the vault.

Composes with

  • deep-research — when query finds gaps in the wiki, route to deep-research to expand from external sources. Deep-research output can be captured back into raw/ for future compilation.
  • paste — capture content cleanly into raw/ (especially for terminal/CLI captures).
  • business-brainstorm — checks Portfolio of Businesses and Entrepreneurship & Startups wiki pages for relevant context before brainstorming.
  • decide — pull from Personal Philosophy / Productivity & Systems wiki for principles when scoring Q34 ("what principles are we bending"). New: a Decision Log wiki page accumulates the narrative form of decisions over time (the decide archive is the structured form; the wiki page is the story).
  • jab-hook — a Content Ideas wiki page hoppers hooks, frameworks, and stories. /jab-hook drafts pull candidates from there.
  • slide-deck — content drafted in outputs/ becomes deck source; speaker notes can reference relevant wiki pages.
  • pm — Projects/ folder in the vault is off-limits to second-brain; pm owns it. But a Workflow Docs wiki page captures operational patterns that show up across multiple projects.

Sibling implementations (reference)

Two other systems following the same raw → wiki → outputs pattern. Both are worth watching as upgrade paths.

  • Hermes' llm-wiki skill — off-the-shelf implementation of the 3-folder pattern. Pre-built workflows for compile / query / lint. Useful for comparing schema decisions.
  • Gbrain by Garry Tan — much more sophisticated. Treats the brain as a database (Postgres or PGLite) with synthesis, graph traversal, gap analysis, scheduled cron maintenance, and MCP integration. Powers a 146K-page deployment with 24K people entities. If the user's vault outgrows the markdown-only pattern, Gbrain is the upgrade direction. Borrows worth adopting today even without migrating: people-as-entities (the person- raw type + People wiki page) and scheduled maintenance (wire compile and lint to fire on a recurring schedule via the loop or compound-engineering:schedule skill).

Notes on quality

  • Quality over quantity. Fewer well-connected wiki pages beat many thin ones. Hold raw files for clarification if compilation would produce a thin page.
  • Don't flatten nuance. If two raw sources contradict, the wiki page should note the disagreement, not pick a side silently.
  • Connections section is mandatory — every wiki page must link to at least one other page.
  • Never delete raw files after compilation. They're the source of truth.
  • Never modify files in Projects/, Daily/, Templates/, Notes/, Tasks.md, Kanban.md, Home.md, or Inbox/ during second-brain operations. Those belong to other workflows.
Files (makerskills)
  • references
    • templates
      • raw.md 341 B 
        source: {URL if applicable, else omit}
captured: {YYYY-MM-DD}

# {Title or short description}

{Body — for articles: cleaned readable text. For ideas: the user's framing. For highlights: the highlights themselves. For braindumps: as-is.}

{For articles, preserve key author names, dates, and citations inline so they survive compilation.}
      • wiki.md 611 B 
        # {Topic Name}

{2–3 sentence summary. What is this topic and why does it matter?}

## Key Concepts

- **{Concept}** — {brief explanation}
- **{Concept}** — {brief explanation}

## Details

{Main content, organized by subtopic with `###` headers if needed. Cite specific sources inline: per [author], per [study], etc.}

### {Subtopic}

{...}

## Connections

- [[Related Topic]] — {how it connects in one phrase}
- [[Another Topic]] — {how it connects in one phrase}

## Sources

- `raw/{filename}.md` — {what was drawn from this source}
- `raw/{filename}.md` — {what was drawn from this source}
    • schema.md 7.3 KB 
      # Schema (fallback)

**Authoritative source: `<vault>/CLAUDE.md`.** This file is a fallback used only when the vault's CLAUDE.md is missing.

The schema below mirrors the user's vault as of 2026-06-17. Update this file only if you're seeding a new vault from scratch.

---

## Folder structure

```
raw/          → Unprocessed source material (articles, highlights, ideas, notes, images)
wiki/         → AI-compiled knowledge base (topic pages, interlinked, with INDEX.md)
  INDEX.md    → Master index of all wiki pages with brief descriptions
outputs/      → Saved Q&A results, analyses, slide decks, research summaries
Projects/     → Project-specific notes (DO NOT modify)
Daily/        → Daily notes (DO NOT modify)
Templates/    → Note templates (DO NOT modify)
Inbox/        → Quick capture (DO NOT modify — see Inbox/Quick Capture.md)
```

## raw/ — file naming

Type prefixes:

**Personal / intellectual**
- `article-` — web article, blog post, news
- `idea-` — your own idea or proposal
- `highlights-` — book/article highlights
- `braindump-` — unstructured thinking
- `note-` — quick reference
- `resource-` — non-text (PDF, video, podcast, image)
- `tweet-` — single X post or thread
- `bookmark-` — URL + a one-line "why I saved this"

**Business / operational** (agency, consulting, client work)
- `call-` — call/meeting transcript (Riverside, Zoom, Otter)
- `meeting-` — meeting notes (your own, not auto-transcripts)
- `screenshot-` — image capture with context (UI, dashboard, competitor)
- `sop-` — standard operating procedure
- `email-` — customer / sales / prospect email worth preserving
- `objection-` — sales objection heard from a prospect (with context)
- `ticket-` — support ticket pattern worth remembering
- `person-` — contact / profile note (think CRM-lite, like Gbrain's people entity)

First line of each file:
```
source: <URL if applicable, or "call with X on YYYY-MM-DD", "email from X", etc.>
captured: YYYY-MM-DD
```

## wiki/ — page format

```markdown
# Topic Name

Brief summary (2–3 sentences).

## Key Concepts
- Concept with explanation

## Details
Main content organized by subtopic.

## Connections
- [[Related Topic]] — how it connects
- [[Another Topic]] — how it connects

## Sources
- `raw/article-example.md` — what was drawn from this source
```

## wiki/INDEX.md — format

```markdown
# Wiki Index

## <Category>
- [[Page Name]] — brief one-line description

## <Another Category>
- [[Page Name]] — brief one-line description
```

Standard categories (extend as needed):
- Creative
- Health & Longevity
- Faith & Personal Growth
- Business
- Personal Growth
- Tech
- Hobbies
- Sci-Fi
- Pets
- Personal Reference

### Suggested wiki pages that compose with other makerskills

Pages whose existence makes other skills sharper:

| Wiki page | Composes with | Why |
|---|---|---|
| **Decision Log** | `decide` | Narrative version of decisions made — the `decide` skill archives one-off decisions; the wiki page is the story of how decisions stacked over time on a topic |
| **Content Ideas** | `jab-hook` | Centralized hopper of hooks, frameworks, stories — drafted posts pull from here |
| **Customer Language** | positioning + sales | Verbatim phrases from prospects/customers — used for copy, headlines, objections |
| **Offer Notes** | positioning | What's been tried, what landed, what didn't |
| **Recurring Questions** | sales, client onboarding | Questions asked >3 times across calls; pre-answered for SOP / FAQ / scripts |
| **Workflow Docs** | `pm` | Documented operational patterns — what gets done, by whom, on what cadence |
| **People** | agency, fundraising, partnerships | Contacts with context — a CRM-lite. Inspired by Gbrain's people entity. |
| **Companies** | clients, prospects | Org profiles with last touchpoint, opportunity, status |
| **Sales Objections** | sales scripts | Library of objections + best responses |
| **Sales Scripts** | sales | Templates assembled from Customer Language + Objections |

### Outputs categories

The `outputs/` folder hosts generated artifacts. Common kinds:
- Posts (social drafts, blog drafts)
- Reports
- Proposals (especially for agency work)
- SOPs (your own + client deliverables)
- Audits (typical agency deliverable)
- Research briefs (composes with `deep-research`)
- Sales scripts
- Client summaries
- Slide deck content (handed off to `slide-deck`)

## Rules

- **One page per concept** — not per source
- **Use `[[wikilinks]]`** for all internal references
- **Keep pages focused** — split if >500 words
- **INDEX.md is the root** — keep current
- **Connections section is mandatory** — every page links to ≥1 other page
- **No orphan pages**
- **Summaries are concise**
- **Preserve nuance** — don't flatten contradictions

---

## Publishing alternatives — how to render `outputs/`

When `outputs/<file>.md` should leave the vault as a polished artifact (research brief to a client, summary to share, slide-deck source, archive PDF), use one of these:

### Default: pandoc + shared stylesheet

```bash
# PDF (requires basictex: brew install --cask basictex, then once:
# sudo tlmgr update --self && sudo tlmgr install collection-fontsrecommended)
pandoc "outputs/<file>.md" \
  --css ~/.local/share/makerskills/render.css \
  --metadata title="<title>" \
  --pdf-engine=xelatex \
  -o "outputs/<file>.pdf"

# HTML (standalone, CSS inlined — drop into a static host or email as attachment)
pandoc "outputs/<file>.md" \
  --standalone \
  --embed-resources \
  --css ~/.local/share/makerskills/render.css \
  --metadata title="<title>" \
  -o "outputs/<file>.html"
```

Shared stylesheet at `~/.local/share/makerskills/render.css` — also used by `read-book`. Edit freely; system-font + max-width 720 + print-optimized.

### Heavier option: Quarto (`.qmd`)

[Quarto](https://quarto.org) is Posit's publishing system — markdown-superset with executable code blocks (Python/R/Julia), native citations + bibliography, cross-references, equations, and multi-format output (HTML, PDF, slides, ePub, books, websites).

**Worth adopting if you want any of:**
- A renderable **public-facing personal handbook / book / website** from the wiki (Quarto projects build full sites with navigation, search, themes)
- **Native citations** in research briefs (BibTeX/CSL → consistent inline + bibliography)
- **Executable analysis** inline in notes (bloodwork charts, financial models, ML experiments)
- **Cross-references** to figures / tables / sections by name (richer than positional markdown links)

**Costs:**
- Obsidian doesn't render `.qmd` natively — daily-driver editing UX degrades
- `[[wikilinks]]` are Obsidian-only; Quarto wants standard markdown links
- YAML frontmatter conventions differ from Obsidian's
- New tool (`brew install quarto`, ~500MB) + optional Python/R engines
- Learning curve (callouts, cross-ref keys, project config, `_quarto.yml`)
- Most second-brain operations (capture, compile, query) gain nothing from Quarto

**Status: skipped by default.** Pandoc + shared CSS handles 80% of publishing needs with 5% of the complexity. Revisit Quarto if/when:
1. You decide to publish the wiki as a personal handbook site, OR
2. You start writing a book using the corpus, OR
3. You add executable analysis to your notes

For everyday capture / compile / query / outputs, plain markdown + pandoc is plenty.
    • vault-config.md 1.7 KB 
      # Vault config

The Second Brain vault location and tool.

| Field | Value |
|---|---|
| **Path** | `${SECOND_BRAIN_VAULT:-$HOME/Documents/SecondBrain}/` |
| **Tool** | Obsidian (markdown-based) |
| **Schema source** | `<path>/CLAUDE.md` (authoritative — always read first) |
| **Backup** | _not configured here — assumes vault is in iCloud/Dropbox/git_ |

## Folders

| Folder | Purpose | Modifiable by `second-brain`? |
|---|---|---|
| `raw/` | Unprocessed source material | ✅ create files |
| `wiki/` | Compiled topic pages | ✅ create + update files |
| `wiki/INDEX.md` | Master index | ✅ update |
| `outputs/` | Generated artifacts (queries, slide decks, briefs) | ✅ create files |
| `Inbox/` | Quick-capture inbox | ❌ off-limits — `Quick Capture.md` is for raw thoughts before they hit `raw/` |
| `Projects/` | Project-specific notes | ❌ off-limits — `pm` skill territory |
| `Daily/` | Daily notes | ❌ off-limits |
| `Templates/` | Note templates | ❌ off-limits |
| `Notes/` | Misc | ❌ off-limits |
| `Tasks.md` | Task list | ❌ off-limits |
| `Kanban.md` | Personal kanban | ❌ off-limits — `pm` skill territory |
| `Home.md` | Vault home | ❌ off-limits |

## Switching vaults

If the user moves the vault or wants to use a different setup (Logseq, plain markdown dir, Notion):

1. Update **Path** above
2. If the tool changes, note any structural differences (e.g., Logseq uses `journals/` and `pages/`)
3. Ensure the new vault has a CLAUDE.md or schema doc the skill can read at Step 1

## Note

The skill always reads `<vault>/CLAUDE.md` at start. If the user updates their schema there, the skill picks it up automatically — no need to keep this skill's `schema.md` in sync.
  • SKILL.md 11.5 KB 
    ---
name: second-brain
description: When you want to capture into, compile, query, lint, or connect your personal Second Brain. Wraps the Karpathy LLM Wiki schema (Obsidian or any markdown vault) — raw/ (unprocessed sources), wiki/ (AI-compiled interlinked topic pages), outputs/ (generated artifacts). Tool-agnostic in design but defaults to a vault at ${SECOND_BRAIN_VAULT:-$HOME/Documents/SecondBrain}/. Six modes — capture (drop something into raw/), compile (process unprocessed raw files into wiki pages, update INDEX.md), query (answer a question from the wiki, save to outputs/), lint (orphans / contradictions / stale / unprocessed raw / topic gaps), connect (suggest new wikilinks between pages), search (quick lookup). Triggers on "/second-brain," "/sb," "capture this," "save this to my brain," "compile the wiki," "process raw notes," "query my wiki," "ask my brain," "lint the wiki," "find connections," "search my notes." Complements deep-research (external corpus) — this is the internal corpus.
metadata:
  version: 0.2.0
---

# /second-brain — Karpathy LLM Wiki workflow

Wraps an existing Second Brain in Obsidian (or any markdown-based vault). The wiki vault's CLAUDE.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 `<vault>/CLAUDE.md` for the authoritative schema. If present, trust it over `references/schema.md` — the user's vault is the source of truth.
3. If no `<vault>/CLAUDE.md`, fall back to `references/schema.md`.

## Step 2 — Parse mode

| Invocation | Mode |
|---|---|
| `/sb capture` / `/second-brain capture` / "capture this" / "save this to my brain" | **capture** |
| `/sb compile` / "compile the wiki" / "process raw notes" | **compile** |
| `/sb query <question>` / "ask my brain X" / "what does my brain say about Y" | **query** |
| `/sb lint` / "lint the wiki" / "health check my brain" | **lint** |
| `/sb connect` / "find connections" / "suggest wikilinks" | **connect** |
| `/sb search <term>` / "search my notes for X" | **search** |

## 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:**
   ```markdown
   source: <URL if applicable>
   captured: YYYY-MM-DD
   ```
4. **Save to `<vault>/raw/`**.
5. If the source is a URL, fetch the article content (via WebFetch or agent-browser for auth-walled) 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.

## Multi-writer git sync (remote agents)

When the vault is git-backed to a hosted remote (GitHub/GitLab), the remote becomes a **capture API for agents that don't have filesystem access** — cloud agents, scheduled jobs, other machines. Any agent that can reach the git host's API (directly, or through an MCP integration layer like [Executor](https://executor.sh)) can read the wiki and capture into `raw/` by committing to the default branch.

The discipline that keeps writers from diverging:

1. **Local sessions pull before writing**: `git pull --rebase --autostash` at the start of any vault work, push after committing. Never assume local is current — a remote agent may have committed since the last session.
2. **Obsidian users**: install the community **Git** plugin with auto-pull on an interval (~10 min) and pull-on-startup, but leave its auto-commit/auto-push **off** — sessions and agents own commits, which keeps history semantic instead of a stream of "vault backup" noise.
3. **Remote agents commit append-mostly**: new files in `raw/` with descriptive commit messages. Append-mostly writes to distinct files make conflicts rare, and rebase absorbs interleaved writers cleanly.

Verify the loop once end-to-end when setting it up: remote commit via API → local pull → file appears in the vault.

## Composes with

- `deep-research` — when `query` finds gaps in the wiki, route to deep-research to expand from external sources. Deep-research output can be captured back into `raw/` for future compilation.
- `paste` — capture content cleanly into `raw/` (especially for terminal/CLI captures).
- `business-brainstorm` — checks `Portfolio of Businesses` and `Entrepreneurship & Startups` wiki pages for relevant context before brainstorming.
- `decide` — pull from `Personal Philosophy` / `Productivity & Systems` wiki for principles when scoring Q34 ("what principles are we bending"). New: a `Decision Log` wiki page accumulates the narrative form of decisions over time (the `decide` archive is the structured form; the wiki page is the story).
- `jab-hook` — a `Content Ideas` wiki page hoppers hooks, frameworks, and stories. `/jab-hook` drafts pull candidates from there.
- `slide-deck` — content drafted in `outputs/` becomes deck source; speaker notes can reference relevant wiki pages.
- `pm` — Projects/ folder in the vault is off-limits to second-brain; pm owns it. But a `Workflow Docs` wiki page captures operational patterns that show up across multiple projects.

## Sibling implementations (reference)

Two other systems following the same raw → wiki → outputs pattern. Both are worth watching as upgrade paths.

- **[Hermes' `llm-wiki` skill](https://hermes.team)** — off-the-shelf implementation of the 3-folder pattern. Pre-built workflows for compile / query / lint. Useful for comparing schema decisions.
- **[Gbrain](https://github.com/garrytan/gbrain)** by Garry Tan — much more sophisticated. Treats the brain as a database (Postgres or PGLite) with synthesis, graph traversal, gap analysis, scheduled cron maintenance, and MCP integration. Powers a 146K-page deployment with 24K people entities. If the user's vault outgrows the markdown-only pattern, Gbrain is the upgrade direction. Borrows worth adopting today even without migrating: **people-as-entities** (the `person-` raw type + `People` wiki page) and **scheduled maintenance** (wire `compile` and `lint` to fire on a recurring schedule via the `loop` or `compound-engineering:schedule` skill).

## Notes on quality

- **Quality over quantity.** Fewer well-connected wiki pages beat many thin ones. Hold raw files for clarification if compilation would produce a thin page.
- **Don't flatten nuance.** If two raw sources contradict, the wiki page should note the disagreement, not pick a side silently.
- **Connections section is mandatory** — every wiki page must link to at least one other page.
- **Never delete raw files** after compilation. They're the source of truth.
- **Never modify** files in `Projects/`, `Daily/`, `Templates/`, `Notes/`, `Tasks.md`, `Kanban.md`, `Home.md`, or `Inbox/` during second-brain operations. Those belong to other workflows.

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.

Related

Claude Prompt
Tighten-my-prose editing prompt
Claude Skill
Adversarial code-review skill for Claude
Claude Workflow
Deep-research workflow (fan-out + verify)
Claude Skill
Conventional-commit writer for Claude