# Connecting Claude Code to Your Second Brain How a simple skill turns Obsidian into a live dashboard for your AI agents, skills, and plans. category: Building date: 2026-03-05 reading-time: 5 min read excerpt: Claude Code generates useful artefacts — agents, skills, plans — but they live in hidden dotfiles and scattered repos. obsidian-link connects them to your Obsidian vault so they're browsable, searchable, and connected. --- ## Obsidian as a second brain If you haven't come across [Obsidian](https://obsidian.md), it's a markdown-based knowledge base that runs entirely on local files. No cloud lock-in, no proprietary format — just folders of `.md` files that you own. What makes it powerful isn't the editor (though it's good). It's the *connections*. Obsidian gives you backlinks, graph view, tags, and a plugin ecosystem that turns a pile of notes into a navigable knowledge graph. You can see how ideas relate to each other. You can search across everything instantly. And because it's all just files on disk, it plays nicely with other tools. People use it for everything — engineering docs, product specs, meeting notes, personal journals, project planning. You don't need to be a developer to get value from it. If you write things down, Obsidian makes those things findable and connected. Claude and myself have been building something called [Zodsidian](https://github.com/conorluddy/Zodsidian) that takes this further — an Obsidian plugin that enforces structure on note frontmatter using Zod schemas, then exposes the vault as a typed data graph that AI agents can query. Think of it as giving your second brain an API. But that's a story for another post. ## The problem Claude Code is brilliant at generating useful artefacts. Custom agents that handle specific workflows. Skills that encode repeatable processes. Plan files that break down complex projects into steps. But where do these things live? Agents sit in `~/.claude/agents/` or `.claude/agents/` inside project repos. Skills are in `~/.claude/skills/`. Plans end up in `~/.claude/plans/`. They're scattered across hidden directories, and unless you know exactly where to look, they're invisible. You can't search across them. You can't see which projects share patterns. You can't browse your growing library of AI tooling without dropping into a terminal and running `ls`. If you're using Claude Code for product planning, project management, or team coordination, these artefacts should be *visible*. They should be searchable, cross-referenced, and easy to browse — especially for people who aren't living in a terminal all day. ## Symlinks as portals The solution uses symlinks, which are worth a quick explanation. A symlink is a pointer — think of it as a portal from one location to another. When you create a symlink, a file appears to exist in two places, but there's only ever one real copy. Open the portal, you get the original file. Edit through the portal, you're editing the original. No duplication, no syncing, no drift. This is how `obsidian-link` bridges Claude Code and Obsidian. It creates portals between where your AI artefacts actually live and your Obsidian vault, so Obsidian can see and index them without anything being copied or moved. ## What obsidian-link does [obsidian-link](https://github.com/conorluddy/ObsidianSkills) is a Claude Code skill with four modes: **Link** — The default. Run `/obsidian-link` inside any project and it connects that project's agents and skills to your vault. It creates a `ClaudeCode/` directory in your vault with organised subdirectories for agents, skills, and plans. Everything is symlinked, so files stay where they belong. **Status** — A health check. Run `/obsidian-link status` to see every linked project, how many agents and skills each has, and whether any symlinks are broken (maybe you deleted a file or moved a repo). **Unlink** — Cleanly disconnects a project from your vault. Removes the symlinks, leaves all your actual files untouched. **Init** — Sets up plan file templates with Obsidian-friendly frontmatter. This means every plan Claude creates automatically gets tags, status fields, and metadata that make it browsable with Obsidian's Dataview plugin and visible in graph view. ### Directionality There's a deliberate design choice in how the linking works: - **Global agents and skills** (ones you use across all projects) live in your Obsidian vault. The vault is the source of truth, and symlinks point *into* `~/.claude/`. - **Per-project agents and skills** live in their project repos (where they should be, version controlled). Symlinks point *into* Obsidian. Both directions use the same portal concept. Files always have one true home — the symlinks just make them visible from both sides. ## What you get Once you've linked a few projects, your Obsidian vault becomes a live dashboard for your Claude Code setup.
![A plan file browsable in Obsidian, with structured frontmatter, project agents and skills visible in the sidebar](/images/obsidian-link/obsidian-vault-plan.jpg)
**Graph view lights up.** Agents, skills, and plans appear as nodes. The auto-generated index note uses wikilinks, so Obsidian's graph view shows how everything connects — which projects share skills, which plans reference which agents. **Search across everything.** Want to find every agent that mentions "deployment"? Every plan with status "draft"? Obsidian's search covers it all in one place, across every linked project. **Non-technical access.** Anyone on your team who uses Obsidian can browse project architecture, read agent instructions, and review plans without touching a terminal. Product managers can see what skills exist. Designers can read the agents that handle their workflows. Everyone gets visibility. **Plans become first-class notes.** With the init mode configured, every plan Claude creates includes frontmatter that Obsidian understands — status tracking, tags, project attribution, dates. You can build Dataview dashboards that show all active plans across all projects. ## Getting started Install the skill from [the GitHub repo](https://github.com/conorluddy/ObsidianSkills), then run `/obsidian-link` inside any project. The skill handles the rest — it'll ask where your vault is, create the directory structure, and set up the symlinks. It's fully idempotent, so running it multiple times is safe. It reports what it did — how many new links, how many were already in place, whether anything is broken. And it never auto-deletes anything. If a symlink is broken, it tells you and lets you decide what to do. If you're already using Obsidian as your second brain, this just gives it eyes into one more part of your workflow. And if you're not using Obsidian yet — this might be a good reason to start.