# How to Turn Obsidian Into an AI Second Brain With a Claude Code Skill > An Obsidian vault is just a folder of markdown files, so a Claude Code skill can capture, file, link, and distill your notes for you. Here is how to turn Obsidian into an AI second brain, and where to keep a human in the loop. *7 min read · Published 2026-07-10 · [Muhammad Idrees](https://adrees.dev/about)* A second brain is only as good as your discipline in feeding it, and that discipline is the first thing to lapse when work gets busy. This is where an agent earns its place: point a Claude Code skill at your Obsidian vault and the capturing, filing, and linking you keep meaning to do gets done for you. The notes stay plain markdown on your own machine; the agent just handles the librarian's work. ## Key takeaways - A second brain is a personal knowledge system that captures notes, links them, and lets you retrieve and connect ideas later. Obsidian stores it as plain markdown files you own, with backlinks and a graph view, so nothing is trapped in a vendor's cloud. - A Claude Code skill is a SKILL.md file that teaches Claude Code a repeatable workflow. Its short description loads at session start and the full instructions load only when the task is relevant, and you invoke it by name or let the model call it automatically. - Because an Obsidian vault is only a folder of markdown files, Claude Code can read, write, link, and search it with its built-in file tools. The skill encodes your capture, filing, linking, and review conventions so the agent follows them consistently instead of improvising. - Keep the agent on a leash. Let it draft, link, and distill, but review its edits, keep the vault under version control so every change is reversible, and gate bulk renames or deletions behind a human. Automate capture and connection, not destruction. ## What is a second brain, and why build one in Obsidian? 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. ## What is a Claude Code skill? 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. ## Why is a Claude Code skill the right tool for an Obsidian vault? 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. ## How do you set up an Obsidian second-brain skill? 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. ## What can it actually do once it is wired up? 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. ## Where does the skill end and your judgment begin? 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. ## FAQ **Can Claude Code manage my Obsidian vault?** Yes. An Obsidian vault is a folder of plain markdown files, and Claude Code reads, writes, edits, and searches local files with its built-in tools, so pointed at the vault folder it can capture notes, file them, add backlinks, and summarize them. A Claude Code skill makes that behavior repeatable by encoding your naming, folder, and linking conventions in a SKILL.md file. **What is a Claude Code skill?** A Claude Code skill is a reusable SKILL.md file that extends Claude Code with a specific workflow. It pairs a short description, which tells the agent when to use the skill, with a markdown body of instructions. The description loads at the start of a session and the full file loads only when the skill is relevant, and you can invoke it by name or let the model call it automatically. Skills follow the open Agent Skills standard. **Is Obsidian a good app for a second brain?** Yes, for most people. Obsidian is local-first and stores everything as plain markdown you own, with wiki-style backlinks and a graph view that make the connections between notes visible. Because the vault is just files on disk, it works cleanly with version control and with external tools like Claude Code, and nothing is locked into a vendor's cloud. **Do I need to know how to code to use Claude Code with Obsidian?** Not really. A skill is plain-English instructions in a markdown file, not code, and you run Claude Code from your vault folder. Some comfort with a terminal helps, but you can begin with a single simple workflow, such as capturing and filing a note, and expand it as you learn what you trust the agent to do. **Is my data private if I use Claude Code with an Obsidian vault?** The vault itself stays on your machine, but Claude Code sends the note content it reads to the model to reason over it, so treat it like any cloud AI tool. Know what leaves your device, keep genuinely sensitive notes out of the agent's scope, and use path limits in the skill and your permission settings to control which files it can read and change. **How is a Claude Code skill different from Obsidian's AI plugins?** Most Obsidian AI plugins add a chat box or autocomplete inside the app. A Claude Code skill instead sets an agent loose on the vault as files: it can read across many notes at once, create and rename files, add backlinks, and run a multi-step review, after which you approve the changes. It is agentic work on your files, not an assistant living inside the editor. ## Sources - [Obsidian](https://obsidian.md/) - [Claude Code docs — Extend Claude with skills](https://code.claude.com/docs/en/skills) - [Agent Skills — open standard](https://agentskills.io/) --- Canonical page: https://www.sentientarc.com/blog/obsidian-second-brain-claude-code-skill