Project Vault

This skill bridges a code repository and an Obsidian vault project folder through a vault symlink. It handles three things:

Setup — Creating and managing the vault symlink
Context Reading — Discovering vault structure, reading conventions, and understanding project documentation
Note Creation — Creating any kind of note in the vault, following its rules and conventions

The skill is self-contained — it includes all Obsidian note-writing conventions needed to work with vault notes.

Critical Rules

Vault root CLAUDE.md takes precedence. If the vault root has a CLAUDE.md, read it first. Its instructions override defaults in this skill.
Discover, do not impose. Never create folders or notes that break the vault's existing organizational pattern. Analyze before writing.
Match existing conventions exactly. Frontmatter fields, tag naming, wikilink style, callout usage, and filename patterns must match what the vault already uses.
Vault is the source of truth for project understanding. When asked about the project, read the vault before answering.
Preserve link integrity. Every wikilink you write must point to a note that exists or that you are creating in the same operation.
Read-only for plan documents. Do not modify existing plan documents unless explicitly asked.

Phase 1: Setup

Run this phase when the user asks to link a vault folder, or when no vault symlink exists and the user wants project vault integration.

Step 1: Accept the target path

Ask the user for the vault project folder path. This is the path to a specific project folder inside their Obsidian vault — not the vault root itself. Example:

/Users/kao/Library/Mobile Documents/iCloud~md~obsidian/Documents/Personal Vault/01-Projects/Raihin

Step 2: Validate the target

Check that the target:

Exists as a directory
Contains at least one .md file with YAML frontmatter

If the target does not exist, ask the user if they want to create it. If they do, create the directory and a root index note (see Phase 3 for format).

Step 3: Check for existing `vault` entry

ls -la vault 2>/dev/null

Symlink exists: Show the current target. Ask the user if they want to update it.
Regular directory exists: Warn and abort — do not overwrite real directories.
Nothing exists: Proceed.

If updating, remove the old symlink first: rm vault

Step 4: Create the symlink

Always quote the target path (vault paths often contain spaces, especially iCloud paths):

ln -s "<target-path>" vault

Step 5: Let the user commit the symlink

Do not add vault to .gitignore. The symlink is just a tiny pointer file — git tracks it safely without pulling in vault contents. Committing the symlink lets other developers and AI agents know the vault link exists. Leave it to the user to decide whether to commit it.

Step 6: Update the project CLAUDE.md

After the symlink is created, add a section to the project's CLAUDE.md (create the file if it doesn't exist) explaining the vault link. This ensures any AI agent working in the project understands the vault directory without needing this skill installed.

Add a section like this:

## Project Vault

The `vault/` directory is a symlink to an Obsidian vault project folder containing project documentation — plans, implementation notes, personas, and design decisions. It is the source of truth for project context.

- Read `vault/` contents to understand the project before starting work
- The vault has its own conventions defined in the vault root's CLAUDE.md — follow them when creating or editing notes inside `vault/`
- The symlink target is outside this repository; git tracks only the pointer, not the vault contents

Adapt the wording to fit the project's existing CLAUDE.md style and content. If CLAUDE.md already has a section about vault/ or context/, update it rather than adding a duplicate.

Step 7: Find and read vault root CLAUDE.md

Resolve the symlink target to its absolute path, then walk up parent directories until you find:

A directory containing .obsidian/ — this is the vault root
Stop at the filesystem root if nothing is found

# Resolve the symlink and walk up
TARGET=$(readlink vault)
DIR="$TARGET"
while [ "$DIR" != "/" ]; do
  if [ -d "$DIR/.obsidian" ]; then
    echo "Vault root: $DIR"
    break
  fi
  DIR=$(dirname "$DIR")
done

If the vault root has a CLAUDE.md, read it. Follow its instructions — they define the vault's conventions for note structure, frontmatter, tags, naming, and organization. These conventions apply to all notes you create in Phase 3.

Phase 2: Context Reading

Run this phase before any task that requires project understanding, or when the user asks to read/understand the project context.

Step 1: Find vault root and read CLAUDE.md

Follow the same process as Phase 1, Step 6. If you already did this during setup, skip it.

Step 2: Identify the root index

Look for the project's entry-point note in vault/:

A .md file whose name matches the project folder name (e.g., Raihin.md in vault/ if the folder is Raihin/)
Fallback: any .md file with tags: [nav] in frontmatter
Fallback: README.md or Index.md

Read the root index — it maps out the project's note structure and links to key documents.

Step 3: Discover organization methodology

Scan the folder structure to identify how notes are organized:

Signal	Methodology
`Implementation/`, `Plan/`, `Persona/` folders	Phase-and-week project tracking
`Projects/`, `Areas/`, `Resources/`, `Archive/`	PARA
Index notes with heavy wikilink lists	Maps of Content (MOC)
Few folders, heavy `tags` in frontmatter	Flat + Tags
Numbered folders (`10-19`, `20-29`)	Johnny Decimal

Record what you find:

Top-level folder names and their purpose
Subfolder naming pattern (e.g., Week N - Focus, Phase N - Name)
Whether subfolders have their own index .md files

Step 4: Parse frontmatter conventions

Read 3–5 representative .md files from different parts of the vault. Extract:

Fields used: Which YAML fields appear (title, date, tags, status, parent, related, source-phase, etc.)
Tag patterns: Kebab-case? Nested with /? Project-specific tag present?
Status values: What values are used (open, closed, active, done, ideation, etc.)
Date format: Usually YYYY-MM-DD
Parent/related style: Wikilinks in quotes? YAML array of wikilinks?

Only use fields you observe in existing notes. Do not introduce new frontmatter fields.

Step 5: Parse note structure conventions

From the same sample notes, identify:

Heading hierarchy (H1 as title repeated from frontmatter? H2 for major sections?)
Callout usage (which types: > [!abstract], > [!info], > [!warning], etc.)
Whether ==highlights== are used for emphasis
Whether "Plan vs Implementation" comparison tables exist
Filename patterns (e.g., N - Title.md for issue notes, Title Case.md for others)
Wikilink style (filename only, or with path?)

Step 6: Map cross-references

Understand how documents link to each other:

Root index → Category indexes (Plan, Implementation, etc.)
  → Sub-indexes (Week 1, Phase 2, etc.)
    → Individual notes
      → parent: "[[Sub-index]]" (linking back up)

Check if an Issue Map or similar tracker exists that bridges GitHub issues to vault notes.

Output

After reading, you have an internal model of the vault's conventions. Do not dump this to the user unless they ask — use it silently to guide Phase 3.

Phase 3: Note Creation

Run this phase whenever you need to create a note in the vault — implementation docs, planning notes, research captures, decision records, idea briefs, meeting notes, or any other documentation the user asks for.

Step 1: Read vault conventions

If you have not yet run Phase 2, do it now — you need to understand the vault's structure before writing to it.

Step 2: Determine note type and placement

First, understand what kind of note you are creating. The vault's folder structure tells you where it belongs:

Match the note to the vault's existing categories. If the vault has Plan/, Implementation/, Persona/, Research/, or other domain folders, place the note in the matching folder. If no folder matches, place it at the project folder root or ask the user.

Placement rules by vault pattern:

Structured folders (e.g., Implementation/Week N/, Plan/Phase N/):
- Find the matching subfolder, or create a new one following the existing naming pattern
- Each subfolder should have an index note if sibling subfolders do
PARA pattern (project lives in 01-Projects/<Name>/):
- Place in the project folder or an appropriate subfolder
- Create a subfolder if the vault uses them for that note type
Flat + Tags pattern:
- Place at the top level of the project folder
- Rely on tags for organization
Unknown or new category:
- Ask the user where to place the note

Step 3: Construct the frontmatter

Build frontmatter using only fields observed in existing notes. The specific fields depend on the note type, but always follow the vault's patterns.

---
tags:
  - time-period-tag
  - category-tag
  - domain-tag
  - project-tag
date: 2026-03-26
parent: "[[Parent Index]]"
---

Rules:

Only include fields the vault actually uses — do not invent new ones
Match the exact tag naming pattern (kebab-case, project-specific tags, etc.)
Always include a time-period tag if sibling notes use them (e.g., week-1, phase-2, sprint-3). Check what tags existing notes in the same folder use — if they all share a time-period tag, your note must include it too.
Include the project-specific tag (e.g., raihin) if existing notes use one
parent links to the containing folder's index note
Add status only if existing notes of this type use it
Add title only if existing notes use a title field
Add related links to connect to relevant existing notes
Add other fields (like source-phase) only if you see them in similar existing notes

Step 4: Write the note body

The body structure depends on the note type. Always follow patterns you observed in existing notes of the same kind. The general structure is:

1. Title — H1 as the note title

2. Context block — If the vault uses callouts for context, add one:

> [!abstract]
> Brief context about what this note covers and why it exists.

3. Main content — The substance of the note. Adapt to the note type:

Implementation note: Summary, Plan vs Implementation table (if the vault uses this), Deviations with callouts, Decision Log
Planning note: Goals, scope, constraints, phases/milestones, dependencies
Research note: Findings, sources, analysis, conclusions
Decision record: Context, options considered, decision made, rationale
Idea/brief: Problem statement, proposed approach, success criteria
Meeting note: Attendees, agenda, discussion points, action items
General note: Whatever structure fits the content

4. Links — Wikilink generously to related notes in the vault.

Implementation Notes: Specific Patterns

When the note documents completed work (implementation, task completion), use these additional patterns if the vault already uses them:

Plan vs Implementation table:

| Aspect | Initial Plan | Actual Implementation | Status |
|---|---|---|---|
| Feature A | As specified | What was built | ✅ Aligned |
| Feature B | Original approach | Different approach | ⚠️ Changed |
| Feature C | Planned | Deferred to later | ⏭️ Deferred |

Deviations — each gets an H3 with a callout:

### Feature B changed approach

> [!warning] Changed
> What changed and why.

**Reason:** Why the deviation was necessary.

Decision Log:

## Decision Log

- Chose X over Y because of Z
- Deferred A to issue #N because of B

Step 5: Update parent indexes

After creating any note:

Find the parent index note (matching parent in frontmatter)
Add a wikilink to your new note under the appropriate heading
Follow the existing format — if the index groups links by category, place yours in the right group

If you created a new subfolder:

Create the folder's index note following the pattern of sibling index notes
Add the new index to its parent index

Step 6: Handle edge cases

No existing notes of this type to learn from: Propose a minimal format (frontmatter with date/tags/parent, H1 title, content) and ask the user to approve before creating.

Multiple notes needed at once: Create each note individually, then update the relevant indexes.

Note overlaps multiple categories: Pick the primary category for placement. Use related links and tags to connect to the other category.

New category not in vault structure: Ask the user whether to create a new folder or place the note in an existing one. If creating a new folder, follow the naming pattern of sibling folders and create an index note.

Obsidian Note Conventions

These are the standard Obsidian conventions to follow when writing notes. If the vault root CLAUDE.md defines different conventions, follow those instead.

Frontmatter

Every note gets YAML frontmatter. Standard fields:

Field	Required	Description
`tags`	Yes	YAML array, lowercase, hyphenated
`date`	Yes	Creation date, `YYYY-MM-DD`
`status`	Context-dependent	e.g., `active`, `closed`, `done`
`parent`	Recommended	Wikilink to parent index: `"[[Parent Note]]"`
`related`	Optional	Array of wikilinks: `["[[Note A]]", "[[Note B]]"]`

Wikilinks

Use [[wikilinks]] for all internal references, never markdown links
Link to specific sections with [[Note#Heading]]
Obsidian resolves wikilinks by note name, not file path — moving files does not break links

Callouts

> [!abstract]
> Summary or context at the top of content notes.

> [!info]
> Explanatory guidance, folder purpose descriptions.

> [!warning]
> Incomplete items, deviations, risks.

> [!tip]
> Helpful suggestions, enhancements.

> [!example]
> Examples, agent prompts, templates.

Naming

Notes: Title Case — Idea Brief.md, Implementation Review.md
Utility folders: lowercase-hyphens — daily-notes/, attachments/
Content folders: Title Case — 01-Projects/Raihin/, Plan/
Issue notes: N - Title.md pattern (number, space, hyphen, space, title)

Diagrams

Do not use Mermaid diagrams — use markdown tables instead.

Vault Structure Examples

Phase-and-Week (project tracking)

vault/
├── ProjectName.md          (root index, tags: nav)
├── Plan/
│   └── Phase N - Name/     (phase folders with index notes)
├── Implementation/
│   └── Week N - Focus/     (week folders with index notes + issue notes)
└── Persona/                (supporting documentation)

Adaptation: Place implementation notes in the matching week folder. Create new week folders following Week N - Focus naming. Each folder gets an index note linking to its contents.

Flat + Tags

vault/
├── ProjectName.md          (root index)
├── Feature A.md            (tags: implementation, feature-a)
├── Feature B.md            (tags: implementation, feature-b)
└── Architecture.md         (tags: plan, architecture)

Adaptation: Place notes at root level. Rely on tags for organization. No subfolders or index notes needed.

PARA with subfolders

vault/
├── ProjectName.md          (root index)
├── planning/               (plan documents)
├── dev-log/                (implementation notes)
└── research/               (reference material)

Adaptation: Place implementation notes in the dev-log/ or equivalent subfolder.

Integration Notes

Repo CLAUDE.md vs vault CLAUDE.md: The repository's CLAUDE.md governs code conventions. The vault root's CLAUDE.md governs documentation conventions. Both apply simultaneously — there is no conflict because they cover different domains.
Symlink is safe to commit: The vault symlink is a tiny pointer file — git tracks it without pulling in vault contents. Let the user decide when to commit it. The vault contents themselves are not tracked by git because the symlink target is outside the repo.
Concurrent editing: The user may edit vault notes in Obsidian while you work. Read notes fresh before modifying them to avoid overwriting the user's changes.

kao-project-vault