obs-vaults

name	obs-vaults
description	Use when the user wants an Obsidian-style vault, linked project documentation, developer docs, architecture notes, codebase knowledge base, repo map, or small connected Markdown notes that explain how a project works.

Obsidian Project Vaults

Overview

Create a developer-documentation Obsidian vault for the current project at the project root. The vault should explain how the project works through small connected Markdown notes, not one giant document and not pasted source-code dumps.

Core principle: the vault is a navigable map of the project. Each note should answer one focused question and link to related notes with Obsidian [[wikilinks]].

When to Use

Use this skill when the user asks for:

• An Obsidian vault for a project or repo
• Developer docs in Obsidian style
• Linked notes explaining a codebase
• A project knowledge base, architecture vault, repo map, or code walkthrough
• Small connected Markdown files that explain how the full project works

Do not use this skill for a single README update, generic documentation prose, or non-project note-taking unless the user specifically wants an Obsidian-style vault.

Required Output

Create exactly this folder at the project root unless the user gives a different path:

obs_vaults/

Do not create vault-docs/, project-vault/, or a nested vault folder unless the user asks for multiple vaults. obs_vaults/ itself is the Obsidian vault.

Workflow

1. Identify the project root before writing files. Prefer the nearest directory containing .git, package/build files, or clear project metadata.
2. Inspect the project enough to understand its purpose, stack, entrypoints, commands, tests, major modules, and runtime flow.
3. Create obs_vaults/ at the project root.
4. Write a small set of high-value Markdown notes first. Add more notes only when the project structure justifies them.
5. Use Obsidian [[wikilinks]] between notes. Every major note should link back to [[Home]] or a map-of-content note.
6. Prefer factual descriptions grounded in files you inspected. Mark uncertainty clearly instead of guessing.
7. Verify the vault exists, key notes are linked, and the docs match the current project.

Default Vault Structure

Start with this structure and adapt it to the repo:

obs_vaults/
  Home.md
  Project Map.md
  Architecture.md
  Development Workflow.md
  Commands.md
  Testing.md
  Glossary.md
  modules/
    <module-name>.md
  flows/
    <runtime-flow>.md
  apis/
    <api-or-interface>.md
  decisions/
    README.md

Only create apis/ when the project has APIs, routes, public interfaces, or integration points. Only create decisions/ when you find architectural decisions or important tradeoffs worth preserving.

Note Standards

Each note should be short and focused:

• Start with a one-sentence purpose.
• Include Related: [[...]], [[...]] near the top or bottom.
• Reference important source files with inline paths like src/main.ts.
• Explain relationships and behavior, not line-by-line code.
• Split notes when a section grows too broad.
• Prefer notes under about 100-150 lines; split earlier when a note covers multiple concepts.
• Avoid copying large code blocks unless a tiny snippet is necessary to explain an interface.

Use this front section when helpful:

# Note Title

Purpose: One sentence explaining what this note covers.

Related: [[Home]], [[Architecture]]

## What It Does

## Important Files

## How It Connects

Required Core Notes

Note	Purpose
Home.md	Entry point for the vault with links to all major maps and notes.
Project Map.md	Directory-level map of important files and folders.
Architecture.md	High-level components, boundaries, dependencies, and data/control flow.
Development Workflow.md	How a developer sets up, runs, changes, and verifies the project.
Commands.md	Build, test, lint, dev, deploy, and utility commands discovered from the repo.
Testing.md	Test frameworks, test layout, and how to run verification.
Glossary.md	Project-specific terms, domain concepts, acronyms, and naming conventions.

Create these optional notes when the repo makes them relevant:

• Configuration.md for environment variables, config files, and runtime settings.
• Deployment.md for deploy targets, Docker, CI/CD, hosting, and release flow.
• Data Model.md for schemas, database tables, domain entities, or persistent state.
• Integrations.md for external services, APIs, queues, webhooks, and third-party SDKs.

Home.md Template

# Home

Purpose: Entry point for understanding this project.

## Start Here

- [[Project Map]]
- [[Architecture]]
- [[Development Workflow]]
- [[Commands]]
- [[Testing]]
- [[Glossary]]

## Main Areas

- [[modules/<module-name>]]
- [[flows/<flow-name>]]

## Open Questions

- Add questions here when behavior cannot be confirmed from the repo.

Analysis Checklist

Before writing or updating notes, inspect likely sources of truth:

• Existing docs: README*, docs/, CONTRIBUTING*, changelogs
• Project metadata: package files, build files, lockfiles, framework config
• Entrypoints: main executable, app bootstrap, routes, CLI commands, workers
• Core modules: domain logic, services, components, libraries, integrations
• Tests: test folders, fixtures, test config, CI files
• Operations: Dockerfiles, deployment config, environment examples, scripts

Do not document secrets. If a file appears to contain credentials or private tokens, do not copy values into the vault.

Linking Rules

Use Obsidian links intentionally:

• Link note-to-note references as [[Architecture]], [[Project Map]], or [[modules/auth]].
• Use readable titles and stable paths.
• Prefer links over repeated explanations.
• Add backlinks from module notes to broader maps.
• If a note is mentioned but not created yet, either create a small note or remove the link.

Verification

Before reporting completion:

• Confirm obs_vaults/ exists at the project root.
• Confirm Home.md links to the main notes.
• Confirm every required core note exists unless you explain why it was intentionally omitted.
• Search for obvious broken [[links]] caused by typos or renamed notes.
• Check that each [[wikilink]] resolves to an existing .md note, accounting for spaces and subfolders such as [[Project Map]] and [[modules/auth]].
• Confirm notes reference real files and commands from the project.
• State any important uncertainty as an open question in the vault and in the final response.

Common Mistakes

Mistake	Fix
Creating vault-docs/ or a nested folder	Create obs_vaults/ directly at the project root.
Writing one giant architecture document	Split into focused notes connected by [[wikilinks]].
Copying source code into notes	Summarize behavior and link to file paths.
Guessing runtime behavior	Inspect files first; mark uncertainty when static analysis is not enough.
Creating empty placeholder notes	Only create notes with useful content, or list planned notes in Home.md.
Forgetting developer workflow	Always include commands, testing, and setup/running notes when discoverable.