How to use Obsidian as a second brain with a Claude Code skill

The market wants to sell you an AI second brain - a new app, a new subscription, your notes living in someone else’s cloud with a chatbot bolted to the side. There is a quieter and more durable option, and you probably already own half of it. An Obsidian vault is nothing but a folder of markdown files on your own disk. Claude Code is an agent that reads and writes files on that same disk. Teach it your note-taking system once, in a skill, and it curates your knowledge the way you would - no export, no lock-in, no leaving plain text.

What is a second brain, and why does Obsidian fit it so well?

A second brain is a personal knowledge system: a trusted place outside your head where you capture ideas, organize them, distill what matters, and pull it back out when you need it. The ideas are not new - Zettelkasten built it from atomic, densely linked notes; the PARA method sorts everything into Projects, Areas, Resources, and Archives; Maps of Content stitch a topic together. What is new is having software that can actually do the filing and linking for you.

Obsidian fits because of what it refuses to do. It does not put your notes in a database or a proprietary block format. A vault is just a folder of plain .md files, linked with a simple double-bracket syntax, and Obsidian resolves the backlinks and graph from the text itself. That refusal is the whole point for AI: your knowledge already lives in the exact format an agent reads and writes natively. There is nothing to export and no API to negotiate - the notes are the interface.

What is a Claude Code skill?

A skill is a folder with a SKILL.md file inside it. The file has two parts: YAML frontmatter with a name and a description that tell the agent what the skill does and when to use it, and a markdown body that tells it how. Skills live in your personal folder at ~/.claude/skills/ or inside a project at .claude/skills/, so you can scope one to a single vault or reuse it everywhere.

The clever part is progressive disclosure. At rest, only each skill’s name and description sit in context - about a hundred tokens - so the agent knows the skill exists and roughly when it applies. The moment a task matches, it reads the full SKILL.md; any bundled scripts or reference files load only when they are actually needed. The practical effect is that a skill is reusable know-how. You write your conventions down once and the agent applies them every session, instead of you re-explaining how your vault works each time. A prompt is a one-off instruction; a skill is a habit the agent keeps.

Why pair Obsidian with Claude Code instead of an AI notes app?

Two reasons, and they are the reasons that last. The first is ownership: your knowledge stays as open markdown you control, not rows in a vendor’s database you rent access to. The second is that the intelligence comes to the data instead of the other way around. Claude Code runs on your machine and works on the vault in place, so it can make multi-step edits across dozens of files in a single pass - file a note, link it to five others, update the topic index, fix a broken link - which a chat sidebar simply cannot do. The skill is where your system lives, so all of that happens your way.

How do you set it up?

Setup is three steps and an optional fourth.

1. Open your vault as the working directory. Run Claude Code from inside the vault folder so the agent’s filesystem is your notes - it can see and edit every .md file, and nothing outside it.
2. Create the skill. Add a SKILL.md at .claude/skills/second-brain/ to scope it to this vault, or at ~/.claude/skills/second-brain/ to reuse it across every vault you keep.
3. Write your conventions into it. The frontmatter says when to use the skill; the body captures your folder map, your note template and frontmatter, your linking rules, and your tag taxonomy.
4. Optionally bundle helper scripts. A small script that lists orphan notes or scaffolds a daily note lets the deterministic chores run as code rather than the model improvising - faster and identical every time.

The skill itself is short. Here is a working starting point you can adapt to your own system:

---
name: second-brain
description: Capture, file, link, and review notes in this Obsidian vault. Use when the user adds a note, asks to organize the vault, wants related notes linked, or asks what they already know about a topic.
---

# Second brain

This vault follows PARA. Every note is atomic - one idea per file.

## Folders
- 0-inbox/     unsorted captures; always triage out of here
- 1-projects/  active, deadline-bound work
- 2-areas/     ongoing responsibilities
- 3-resources/ reference and topic notes, plus Maps of Content
- 4-archive/   inactive

## Note template
Every new note opens with frontmatter, then the body:
---
title:
created:
tags: []
---

## Rules
- Move new captures out of 0-inbox/ into the right folder, then remove the inbox copy.
- Link generously: add [[wikilinks]] to every related note that already exists.
- Keep one Map of Content per topic in 3-resources/ and add new notes to it.
- Use lowercase-hyphen tags; reuse a close existing tag instead of inventing one.
- Never overwrite my words in a source note - summarize into a new atomic note and link back.

Run Claude Code, ask it to file a stray thought or link a topic, then open Obsidian - the new files, wikilinks, and graph are simply there. Obsidian never needed to be running; the agent was editing the same markdown the app reads.

What can the agent actually do for your vault?

Once the skill is in place, the vault stops being a passive pile of files and starts being maintained. The jobs that used to decay because they were tedious now happen on request:

• Capture and file. Paste a messy dump of thoughts and the agent splits it into atomic notes, adds frontmatter, files each one into the right folder, and clears your inbox.
• Link. It reads your existing notes and adds [[wikilinks]] in both directions, so Obsidian’s backlinks and graph fill in instead of staying empty.
• Build maps of content. It creates or updates a topic index note that ties a cluster of related notes together, so a subject has a front door.
• Run daily and weekly reviews. It scaffolds today’s note and rolls a week of notes into a review - open threads, decisions made, loose ends to close.
• Keep things tidy. It normalizes tags, merges near-duplicates, and surfaces orphan notes and broken [[links]] before they rot.
• Retrieve and synthesize. Ask what you already know about a topic and it reads across the vault and answers with links back to the source notes - personal, cited retrieval over your own writing.

That last one is worth sitting with. A well-linked vault plus an agent that can read it is, in effect, retrieval over your own life - the same pattern production teams build for company knowledge, pointed at yours instead.

What stays local, and what leaves your machine?

This is where honesty matters more than enthusiasm. Your vault is local files, and Claude Code does not sync or upload the whole thing anywhere - it is a command-line tool operating on your disk. But to actually reason over a note, the agent sends that note’s content to Anthropic’s API as context, exactly like any other Claude request. So the accurate framing is local storage, cloud inference.

That has practical consequences. Scope the agent to the notes a task needs rather than turning it loose on the entire vault. Keep genuinely sensitive material - credentials, private client data, anything you would not paste into a chat - in a separate vault the skill never touches. And remember that standard API data handling applies; skills are not covered by zero-data-retention arrangements. What never changes is ownership: the files are yours, in plain markdown, whether or not you ever run the agent again.

Where does this beat, and not beat, a plugin or a notes app?

It wins on ownership, on customization - your whole system is a text file you can rewrite - and on doing real work: multi-file restructuring, pulling live web research into a note, and scheduled maintenance that tidies the vault on its own. It does not win everywhere. An in-app plugin like Obsidian Copilot or Smart Connections gives you inline chat and semantic search while you type, which an external agent cannot. A polished notes app gives you frictionless mobile capture and a GUI for people who would rather not open a terminal. The honest answer is that many people run both - a plugin for search inside the app, Claude Code for the heavy lifting. Different tool, same vault.

When should you reach for this?

Reach for it if you already live in Obsidian and a terminal, you want your own conventions enforced the same way every time, and you care about owning your knowledge in open files. Skip it if what you actually want is a zero-setup, mobile-first app and you are happy to trade ownership for polish.

The deeper point outlasts the notes vault. A skill is just your workflow written down in a form an agent can execute reliably - and that idea scales far past personal knowledge management. Encoding how a founder or a team actually works into dependable agent skills and systems is the work we do at Sentient Arc; a second brain is simply the smallest, most personal version of it, and a good place to feel the pattern before you trust it with anything bigger.