Building a Knowledge Base That AI Can Actually Use

There’s been a wave of posts about this combo lately: James Bedford’s full walkthrough, Greg Isenberg’s “personal OS” approach, kepano (Obsidian’s CEO) sharing Claude Skills. They’re all worth reading.

What most of these guides cover is the setup. Install Claude Code, point it at your vault, go. This post is about the structure that makes the whole thing actually work.

Why Structure Matters More Than Tools

#

You can run cd ~/my-vault && claude right now. Claude will read your files, answer questions about them, and even create new notes. The problem is quality.

If your vault is a flat folder of 200 files with inconsistent naming, no metadata, and no conventions, Claude will produce notes that match: inconsistent, hard to find, disconnected from everything else.

The AI inherits your organizational discipline. Or your lack of it.

James Bedford made an interesting observation in his walkthrough. He initially put everything in Obsidian, including content Claude generated, but found it diluted his knowledge graph. He now separates notes he personally wrote from AI-generated content.

I went the opposite direction. Claude writes directly into my vault, alongside my own notes, using the same templates and conventions. The key difference: I invested upfront in structure that constrains Claude’s output to match what I’d write myself.

My Setup at a Glance

#

I use Obsidian as my primary knowledge base for study notes and technical reference material. The vault has 170+ markdown notes organized into modules and topics, version-controlled with git, and synced to GitHub. Claude Code has 9 custom skills for creating and maintaining content.

The structure follows a simple hierarchy:

Vault/
├── .claude/skills/          # 9 Claude Code skills
├── CLAUDE.md                # AI assistant rulebook
├── Topic-Area/
│   ├── Module-01/
│   │   ├── 00-Overview.md
│   │   ├── 01-First-Topic.md
│   │   ├── 02-Second-Topic.md
│   │   └── 03-Third-Topic.md
│   ├── Module-02/
│   │   └── ...
│   └── Module-03/
│       └── ...
├── Dashboards/
└── Templates/

Nothing fancy. But every part of it is deliberate, and that deliberateness is what makes Claude effective.

The Principles That Make It Work

#

Consistent Naming and Numbering

#

Every file follows the same pattern: kebab-case English name, number prefix for ordering.

Module-03/
├── 00-Overview.md
├── 01-Introduction.md
├── 02-Core-Concepts.md
├── 03-Capabilities.md
├── 04-Advanced-Topics.md
├── 05-Training-Methods.md
├── 06-Optimization.md
├── 07-Activation-Functions.md
├── 08-Practical-Applications.md
└── 09-Common-Pitfalls.md

When I tell Claude to create a new note in a module, it can look at existing files and figure out the next number automatically. No ambiguity, no conflicts. The naming pattern is predictable enough that Claude doesn’t need to be told where to put things.

Rich Frontmatter as a Contract

#

Every note includes YAML frontmatter with metadata:

---
title: "Topic Title"
module: Module-03
tags:
  - core-concept
  - intermediate
content_type: concept
difficulty: beginner
has_practice_questions: true
has_diagrams: true
estimated_reading_time: "15 min"
status: complete
created: 2025-12-15
updated: 2026-01-20
---

This isn’t just metadata for Obsidian’s Dataview plugin. It’s a contract between me and Claude about what each note is. When Claude creates a new note, it fills in all these fields because the pattern is documented in CLAUDE.md. When Claude searches the vault, it can filter by difficulty, content type, or status without reading every file.

Think of frontmatter as a schema. The more consistent your schema, the more reliably AI can work with your data.

Templates That Enforce Structure

#

I have two templates. An overview template for entry points and a note template for individual topics:

# Topic Title

> One-line summary of this note.

---

## Learning Objectives

- Objective 1
- Objective 2

---

## Main Content

Your content here...

---

## Related Links

- Previous: [[Previous-Note]]
- Next: [[Next-Note]]

---

## Practice Questions

> Question here?

> [!success]- Click for answer
> Answer here.

The template does two things. It gives me consistent notes that are easy to navigate. And it gives Claude a pattern to follow without explicit instruction. After seeing 50 notes in this format, Claude will produce new notes that look the same. Templates are free structure.

CLAUDE.md as the Rulebook

#

The vault has its own CLAUDE.md file at the root. It covers:

• The full directory structure
• File naming conventions (English, kebab-case, number prefixes)
• Editing guidelines (preserve wiki links, use LaTeX for math, support tags)
• How to add new modules (step-by-step)
• A note template for reference
• Which Obsidian plugins are in use
• A table of all 9 Claude skills and when to use each

Skills for Repeatable Workflows

#

Claude Code supports custom skills: markdown files in .claude/skills/ that define reusable workflows. I have 9 of them. A few examples:

Convert Transcript takes raw lecture or reference material, identifies main topics, splits them into separate notes, adds examples and practice questions, and links everything together with wiki links. One transcript becomes a full module with 8-10 interconnected notes.

Vault Health Check audits the vault for broken internal links, missing tags, inconsistent naming, orphan files, and empty folders. I run it before pushing to GitHub. It catches the kind of drift that makes a vault gradually less useful over time.

Search and Organize helps me find notes across modules and reorganize them when the structure evolves. Useful when I realize a concept belongs in a different module than where I originally put it.

The idea is the same as Boris Cherny’s slash commands for Claude Code (covered in my previous post): anything you do more than twice should be automated.

What Claude Code Can Do in a Vault

#

Here’s the concrete workflow. A typical session looks like:

1. I paste raw material (a transcript, an article, or rough notes) into Claude Code
2. The “Convert Transcript” skill breaks it into structured notes with frontmatter, examples, and practice questions
3. I review and edit. Claude handles the scaffolding, I handle the understanding
4. The “Health Check” skill verifies all links resolve and all notes have proper metadata
5. The “Git Push” skill commits and pushes to GitHub

Other things Claude handles regularly:

• Generating study materials from existing notes (summaries, practice sets)
• Reorganizing notes when I restructure a module
• Filling in missing metadata across batches of notes
• Creating overview files that link to all notes in a module

What Doesn’t Work Yet

#

Honest assessment of the limitations:

Obsidian’s graph view is invisible to Claude. Claude reads files and follows wiki links. But it doesn’t understand the emergent relationships that Obsidian’s graph view reveals. It can’t say “these two modules are highly connected” unless you tell it.

Large vaults can exceed context windows. With 170 notes, Claude can’t hold the entire vault in context at once. It works file-by-file or module-by-module. For vault-wide operations, you need to be specific about scope.

Canvas files are awkward. They’re JSON under the hood, and Claude can technically edit them, but reasoning about spatial layout in a canvas isn’t something Claude does well.

Plugin-specific features need hand-holding. Bases queries, Dataview syntax, Templater scripts. Claude knows these exist, but you need to be explicit about what you want. The CLAUDE.md helps, but it’s not automatic.

Getting Started

#

If you want to try this:

1. Open your terminal in your Obsidian vault folder and run claude
2. Create a CLAUDE.md at the vault root. Describe your folder structure, naming conventions, and note format
3. Pick your most repeated task and make it a skill. For most people, that’s creating new notes from raw material
4. Add frontmatter to your notes. Even basic fields (title, tags, date) give Claude something to work with
5. Check out kepano’s Claude Skills for Obsidian for inspiration on what’s possible

You don’t need to restructure your entire vault. Start with one folder, get the conventions right, and expand from there.

The Real Payoff

#

Here’s what I didn’t expect: the biggest benefit isn’t the AI. It’s that building for AI forced me to build a better knowledge base.

Consistent naming, rich metadata, clear templates, documented conventions. These make the vault better for me, not just for Claude. I can find notes faster, navigate modules more intuitively, and trust that new content will fit the existing structure.

Claude is the forcing function. Good structure is the actual reward.

References: James Bedford’s Obsidian + Claude walkthrough, kepano’s Claude Skills for Obsidian, Greg Isenberg’s personal OS approach