How to Turn Obsidian Into an AI Second Brain With a Claude Code Skill

A second brain is a personal knowledge system: a place where you capture what you read, think, and decide, link those notes together, and retrieve them later when they are useful. The term comes from the personal knowledge management world, but the idea is old. The value is not in hoarding notes; it is in the connections between them, so a thought you had months ago surfaces exactly when you need it.

Obsidian is a strong home for one because it is local-first and stores everything as plain markdown files you own. There is no proprietary database and no vendor cloud in the middle: wiki-style backlinks connect notes, a graph view makes the structure visible, and the whole vault is just a folder on your disk. That last fact is the one that matters here, because a folder of files is something an agent can work with directly.

A Claude Code skill is a reusable SKILL.md file that teaches Claude Code a specific workflow. It has two parts: a short description that tells the agent what the skill does and when to use it, and a markdown body of plain-English instructions. Skills follow the open Agent Skills standard, so the same idea works across Claude's tools rather than being a one-off trick.

The mechanism that makes skills cheap to keep around is progressive disclosure. At the start of a session Claude Code loads only the names and descriptions of your skills, so it knows what is available without carrying every instruction in context; the full SKILL.md loads only when the skill is actually relevant, or when you invoke it by name with a slash command. A skill is a folder too, so it can bundle templates, examples, or reference files alongside the instructions. It is worth being precise about what a skill is not: it is not an MCP server wiring in an outside service, and it is not a plugin. It is instructions on disk that shape how the agent works.

Because the vault is just markdown files, and reading and writing files is exactly what Claude Code already does. Its built-in tools read a note, edit one in place, create new ones, and search across the whole vault by name or content. Run the agent from your vault folder and it can see and touch every note, with no integration layer in between.

What the skill adds is consistency. Left to improvise, an agent will file a note somewhere plausible, invent a heading style, and link things the way it guesses you want. A skill removes the guessing: it encodes your conventions, where daily notes live, how you name files, which frontmatter fields every note carries, how you write links, what a weekly review looks like, so the agent follows your system instead of its own. The vault stays yours; the skill just teaches the agent how you keep it.

Start by placing a SKILL.md file where Claude Code will find it: a project skill at .claude/skills/second-brain/SKILL.md inside the vault, or a personal one under your home .claude/skills/ folder if you want it available everywhere. Give it a description that names the trigger clearly, something like "capture, file, and link notes in my Obsidian vault," so the agent knows when to reach for it.

Then write the instructions as the moves you actually want, in plain language. A good starting set is small: capture a rough note and file it in the right folder, add frontmatter and a title in your format, suggest backlinks to related existing notes, and flag anything that looks like a duplicate. Run Claude Code from the vault directory so those instructions have files to act on. Keep the first version narrow and grow it as you learn what you trust the agent to do; a skill you refine over a week beats a sprawling one you wrote in an afternoon.

The everyday win is capture and filing. Paste a messy dump of thoughts, a meeting's notes, or an article's highlights, and the agent turns it into a clean note in the right place, titled and tagged to your convention, without you stopping to sort it. Multiply that across a busy week and the vault stays current instead of becoming a backlog.

The larger win is connection and recall. Because the agent can read across the whole vault, it can suggest backlinks between notes that belong together, distill a long note into a short summary and key points, answer "what have I already written about this," and run a weekly review that surfaces orphaned notes, stale tasks, and threads worth revisiting. This is retrieval and synthesis over your own knowledge, close in spirit to a RAG system, but running over plain files you control.

The honest boundary is the same one we draw on every agent we ship: let it do the reversible work, and keep a human on anything that is not. Capturing, filing, linking, and summarizing are low-stakes and easy to undo, so we automate them freely. Bulk renames, merges, and deletions are where a confident mistake gets expensive, so those stay behind review. Keeping the vault under version control turns every edit into something you can inspect and roll back, which is what makes trusting the agent safe rather than a leap.

Two cautions are worth stating plainly. The vault lives on your machine, but Claude Code sends the notes it reads to the model to reason over them, so treat it like any cloud AI tool: know what leaves your device, keep genuinely sensitive notes out of scope, and use path limits and permission settings to bound what the agent can touch. And a second brain is still yours to think with; the skill does the librarian's work so you can do the thinking, not the reverse. If you want the groundwork on why an agent behaves this way, our field guide "What Is Agentic Development? A Field Guide for Operators" covers the retrieve-reason-act-verify loop underneath it.