# Ariadne:vault

> Bootstrap an agentic Markdown knowledge vault for projects, research, learning, life systems, and other long-running knowledge work. Use when creating a new vault, installing the base folder structure, templates, AGENTS.md, CLAUDE.md, Agent navigation files, and optional Obsidian-compatible Bases.

- Skill: `pariyar07/ariadne-vault` (Agent Skill, multi-file: 62 files)
- Install (CLI): `npx skillmds@latest add pariyar07/ariadne-vault`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pariyar07/ariadne-vault/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: pariyar07 (https://skillmd.com/u/pariyar07)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/pariyar07/ariadne-vault

---


# Ariadne Vault

Use this skill to create or refresh a durable, agent-maintained Markdown knowledge vault. Obsidian is an optional, recommended frontend rather than a runtime requirement.

This skill complements Obsidian mechanics skills:

- Use `obsidian-markdown` for notes, properties, wikilinks, embeds, and callouts.
- Use `obsidian-bases` for `.base` views.
- Use `json-canvas` for `.canvas` maps.
- Use `defuddle` for clean Markdown extraction from web pages.
- Use `obsidian-cli` when Obsidian is open and CLI interaction is useful.

It also has workflow companion skills:

- `ariadne:knowledge-capture` for raw inputs, links, documents, and brain dumps.
- `ariadne:global-discovery` for registering existing vaults so cold agents can find them from any workspace.
- `ariadne:workspace-instructions` for creating or updating workspace-level `AGENTS.md`, `CLAUDE.md`, or `GEMINI.md` files that connect a workspace to registered Ariadne context.
- `ariadne:research-ingest` for cold-start research sources, target confirmation, and write-set orchestration.
- `ariadne:research-synthesis` for multi-source research disposition and inquiry history.
- `ariadne:research-stewardship` for audit-first research-boundary health and allowlisted repairs.
- `ariadne:research-pipeline` for adding research intake and synthesis infrastructure inside an existing scope.
- `ariadne:workstream-tracking` for Kanban work boards, Dataview dashboards, and workstream status tracking.
- `ariadne:closeout` for post-work capture, checkpoints, handoffs, and safe-to-close decisions.
- `ariadne:maintenance` for health checks and recurring maintenance.
- `ariadne:navigation` for hubs, routing, workstream graphs, and Base/view-layer changes.

## Prerequisites

Before bootstrapping or refreshing a vault, confirm the user has:

- A target vault folder available on disk.
- Optional: Obsidian installed when the user wants its native frontend.
- Optional: Obsidian Bases enabled when the vault should render `.base` dashboards.
- Node.js available for the validator and `scripts/register_vault.js`.
- A skills-capable agent runtime.

For full Obsidian mechanics coverage, recommend installing `https://github.com/kepano/obsidian-skills` alongside Ariadne when equivalent skills are not already available. Those companion skills cover Markdown, Bases, JSON Canvas, clean web extraction, and Obsidian CLI interaction.

## Core Model

The vault is the memory. The skill is the setup and maintenance procedure.

The human curates direction. Agents compile raw material into a linked Markdown wiki. Any filesystem-capable agent can operate the source directly. Obsidian is a recommended readable frontend; Bases and canvases are optional view layers over the Markdown source of truth and never replace it.

For multi-area vaults, model the vault as a recursive scope tree. The root scope owns global policy and shared view layers. Each child scope inherits parent rules and adds only local deltas — it never repeats the parent and never ignores it.

The design principles behind these patterns are documented in the skill references:

- `references/knowledge-processing-architecture.md` — intake interfaces, processing passes, and the raw → compiled pipeline
- `references/recursive-scopes.md` — scope inheritance, the includes-and-transcends model, wikilink resolution
- `references/vault-operating-model.md` — the three-layer vault model and navigability rules

These are reference documentation for skill users. They are not files to bootstrap into the target vault — the principles are encoded in how the skills work.

This skill bootstraps the system. Use the companion skills for ongoing ingest, synthesis, navigation changes, and maintenance.

## Start Workflow

Before writing, read applicable existing root and ancestor instructions. When refreshing a multi-scope vault, require a current-turn named or confirmed target and state an explicit `allowed_write_set`; name every out-of-target hub, routing matrix, or Base formula separately.

1. Determine the vault path and purpose.
2. Classify the vault mode:
   - `project` - shipping/building something.
   - `research` - studying a topic.
   - `learning` - building durable understanding.
   - `life` - personal operating system, admin, goals, habits.
   - `system` - procedures, workflows, infrastructure, automation.
   - `mixed` - more than one of the above.
3. Create or update the base folder structure.
4. Add core files from `assets/templates/`. A new vault must include the schema-v1 root checkpoint (`00 Index.md`, `AGENTS.md`, `Agent/00 Agent Navigation.md`, and `Agent/Task Routing Matrix.md`) plus `Bases/Scope Registry.base`, `Agent/Scope Map.md`, and `Agent/Scope Map.canvas`.
5. Customize `00 Index.md`, `AGENTS.md`, and `CLAUDE.md` for the vault purpose.
6. Add `Agent/00 Agent Navigation.md`, `Agent/Vault Navigation Standard.md`, `Agent/Task Routing Matrix.md`, and `Agent/Vault Health Check Procedure.md` when useful.
7. Add relevant mode folders from `references/vault-structure.md`.
8. Create Bases from the `.base` files in `assets/templates/` when useful.
9. Add `Bases/00 Bases Index.md` and link each Base from it, including the generated scope registry.
10. Add Kanban boards or Dataview dashboards only when a recurring workstream needs visible status tracking.
11. Validate that Markdown frontmatter and Base YAML parse.
12. If machine-level discovery is absent or stale, explicitly offer `ariadne:global-discovery` so future cold agents can discover the vault from outside the vault. Do not silently write global files.
13. If the user also has a code repository or folder that should point at this vault or one of its scopes, offer `ariadne:workspace-instructions` after the vault and discovery path are clear.

## Default Folder Structure

Create these folders unless the user asks for a different structure:

- `Raw/`
- `Raw/Sources/`
- `Inbox/`
- `Processing Queue/`
- `Notes/`
- `Research/`
- `Entities/`
- `Relationships/`
- `Concepts/`
- `Questions/`
- `Decisions/`
- `Outputs/`
- `Visualizations/`
- `Templates/`
- `Agent/`
- `Bases/`
- `Archive/`

Add mode-specific folders only when useful.

## Long-Term Context Discovery

Do not read the entire vault by default.

Use progressive discovery:

1. Read `00 Index.md`.
2. Read `AGENTS.md` or `CLAUDE.md`.
3. Read `Agent/Long Term Knowledge Workflow.md`.
4. Search filenames with `find`.
5. Search content with `rg`.
6. Read hub/index notes first.
7. Follow relevant wikilinks.
8. Read raw sources only when compiled notes are insufficient.
9. Use `.base` files to inspect note status and metadata.

## Machine-Level Vault Registration

After bootstrapping or refreshing a vault, check whether machine-level discovery is absent or stale enough to affect cold agents. If so, explicitly offer to use `ariadne:global-discovery` to register, update, or repair discovery for the vault.

Registration and repair are optional and should be explicit. Do not silently write global agent instruction files.

When the user agrees, use `scripts/register_vault.js`:

```bash
node /path/to/skills/vault/scripts/register_vault.js \
  --vault "/path/to/vault" \
  --name "Vault Name" \
  --purpose "Short purpose statement." \
  --agents codex,claude,gemini \
  --primary
```

What registration creates:

- `~/.ariadne/vaults.json` - machine-readable vault registry.
- `~/.ariadne/vaults.md` - agent-readable vault registry.
- small marker-managed discovery blocks in selected global agent files.

Supported adapters:

- `codex` - `~/.codex/AGENTS.md`
- `claude` - `~/.claude/CLAUDE.md`
- `gemini` - `~/.gemini/GEMINI.md`
- `copilot` - `~/.copilot/copilot-instructions.md`
- `opencode` - `~/.config/opencode/AGENTS.md`
- `roo` - `~/.roo/rules/ariadne-vault-discovery.md`
- `cline` - `~/Documents/Cline/Rules/ariadne-vault-discovery.md`

Use `--agents all` only when the user wants all supported adapters. Use `--agents none` when the user only wants the registry files.

Use `--dry-run` before writing when the user wants to inspect changes.

Use `--remove` through `ariadne:global-discovery` when the user wants to unregister a vault.

If a global discovery lookup returns multiple plausible vault matches, show the top matches with short reasons and ask which vault to use before creating, updating, or filing artifacts.

Inside a selected multi-scope vault, write actions need a current-turn explicit target. A target is explicit only when the current prompt names the target scope, domain, customer, project, or workstream, or the user confirms one after the agent asks. Search hits, a single likely match, existing matching cards, prior conversation, current working directory, and active skills are not confirmation.

Safety rules:

- Global files should point to `~/.ariadne/vaults.md`; they should not duplicate long vault instructions.
- Existing global instructions must be preserved.
- Updates must stay inside the marker block:
  - `<!-- ariadne:vault-discovery:start -->`
  - `<!-- ariadne:vault-discovery:end -->`
- Re-running registration for the same vault should update the existing registry entry, not duplicate it.
- Re-running registration can also refresh stale marker-managed discovery blocks when Ariadne ships newer discovery rules.

Cold agents that encounter the global discovery block should read the registry first for vague questions, terse keyword prompts, or empty-workspace ambiguity about prior projects, documents, meetings, research, decisions, customers, work history, personal knowledge, or "what was I working on".

## Navigation Pattern

New vaults should separate:

- knowledge graph: research, concepts, entities, relationships, decisions, architecture, product, and other durable semantic notes
- operating graph: agent instructions, workflows, templates, inbox, processing queue, raw sources, outputs, and health checks
- view layer: Bases, canvases, dashboards, and generated reports

Future scopes should be promoted only when recurring use needs a dedicated route. A promoted scope needs a hub, parent/child navigation links, routing coverage, optional local rules, optional templates, optional Bases, and health-check coverage.

The root starts as the active `root` scope at path `.`. Keep the generated `ariadne:scope-boundary`, `ariadne:scope-inheritance`, `ariadne:scope-navigation`, `ariadne:scope-routing`, and `ariadne:scope-map` blocks byte-compatible with the shared topology renderer. Keep vault-specific workflows and policy outside those blocks. The scope registry and Canvas are fully generated; do not hand-edit them or copy policy into inheritance output.

## Templates

Use the files in `assets/templates/` as starting points. Copy them into the target vault and customize placeholders.

See:

- `references/vault-operating-model.md`
- `references/vault-modes.md`
- `references/vault-structure.md`
- `references/maintenance.md`
- `references/knowledge-processing-architecture.md`
- `references/recursive-scopes.md`
- `references/bases-scope-patterns.md`