Second Brain: an LLM-maintained Obsidian wiki driven by four Agent Skills

The filing problem Second Brain is built around

Most personal knowledge bases fail at maintenance, not capture. Clipping an article takes seconds. Deciding where it belongs, which existing note it contradicts, and whether it deserves its own page takes minutes you will not spend at 11pm. Second Brain targets that gap directly. The README states the division of labour plainly: the LLM is the librarian, you are the curator. Your job is to drop raw material into raw/ and browse the result in Obsidian. The agent's job is to read everything, write structured wiki pages, create cross-references, and maintain an index. The intended user is someone who already keeps notes in Obsidian and already runs a coding agent such as Claude Code, Codex, Cursor, or Gemini CLI. If you use neither, the project has nothing to offer you, because the browsing surface and the execution surface are both external dependencies rather than things it ships.

The raw/ to wiki/ contract and what the agent actually writes

The mechanism is a folder contract. You put articles, papers, notes, and transcripts into raw/, with images and attachments under raw/assets/. The ingest skill reads that folder and writes into wiki/, which is subdivided by page type: sources/ holds one summary per ingested source, entities/ holds people, organisations, products and tools, concepts/ holds ideas, frameworks and theories, and synthesis/ holds comparisons, analyses and themes. Two files sit at the top of wiki/. index.md is described as the master catalog of all pages, and log.md as a chronological operation record. Browsing happens through [[wikilinks]] and Obsidian's graph view. The design choice worth noting is that page type is encoded in the directory rather than in frontmatter or tags. That makes the structure legible to an agent that only sees file paths, and it makes the lint skill's job tractable, but it also means a page that is genuinely both an entity and a concept has to be filed somewhere, and the README does not say how the agent resolves that ambiguity. Cross-references are the other half of the mechanism: the agent creates them, and /second-brain-lint is what detects them when they break.

Installing four skills with one npx command

Installation is a single command, and it depends on Node.js being present because the skills are distributed through npm:

npx skills add NicholasSpisak/second-brain

That installs four skills into the agent: /second-brain for the guided setup wizard, /second-brain-ingest for processing raw sources into wiki pages, /second-brain-query for asking questions against the wiki, and /second-brain-lint for health checks. The README claims support across Claude Code, Codex, Cursor, Gemini CLI and, in its words, 40+ other agents that implement the Agent Skills standard. Setup then runs as a wizard invoked by typing /second-brain, which walks through naming, location, domain and tooling, and generates an agent config file. The README notes that file is named CLAUDE.md in the example vault layout but varies by agent. Capture is deliberately outside the tool: the README points at the Obsidian Web Clipper browser extension and tells you to configure it to save into the vault's raw/ folder. The only in-editor configuration it specifies is Settings, Files and links, Attachment folder path set to raw/assets/, followed by "Download attachments for current file" after each clip. Optional tools are offered by the wizard rather than required: summarize for links, files and media from the CLI, qmd for local markdown search, and agent-browser for web research.

Where the design strains: raw/ is not immutable and the index drifts

The README's own FAQ is the most honest part of the project. Two entries describe failure modes the authors expect you to hit. The first is index drift: wiki/index.md can fall out of sync with the actual pages, and the remedy is to run /second-brain-lint, which checks index consistency and offers to fix mismatches. The second is link rot after renaming: /second-brain-lint scans for broken [[wikilinks]] and reports which files need updating. The recommended cadence is after every 10 ingests or monthly, whichever comes first, and before any major query or synthesis work. That cadence is itself the admission: this is not a system that stays consistent on its own. There is a third, quieter problem. The README says that if you accidentally modify a file in raw/, the wiki is unaffected because it was built from the original content, and that if you need the original back you should check your git history "if the vault is a git repo" or re-clip the source. The vault is not a git repository by default, so for most users the recovery path is re-clipping. Anyone treating raw/ as an archive should initialise git in the vault before the first ingest, not after the first mistake.

Scale, search, and the qmd dependency

The README addresses growth in one FAQ entry: the wiki is getting large and queries are slow. The answer is to install qmd with npm i -g @tobilu/qmd, at which point the query skill uses it automatically when available and gains what the README calls fast hybrid search across wiki files. This is the project's clearest architectural boundary. Up to some unspecified size, the agent reads markdown directly and the only cost is tokens. Past it, retrieval quality depends on a third-party binary that Second Brain does not vendor, version-pin, or test against. No threshold is given for when that switch becomes necessary, so the decision is left to you noticing that queries feel slow. For a vault of a few hundred pages this is unlikely to matter. For one with thousands, the search layer is doing more work than the skills are, and the skills are the part this repository actually maintains.

How this differs from an LLM wiki built on a database

The obvious alternative is a knowledge tool that stores notes in a database with typed entities and relations, such as a graph-backed note system or a retrieval system that indexes chunks into a vector store. The difference is not the model, it is the substrate. A database-backed tool can enforce a schema on write, so a malformed relation is rejected at insert time. Second Brain has no schema enforcement at all: the wiki is plain markdown, and correctness is checked after the fact by /second-brain-lint, which reports problems rather than preventing them. The trade is portability for guarantees. Every page is a text file you can read in any editor, diff in git, and move to another tool without an export step, and the entire wiki remains legible to a human without the agent running. In exchange you accept drift, broken links between lint runs, and a structure that holds only as long as the agent keeps following the same conventions. If your notes need referential integrity, this is the wrong substrate, and no amount of prompt engineering in the skills changes that.

Licence, maintenance, and what to check before committing a vault

The repository metadata supplied here does not include a licence, and no releases have been retrieved. That is a real gap for anyone planning to run this against a personal archive, because the licence determines what you may do with the code and what obligations travel with it. Nothing in this article is legal advice; the practical step is to read the LICENSE file in the repository, and if there is not one, treat the default as unresolved and ask the maintainer before depending on it. Maintenance cost is otherwise low and mostly external. The skills are Shell and markdown, so upgrading means re-running npx skills add NicholasSpisak/second-brain, and the wizard is described as idempotent, meaning re-running /second-brain will not overwrite existing files. Your recurring cost is the lint cadence the README recommends plus the token spend of ingesting and querying, which scales with vault size. Because there are no releases, there is no changelog to read before an upgrade; the only signal is the commit history on main, and the last push recorded here is 2026-04-07.

Editorial conclusion

Adopt Second Brain if you already read in Obsidian and want an agent to do the filing: the raw/ to wiki/ contract, the four skills, and the idempotent wizard mean you can start with one clipped article and no schema decisions. Do not adopt it if you need a queryable store with typed relations, or if you cannot state a licence for the code you are about to run. Verify three things first: the repository licence, which agent you will run the skills under, and whether the vault is a git repository, because the README's recovery advice for a modified raw/ file points at git history that only exists if you created it.

Official sources

1. Issues
2. NicholasSpisak/second-brain on GitHub
3. README