Second Brain — Ingest

Process raw source documents into structured, interlinked wiki pages.

Identify Sources to Process

Determine which files need ingestion:

1. If the user specifies a file or files, use those
2. If the user says "process new sources" or similar, detect unprocessed files:
   • List all files in raw/ (excluding raw/assets/)
   • Read wiki/log.md and extract all previously ingested source filenames from ingest entries
   • Any file in raw/ not listed in the log is unprocessed
3. If no unprocessed files are found, tell the user

Process Each Source

For each source file, follow this workflow:

1. Read the source completely

Read the entire file. If the file contains image references, note them — read the images separately if they contain important information.

2. Discuss key takeaways with the user

Before writing anything, share the 3-5 most important takeaways from the source. Ask the user if they want to emphasize any particular aspects or skip any topics. Wait for confirmation before proceeding.

3. Create source summary page

Create a new file in wiki/sources/ named after the source (slugified). Include:

---
tags: [relevant, tags]
sources: [original-filename.md]
created: YYYY-MM-DD
updated: YYYY-MM-DD
---

# Source Title

**Source:** original-filename.md
**Date ingested:** YYYY-MM-DD
**Type:** article | paper | transcript | notes | etc.

## Summary

Structured summary of the source content.

## Key Claims

- Claim 1
- Claim 2
- ...

## Entities Mentioned

- [[Entity Name]] — brief context
- ...

## Concepts Covered

- [[Concept Name]] — brief context
- ...

4. Update entity and concept pages

For each entity (person, organization, product, tool) and concept (idea, framework, theory, pattern) mentioned in the source:

If a wiki page already exists:

• Read the existing page
• Add new information from this source
• Add the source to the sources: frontmatter list
• Update the updated: date
• Note any contradictions with existing content, citing both sources

If no wiki page exists:

• Create a new page in the appropriate subdirectory:
  • wiki/entities/ for people, organizations, products, tools
  • wiki/concepts/ for ideas, frameworks, theories, patterns
• Include YAML frontmatter with tags, sources, created, and updated fields
• Write a focused summary based on what this source says about the topic

5. Add wikilinks

Ensure all related pages link to each other using [[wikilink]] syntax. Every mention of an entity or concept that has its own page should be linked.

6. Update wiki/index.md

For each new page created, add an entry under the appropriate category header:

- [[Page Name]] — one-line summary (under 120 characters)

7. Update wiki/log.md

Append:

## [YYYY-MM-DD] ingest | Source Title
Processed source-filename.md. Created N new pages, updated M existing pages.
New entities: [[Entity1]], [[Entity2]]. New concepts: [[Concept1]].

8. Report results

Tell the user what was done:

• Pages created (with links)
• Pages updated (with what changed)
• New entities and concepts identified
• Any contradictions found with existing content

Conventions

• Source summary pages are factual only. Save interpretation and synthesis for concept and synthesis pages.
• A single source typically touches 10-15 wiki pages. This is normal and expected.
• When new information contradicts existing wiki content, update the wiki page and note the contradiction with both sources cited.
• Prefer updating existing pages over creating new ones. Only create a new page when the topic is distinct enough to warrant its own page.
• Use [[wikilinks]] for all internal references. Never use raw file paths.

What's Next

After ingesting sources, the user can:

• Ask questions with /second-brain-query to explore what was ingested
• Ingest more sources — clip another article and run /second-brain-ingest again
• Health-check with /second-brain-lint after every 10 ingests to catch gaps

Second Brain — Lint

Health-check the wiki and report issues with actionable fixes.

Audit Steps

Run all checks below, then present a consolidated report.

1. Broken wikilinks

Scan all wiki pages for [[wikilink]] references. For each link, verify the target page exists. Report any broken links.

# Find all wikilinks across wiki pages
grep -roh '\[\[[^]]*\]\]' wiki/ | sort -u

Cross-reference against actual files in wiki/.

2. Orphan pages

Find pages with no inbound links — no other page references them via [[wikilink]].

For each .md file in wiki/sources/, wiki/entities/, wiki/concepts/, wiki/synthesis/:

• Extract the page name (filename without extension)
• Search all other wiki pages for [[Page Name]]
• If no other page links to it, it's an orphan

3. Contradictions

Read pages that share entities or concepts and look for conflicting claims. Flag when:

• Two source summaries make opposing claims about the same topic
• An entity page contains information that conflicts with a source summary
• Dates, figures, or factual claims differ between pages

4. Stale claims

Cross-reference source dates with wiki content. Flag when:

• A concept page cites only old sources and newer sources exist on the same topic
• Entity information hasn't been updated despite newer sources mentioning that entity

5. Missing pages

Scan for [[wikilinks]] that point to pages that don't exist yet. These are topics the wiki mentions but hasn't given their own page. Assess whether they warrant a page.

6. Missing cross-references

Find pages that discuss the same topics but don't link to each other. Look for:

• Entity pages that mention concepts without linking them
• Concept pages that mention entities without linking them
• Source summaries that cover the same topic but don't reference each other

7. Index consistency

Verify wiki/index.md is complete and accurate:

• Every page in wiki/sources/, wiki/entities/, wiki/concepts/, wiki/synthesis/ has an index entry
• No index entries point to deleted pages
• Entries are under the correct category header

8. Data gaps

Based on the wiki's current coverage, suggest:

• Topics mentioned frequently but lacking depth
• Questions the wiki can't answer well
• Areas where a web search could fill in missing information

Report Format

Present findings grouped by severity:

Errors (must fix)

• Broken wikilinks
• Contradictions between pages
• Index entries pointing to missing pages

Warnings (should fix)

• Orphan pages with no inbound links
• Stale claims from outdated sources
• Missing pages for frequently referenced topics

Info (nice to fix)

• Potential cross-references to add
• Data gaps that could be filled
• Index entries that could be more descriptive

For each finding, include:

• What: description of the issue
• Where: the specific file(s) and line(s)
• Fix: what to do about it

After the Report

Ask the user:

"Found N errors, N warnings, and N info items. Want me to fix any of these?"

If the user agrees, fix issues and report what changed.

Log the lint pass

Append to wiki/log.md:

## [YYYY-MM-DD] lint | Health check
Found N errors, N warnings, N info items. Fixed: [list of fixes applied].

When to Lint

• After every 10 ingests — catches cross-reference gaps while they're fresh
• Monthly at minimum — catches stale claims and orphan pages over time
• Before major queries — ensures the wiki is healthy before you rely on it for analysis

Related Skills

• /second-brain-ingest — process new sources into wiki pages
• /second-brain-query — ask questions against the wiki

Second Brain — Query

Answer questions by searching and synthesizing knowledge from the wiki.

Search Strategy

1. Start with the index

Read wiki/index.md to identify relevant pages. Scan all category sections (Sources, Entities, Concepts, Synthesis) for entries related to the question.

2. Use qmd for large wikis

If qmd is installed (check with command -v qmd), use it for search:

qmd search "query terms" --path wiki/

This is especially useful when the wiki has grown beyond ~100 pages where scanning the index becomes inefficient.

3. Read relevant pages

Read the wiki pages identified by the index or search. Follow [[wikilinks]] to pull in related context from linked pages. Read enough pages to give a thorough answer, but don't read the entire wiki.

4. Check raw sources if needed

If the wiki pages don't fully answer the question, check relevant source summaries in wiki/sources/ for additional detail. Only go to files in raw/ as a last resort.

Synthesize the Answer

Format

Match the answer format to the question:

• Factual question → direct answer with citations
• Comparison → table or structured comparison
• Exploration → narrative with linked concepts
• List/catalog → bulleted list with brief descriptions

Citations

Always cite wiki pages using [[wikilink]] syntax. Example:

According to [[Source - Article Title]], the key finding was X. This connects to the broader pattern described in [[Concept Name]], which [[Entity Name]] has also explored.

Offer to save valuable answers

If the answer produces something worth keeping — a comparison, analysis, new connection, or synthesis — offer to save it:

"This comparison might be useful to keep in your wiki. Want me to save it as a synthesis page?"

If the user agrees:

1. Create a new page in wiki/synthesis/ with proper frontmatter
2. Add an entry to wiki/index.md under Synthesis
3. Append to wiki/log.md: ## [YYYY-MM-DD] query | Question summary

Conventions

• Search the wiki first. Only go to raw sources if the wiki doesn't have the answer.
• Cite your sources. Every factual claim should link to the wiki page it came from.
• Valuable answers compound. Encourage saving good analyses back into the wiki.
• Use [[wikilinks]] for all internal references. Never use raw file paths.

Related Skills

• /second-brain-ingest — process new sources into wiki pages
• /second-brain-lint — health-check the wiki for issues

Second Brain — Onboarding Wizard

Set up a new Obsidian knowledge base using the LLM Wiki pattern. The LLM acts as librarian — reading raw sources, compiling them into a structured interlinked wiki, and maintaining it over time.

Wizard Flow

Guide the user through these 5 steps. Ask ONE question at a time. Each step has a sensible default — the user can accept it or provide their own value.

Step 1: Vault Name

Ask:

"What would you like to name your knowledge base? This will be the folder name." Default: second-brain

Accept any user-provided name. This becomes the folder name and the title in the agent config.

Step 2: Vault Location

Ask:

"Where should I create it? Give me a path, or I'll use the default." Default: ~/Documents/

Accept any absolute or relative path. Resolve ~ to the user's home directory. The final vault path is {location}/{vault-name}/.

Step 3: Domain / Topic

Ask:

"What's this knowledge base about? This helps me set up relevant tags and describe the vault's purpose."

Examples: "AI research", "competitive intelligence on fintech startups", "personal health and fitness"

Accept free text. Use this to:

• Write a one-line domain description for the agent config
• Generate 5-8 suggested domain-specific tags

Step 4: Agent Config

Auto-detect which agent is running this skill. State it clearly:

"I'm running in [Agent Name], so I'll generate a [config file] for this vault."

Then ask:

"Do you use any other AI agents you'd like config files for? Options: Claude Code, Codex, Cursor, Gemini CLI — or skip."

Skip the agent that was auto-detected. Generate configs for all selected agents.

Agent detection logic:

• If the CLAUDE.md convention is being used or the Skill tool is Claude Code's → Claude Code
• If the environment indicates Codex → Codex
• If .cursor/ exists in the working directory → Cursor
• If GEMINI.md convention is being used → Gemini CLI
• If unsure, ask the user which agent they're using

Step 5: Optional CLI Tools

Ask:

"These tools extend what the LLM can do with your vault. All optional but recommended:"

1. summarize — summarize links, files, and media from the CLI
2. qmd — local search engine for your wiki (helpful as it grows)
3. agent-browser — browser automation for web research

"Install all, pick specific ones (e.g. '1 and 3'), or skip?"

Post-Wizard: Scaffold the Vault

After collecting all answers, execute these steps in order:

1. Create directory structure

Run the onboarding script, passing the full vault path:

bash <skill-directory>/scripts/onboarding.sh <vault-path>

This creates all directories and the initial wiki/index.md and wiki/log.md files.

2. Generate agent config file(s)

For each selected agent, read the corresponding template from <skill-directory>/references/agent-configs/:

For each template, replace the placeholders:

• {{VAULT_NAME}} → the vault name from Step 1
• {{DOMAIN_DESCRIPTION}} → a one-line description derived from Step 3
• {{DOMAIN_TAGS}} → generate 5-8 domain-relevant tags as a bullet list based on the domain from Step 3
• {{WIKI_SCHEMA}} → read <skill-directory>/references/wiki-schema.md and insert everything from ## Architecture onward

Write the generated config to the vault.

3. Update wiki/log.md

Append the setup entry:

## [YYYY-MM-DD] setup | Vault initialized
Created vault "{{VAULT_NAME}}" for {{DOMAIN_DESCRIPTION}}.
Agent configs: {{list of generated config files}}.

4. Install CLI tools (if selected)

For each tool the user selected in Step 5, run the install command:

• summarize: npm i -g @steipete/summarize
• qmd: npm i -g @tobilu/qmd
• agent-browser: npm i -g agent-browser && agent-browser install

After each install, verify with <tool> --version. Report success or failure for each.

5. Print summary

Show the user:

1. What was created — directory tree and config files
2. Required next step — install the Obsidian Web Clipper browser extension:

   Install the Obsidian Web Clipper to easily save web articles into your vault: https://chromewebstore.google.com/detail/obsidian-web-clipper/cnjifjpddelmedmihgijeibhnjfabmlf

3. How to start — open the vault folder in Obsidian, clip an article to raw/, then run /second-brain-ingest

Reference Files

These files are bundled with this skill and available at <skill-directory>/references/:

• wiki-schema.md — canonical wiki rules (single source of truth for all agent configs)
• tooling.md — CLI tool details, install commands, and verification steps
• agent-configs/claude-code.md — CLAUDE.md template
• agent-configs/codex.md — AGENTS.md template
• agent-configs/cursor.md — Cursor rules template
• agent-configs/gemini.md — GEMINI.md template

Next Steps

After setup is complete, the user's workflow is:

1. Clip articles to raw/ using the Obsidian Web Clipper
2. Ingest sources with /second-brain-ingest — processes raw files into wiki pages
3. Ask questions with /second-brain-query — searches and synthesizes from the wiki
4. Health-check with /second-brain-lint — run after every 10 ingests or monthly