Obsidian Claude Code Instructions 2026-01-03

CLAUDE.md

System Overview

This is Danny's personal knowledge management vault using Obsidian (local markdown) and taskdn for task management. The system follows a modified PARA methodology with a focus on areas, projects, tasks, and documents. Notion contains historical data and is used for client-facing pages only.

Philosophical Foundation

This system embraces "emergent structure" over rigid hierarchy:

• Ideas as objects: Categories and templates create reusable, combinable concept objects
• Profuse linking: Internal links and unresolved links become "breadcrumbs for future connections"
• Concise clarity: Templates and structured frontmatter enable faster understanding and more combinable ideas

Vault Structure

• 1-inbox/ - Raw notes before processing, often from the web-clipper or external tools.
• 2-day-notes/ - Daily running notes, one per day. Acts as a kind of "bullet journal".
• 3-areas/ - Major life areas (Health, Finance, Coding, etc.) and Clients
• 4-projects/ - Currently active (or paused) projects
• 5-documents/ - All other notes and docs
• 6-annals/ - All content in "deep archive". Will be exclded from most searches
• 7-tasks/ - Task files (in tdn spec)
• ai-docs/ - Documentation specifically for providing context to various AI tools and agents
• Attachments/ - All attached images and files
• Categories - One doc per category. Notes created from templates reference these in their frontmatter.
• Readwise/ - Imported content from articles and books
• Templates/ - Note templates for various different content types
  • Templates/Bases/ - Obsidian Bases files for data display and filtering

Template Maintenance Note

When creating new Areas in 3-areas/, the Project Template (Advanced) needs updating to include the new area in its suggester list. The template is located at Templates/Templater/Project Template (Advanced).md - update line 4 to add the new area to both the display array and the link array.

Working Patterns

Note Creation

• New notes usually start in 1-inbox/ or 5-documents/
• Use templates from Templates/ folder whenever applicable
• Link liberally using [[double brackets]] - this is Obsidian's strength

File Organization

• Move processed inbox items to appropriate folders - almost always 5-documents
• NEVER put random documents in 3-areas or 4-projects or 7-tasks
• Use descriptive filenames without dates (Obsidian handles metadata), except when dealing with Day Notes.
• Never create new tags without asking the user

AI Assistant Guidelines

Task Management (taskdn)

When working with areas, projects, or tasks, load the task-management skill first. This provides full documentation on the taskdn CLI and file formats.

Quick commands:

• tdn context --ai - Get overview of current areas, projects, and tasks
• tdn today --ai - See today's actionable tasks
• tdn new "Task title" --ai - Create a new task
• tdn list --ai - List tasks with filtering options

Key rule: Always use tdn new --ai to create tasks, not manual file creation. The CLI handles timestamps and proper formatting.

When Working with Notes

• Maintain existing linking patterns and folder structure
• Use templates when creating new structured content
• Respect the inbox processed workflow
• Keep markdown formatting consistent with existing notes
• Preserve existing tagging and categorization systems

Common Tasks

• Processing inbox items into appropriate locations
• Creating structured notes from raw thoughts/captures
• Linking related notes and surfacing connections
• Maintaining consistent formatting and organization
• Helping with periodic reviews and cleanup

Available Commands

Two specialized commands are available for managing the knowledge base:

• /inbox-clean - Clean and enhance inbox items with metadata, linking, and formatting
• /inbox-organize - Move cleaned items to final destinations and update day notes

What NOT to Do

• Don't create files outside the established folder structure without asking
• Don't change the fundamental organization system
• Don't over-complicate simple notes with excessive formatting
• Don't break existing link patterns

Frontmatter & Metadata

YAML Frontmatter Patterns

Templates use structured frontmatter to categorize and link notes:

---
categories:
  - '[[People]]'
tags:
  - people
birthday:
org: []
created: { { date } }
---

Categories System

• Categories are special notes in /Categories directory (People.md, Companies.md, Books.md, etc.)
• Templates reference categories as [[CategoryName]] in frontmatter
• Each category note just has tags: [category] in its frontmatter
• This creates a structured taxonomy for different content types

Data Display: Bases vs DataView

Primary Method: Obsidian Bases (native, early access v1.9.0+)

• Use Bases for all simple data display, filtering, and organization
• Native performance, cleaner syntax, multiple views per base
• Base files stored in Templates/Bases/ directory

Fallback: DataView Plugin

• Only use DataView when Bases cannot accomplish the task
• Complex JavaScript logic, advanced aggregations, custom HTML output
• Legacy queries remain in dashboard for complex project grouping

Bases Usage

Embed bases in notes: ![[BaseName.base]] or ![[BaseName.base#ViewName]]

Available bases:

• Category bases: Books, People, Trips, Companies, Apps, etc.
• Core bases: Projects, Areas, Inbox, DayNotes
• Contextual: AreaProjects (for individual area pages)

DataView (Legacy/Complex Only)

Reference: See ai-docs/DataView Reference.md for complex query syntax

Core Obsidian Mechanics

Tags: #tagname or #nested/tag - combine with Categories system via frontmatter. DataView queries can filter by tags.

Backlinks: [[Note Name]] creates bidirectional links. Links in frontmatter (categories: [[[People]]) create structured relationships. Unresolved links become "breadcrumbs for future connections."

CRITICAL - Frontmatter Link Formatting: All links in YAML frontmatter MUST be quoted. Examples:

• ✅ loc: "[[London]]"
• ✅ categories: ["[[People]]"]
• ❌ loc: [[London]] (will break YAML parsing)
• ❌ categories: [[[People]]] (will break YAML parsing)

Markdown Style Guidelines

Headings:

• File title serves as document title - don't add H1 at top
• Use H1 (#) for main sections, H2 (##) for subsections, etc.
• Avoid emoji in headings or at start of headings

General:

• Minimal emoji use - don't overuse
• Keep formatting clean and consistent

Plugin-Enhanced Workflows

Folder Notes Plugin

The vault uses the Folder Notes plugin which creates special index notes for folders. These notes have the same name as their containing folder (e.g., 1-inbox/1-inbox.md, 3-areas/3-areas.md, 4-projects/4-projects.md).

Important points:

• These folder notes are hidden from folder listings in Obsidian (they merge with the folder icon)
• Base views filter them out to avoid duplication using conditions like file.name != "1-inbox"
• They typically contain embedded Base views or folder overviews
• When working with folders, be aware these index files exist but won't show in normal listings

Templater (Advanced Templates)

Templater extends core templates with JavaScript capabilities:

<% tp.date.now("YYYY-MM-DD") %>          # Current date
<% tp.file.title %>                      # File name
<% tp.file.creation_date() %>            # Creation timestamp
<% tp.web.daily_quote() %>               # Dynamic content

Key Points:

• All functions under tp object
• Use <% %> syntax (not {{ }})
• Can execute JavaScript and conditionals
• Templates auto-apply when creating via Calendar plugin

Daily Notes Integration

Calendar + Daily Notes:

• Templates apply automatically when using Calendar
• Uses YYYY-MM-DD format in 2-day-notes/ folder
• Journaling plugin provides journal-like continuous view

Notion (Legacy)

Notion contains historical data and is used only for client-facing pages and public docs. All active areas, projects, and tasks are managed in Obsidian via taskdn.

When referencing Notion content, collection URLs are provided in ai-docs/My System.md for historical reference.

For task management, load the task-management skill which provides full documentation on the taskdn CLI and file formats.

inbox-clean.md

description	allowed-tools
Clean and enhance inbox items with metadata, linking, and URL fetching while preserving original intent	Read Write Edit Glob WebFetch Bash Skill

/inbox-clean - Clean and Enhance Inbox Items

Purpose

Systematically clean and enhance items in 1-inbox/ folder by adding metadata, [[linking]], fetching URL content, and improving formatting while preserving original intent and brevity.

Usage

/inbox-clean [--dry-run] [--no-fetch] [--type=restaurant|clipping|voice|task|person]

Arguments

• --dry-run - Show what would be done without making changes
• --no-fetch - Skip URL fetching entirely
• --type - Process only specific item types

Execution

1. Load task-management skill - Run Skill(tdn:task-management) to load taskdn documentation before processing any tasks

2. Read existing templates - Examine all files in Templates/ folder to understand frontmatter patterns and field structures

3. Read all inbox notes into context - Before processing, read ALL notes in 1-inbox/ to understand patterns, related content, and overall themes

4. Sort by creation time - Process oldest to newest to handle sequential voice notes properly

5. For each item (oldest first):

   • Read content and identify type
   • Handle content-as-filename pattern: If file is empty/single line but filename contains meaningful content (like "Book day skippers with Chris https..."), move filename content into file body and rename to appropriate descriptive name
   • Handle obvious mistakes: If file contains just random meaningless words ("the", "a", etc.) → clear content completely (empty file)
   • Handle empty files: Skip entirely, no processing needed
   • Improve filename to be descriptive (remove special chars, make meaningful)
   • Add frontmatter ONLY when clearly appropriate: Don't add frontmatter unless content clearly fits a specific template (restaurants, clippings, people, etc.). Random thoughts/notes are fine without frontmatter
   • Fix obvious transcription errors, spelling mistakes, and add basic punctuation
   • Wrap proper nouns in [[double brackets]] for future linking (even in tasks)
   • Add project/area links only when connection is clear and specific
   • Check for sequential voice notes that should be concatenated

6. URL fetching (when needed):

   • Only fetch if file contains ONLY a URL or very minimal content
   • Restaurant Google Maps → extract name, address, basic info only
   • Tweet URLs → pull tweet text and author name only
   • Article URLs → title, author, publication date only
   • If URL fetch fails: Leave original URL in place, note in summary

7. Save enhanced versions back to same location in 1-inbox/

8. Generate processing summary with what was cleaned, failed fetches, files cleared, and tasks identified

Other Rules & Information

Critical - DO NOT expand content:

• Fix formatting, spelling, grammar, and add structure, but don't add analysis or interpretation
• Preserve original brevity and intent
• Don't turn short notes into detailed plans or add context not in original
• Conservative frontmatter approach: Only add frontmatter when content clearly matches a specific template pattern. Don't guess or force frontmatter on random thoughts/notes

Core Decision Principles:

• When in doubt, preserve rather than assume
• Ask rather than guess at connections
• Flag for manual review rather than make poor automated choices
• Always preserve original creation timestamps
• Templates are starting points, not rigid requirements

Category and People Note Rules:

• NEVER create new categories without explicit permission
• Only create People notes when person will be referenced multiple times
• One-off encounters → mention in relevant project/area instead
• Don't create notes for article authors unless they become significant

Type Detection & Handling:

• Web Clippings: Has frontmatter with source/author OR bare URL → ADD frontmatter
• Restaurants: Contains "Type: Restaurant", location info, or Google Maps links → ADD frontmatter
• People Captures: Clear person-focused content with context → ADD frontmatter (sparingly)
• Tasks: Imperative mood ("Call", "Remember to", "Book") → Flag for taskdn creation during organize phase. Clean content and add [[linking]] but DO NOT create task files manually
• Random thoughts/notes: Voice notes, informal observations, ideas → NO frontmatter, just clean formatting, fix spelling/grammar, and add [[linking]]
• Quotes: Quotation marks, attribution, inspirational text → Consider if worth structured frontmatter
• Content-as-filename: Empty/minimal content but filename contains the actual intended content

Sequential Voice Note Handling:

• Check for multiple notes with similar timestamps (same day)
• Look for continuation phrases ("also", "another thing", "oh and")
• If related content → concatenate with clear breaks between sections
• If separate thoughts → process individually

Linking Rules:

• Person names (first + last): [[Mitchell Hashimoto]], [[Eduardo]]
• Places: [[London]], [[Hastings]], [[Brixton]]
• Books: [[Clean Code]], [[I Will Teach You To Be Rich]]
• Companies: [[HashiCorp]], [[Notion]]
• Project/Area connections: Link to specific existing areas/projects when content clearly relates, use intelligence to determine appropriate connections rather than rigid mapping

CRITICAL - Frontmatter Link Formatting:

• All links in YAML frontmatter MUST be quoted
• ✅ loc: "[[London]]"
• ✅ categories: ["[[People]]"]
• ❌ loc: [[London]] (will break YAML parsing)

Error Handling:

• Empty files: Skip processing entirely
• Obvious mistakes: Files with just meaningless words ("the", "a", random text) → clear completely (empty content)
• Failed URL fetches: Leave original URL, note failure in summary
• Unclear content: When in doubt, preserve original and flag for manual review

Filename Improvements:

• Remove problematic characters: / \ : * ? " < > |
• Make descriptive based on content, not just creation time
• Examples: "Amazing Korean bbq place.md" → "Korean BBQ Restaurant.md"

Processing Context:

• Read all inbox items first to understand themes and relationships
• Process oldest to newest for better sequential voice note handling
• Typical batch size: ~50 notes (weekly processing)

inbox-organise.md

description	allowed-tools
Organize cleaned inbox items into their final destinations after manual review	Read Write Edit Glob Bash Skill

/inbox-organize - Move Cleaned Items to Final Destinations

Purpose

After manual review of cleaned inbox items, systematically move them to appropriate final locations (Documents, Annals, or append to existing notes) and update today's day note with processing summary.

Usage

/inbox-organize [--dry-run] [--interactive]

Arguments

• --dry-run - Show what would be done without making changes
• --interactive - Ask for confirmation on each move decision

Execution

1. Load task-management skill - Run Skill(tdn:task-management) to load taskdn documentation for creating tasks

2. Read cleaned inbox items - Examine all processed files in 1-inbox/

3. For each cleaned item:

   • Analyze content, tags, and project/area connections
   • Determine destination based on decision framework
   • Apply appropriate template if not already applied (only when clearly fits a template pattern)
   • Check if item should append to existing note vs create new one
   • If task identified: Use tdn new "Task title" --ai to create in taskdn, then delete inbox file

4. Move to destinations:

   • 5-documents/ - Content with ongoing value, related to active areas/projects
   • 6-annals/ - Worth keeping but not actively useful (completed tasks, outdated info, random bits and pieces)
   • Append to existing - Fragments that belong with existing project/area notes
   • 7-tasks/ - Tasks created via tdn new --ai (never manually)

5. Update project/area notes - Add backlinks where items were moved

6. Add summary to today's day note - Bulleted list linking to all processed items

Decision Framework

Documents vs Annals

Move to 5-documents/ when:

• Related to active areas or projects
• Likely to be referenced again
• Has ongoing value or relevance
• Connects to current thinking/work

Move to 6-annals/ when:

• Worth keeping for record but not actively useful
• Outdated information
• No clear connection to current areas/projects
• NOT for pure tasks - these should be created in taskdn via tdn new --ai

New Document vs Append

Create new document when:

• Content is substantial and standalone
• It's a distinct entity (person, place, book, restaurant)
• Warrants its own note for future linking

Append to existing when:

• Fragment of thought related to a project/area
• Updates to ongoing documentation
• Too small to warrant its own note but too valuable to lose

Template Application

Apply templates during organization phase:

• Restaurants → Restaurant Template in Documents
• People → People Template in Documents (if substantial contact)
• Books → Book Template in Documents
• Companies → Company Template in Documents
• Web Clippings → Usually stay as-is, may get Clipping Template if not already applied
• Random thoughts/voice notes → No template needed, keep clean and simple

Day Note Summary

Add to today's day note in 2-day-notes/YYYY-MM-DD.md:

## 📥 Inbox Processing Complete - [Date]

Processed **[X]** items from inbox:

### New Documents:

- [[Item Name]] - Restaurant recommendation
- [[Item Name]] - Article about coding practices
- [[Item Name]] - Contact info for new person

### Appended to Existing:

- Added restaurant note to [[Travel]] area
- Added health insights to [[Lab Rat]] project

### Archived to Annals:

- [[Completed Task]] - Old reminder
- [[Outdated Info]] - No longer relevant

### Tasks Created (taskdn):

- [[Call Eduardo about weeding]] - created via `tdn new`
- [[Book sailing course with Chris]] - created via `tdn new`

### Processing Stats:

- **Documents:** [X] items
- **Annals:** [X] items
- **Appended:** [X] items
- **Tasks Created:** [X] items
- **Templates Applied:** [X] items

Other Rules & Information

Core Decision Principles:

• When in doubt, err toward Documents over Annals
• Prefer appending over creating new notes
• Ask user rather than guess at connections
• Flag for manual review rather than make poor automated choices
• Always preserve original creation timestamps

Critical Rules:

• NEVER create new categories without explicit permission
• Only apply templates when content clearly fits a template pattern (conservative approach)
• Don't force templates onto ambiguous content - notes are fine without frontmatter
• Tasks must be created using tdn new --ai - never create task files manually
• When unsure about destination → flag for manual review

Batch Operations:

• Process all similar items together (all restaurants, all people, etc.)
• Look for patterns and connections between items
• Consider if multiple small items could be combined

Project/Area Updates:

• When appending to project/area notes, add date headers
• Create bidirectional links where appropriate
• Update project status if relevant

Error Handling:

• If destination unclear → flag for manual review
• If template doesn't fit → move without template
• If file conflicts exist → append number suffix

File Organization:

• Preserve meaningful filenames when moving
• Clean up any remaining problematic characters
• Ensure consistent naming conventions

Sensitive Content Handling:

• Never archive sensitive information to Annals (might be shared)
• Personal health, financial, or relationship content → Documents with appropriate privacy tags
• Consider which notes might need restricted access

Multi-Topic Notes:

• If note contains multiple unrelated items → ask user: "Split or keep together?"
• If split → create logical breaks, process each section appropriately
• If keep → choose primary topic for classification

Post-Organization:

• Verify all items moved successfully
• Check that inbox is empty or contains only items flagged for review
• Confirm day note summary is complete and accurate

Quick Reference - Most Common Flows:

1. Restaurant → Restaurant template → Documents
2. Voice note → Clean + categorize → Append to project/area
3. Web clipping → Check relevance → Documents or Annals
4. Task → Create via tdn new --ai → Delete inbox file after confirmation
5. Person → Assess significance → People template or mention in context