Obsidian Wiki — Agent Context

A skill-based framework for building and maintaining an Obsidian knowledge base. No scripts or dependencies — everything is markdown instructions that you execute directly.

Configuration

Resolve config using the Config Resolution Protocol in llm-wiki/SKILL.md:

1. Walk up from CWD — look for a .env file in the current directory, then each parent, up to $HOME. Stop at the first .env that contains OBSIDIAN_VAULT_PATH.
2. Global config — if no local .env is found, read ~/.obsidian-wiki/config.
3. Prompt setup — if neither exists, tell the user to run wiki-setup.

The resolved config sets OBSIDIAN_VAULT_PATH (where the wiki lives). It may also set OBSIDIAN_WIKI_REPO (where this repo is cloned) and other optional variables.

After reading config, always read $OBSIDIAN_VAULT_PATH/AGENTS.md if it exists. It contains owner-specific conventions (domain vocabulary, ingest preferences, writing style, project scoping) that override framework defaults for all skills. Apply it for the duration of the session.

Vault Structure

$OBSIDIAN_VAULT_PATH/
├── index.md                # Master index — every page listed, always kept current
├── log.md                  # Chronological activity log (ingests, updates, lints)
├── hot.md                  # Session hot cache — ~500-word semantic snapshot of recent activity
├── .manifest.json          # Tracks every ingested source: path, timestamps, pages produced
├── _meta/
│   ├── taxonomy.md         # Controlled tag vocabulary
│   └── *.base              # Obsidian Bases dashboard definitions (wiki-dashboard skill)
├── _insights.md            # Graph analysis output (hubs, bridges, dead ends)
├── _raw/                   # Staging area — drop rough notes here, next ingest promotes them
├── concepts/               # Abstract ideas, patterns, mental models
├── entities/               # Concrete things — people, tools, libraries, companies
├── skills/                 # How-to knowledge, techniques, procedures
├── references/             # Factual lookups — specs, APIs, configs
├── synthesis/              # Cross-cutting analysis connecting multiple concepts
├── journal/                # Time-bound entries — daily logs, session notes
└── projects/
    └── <project-name>.md   # One page per project synced via wiki-update

Every wiki page has required frontmatter: title, category, tags, sources, created, updated. Pages connect via internal links — [[wikilinks]] by default, or standard Markdown links when OBSIDIAN_LINK_FORMAT=markdown is set in config.

Skill Routing

Skills live in .skills/<name>/SKILL.md. Match the user's intent to the right skill:

Cross-Project Usage

The main use case: you're working in some other project and want to sync knowledge into your wiki or query it. Two global skills handle this — wiki-update and wiki-query. They work from any directory.

wiki-update (write to wiki)

1. Resolve config using the Config Resolution Protocol to get OBSIDIAN_VAULT_PATH
2. Scan the current project: README, source structure, git log, package metadata
3. Distill what's worth remembering (architecture decisions, patterns, trade-offs — not code listings)
4. Write to $VAULT/projects/<project-name>.md, cross-linking to concept/entity pages as needed
5. Update .manifest.json, index.md, and log.md

On repeat runs, it checks last_commit_synced in .manifest.json and only processes the delta via git log <last_commit>..HEAD.

wiki-query (read from wiki)

1. Resolve config using the Config Resolution Protocol to get OBSIDIAN_VAULT_PATH
2. Scan titles, tags, and summary: frontmatter fields first (cheap pass)
3. Only open page bodies when the index pass can't answer
4. Return a synthesized answer with [[wikilink]] citations

Visibility Tags (optional)

Pages can carry a visibility/ tag to mark their intended reach. This is entirely optional — untagged pages behave exactly as they always have (visible everywhere). The system stays single-vault, single source of truth.

Filtered mode is opt-in, triggered by phrases like "public only", "user-facing answer", "no internal content", or "as a user would see it" in a query. Default mode shows everything.

visibility/ tags are system tags — they don't count toward the 5-tag limit and are listed separately from domain/type tags in the taxonomy.

See wiki-query and wiki-export skills for how the filter is applied.

Core Principles

• Compile, don't retrieve. The wiki is pre-compiled knowledge. Update existing pages — don't append or duplicate.
• Track everything. Update .manifest.json after ingesting, index.md, log.md, and hot.md after any write operation.
• Connect with [[wikilinks]]. Every page should link to related pages. This is what makes it a knowledge graph, not a folder of files.
• Frontmatter is required. Every wiki page needs: title, category, tags, sources, created, updated.
• Single source of truth. Visibility tags shape how content is surfaced — they don't duplicate or separate it.
• Keep context warm. hot.md is a ~500-word semantic snapshot of recent activity. Every write skill updates it so the next session can pick up where the last one left off without crawling the full vault.

Architecture Reference

For the full pattern (three-layer architecture, page templates, project org), read .skills/llm-wiki/SKILL.md.