forge-obsidian

Teaches AI coding assistants how to work with your Obsidian vault — wikilinks, frontmatter conventions, tag usage, and file verification. Also provides the /Draft and /Promote workflow for authoring skills in the vault before pushing them to modules.

CLAUDE.md and AGENTS.md are autogenerated by /Init (forge-init.sh). Do not edit directly — run /Update (forge-update.sh) to regenerate.

Layer

Behaviour — part of forge-core's three-layer architecture (Identity / Behaviour / Knowledge). Loaded at session start via SessionStart hook or Claude Code's native skill discovery.

Skills

Skill	Purpose
ObsidianCLI	Official Obsidian CLI (1.12+) — files, properties, search, links, bases, daily notes
ObsidianConventions	Vault file conventions — wikilinks, frontmatter, tags, file verification
VaultOperations	TLP integration, patterns, preferences, and operational rules for vault work
WikiLink	Add [[wikilinks]] to a document by matching terms against vault notes + frontmatter enrichment
ObsidianBase	Resolve .base files — query vault notes (CLI preferred, binary fallback)
ObsidianTemplates	Template management — dual-file creation, rendering, schemas, Templater config
ProjectConventions	Project note conventions — base files, embeds, Dataview, frontmatter
Draft	Pull a module skill into the vault workspace for editing in Obsidian
Promote	Push a vault skill back to its target module for GitHub distribution
ObsidianREST	(deprecated) Local REST API — replaced by ObsidianCLI
ObsidianActions	(deprecated) Actions URI — replaced by ObsidianCLI

Draft/Promote workflow

Skills can be authored in Obsidian for iterative editing, then promoted to modules:

/Draft BehavioralSteering       # pull from forge-steering → vault workspace
# ... edit in Obsidian ...
/Promote BehavioralSteering     # push back to forge-steering

• /Draft copies a module skill to Orchestration/Behaviour/<SkillName>/ and adds source_module: frontmatter for provenance tracking
• /Promote reads source_module:, copies back to the module, strips the provenance field, removes the vault copy, and commits
• /Promote (no args) promotes all drafts with source_module: frontmatter

The vault workspace path is configured in forge-steering/config.yaml under steering:. forge-update.sh auto-injects it into plugin.json when active drafts exist.

Layout

forge-obsidian/
├── module.yaml
├── skills/
│   ├── ObsidianCLI/SKILL.md
│   ├── ObsidianConventions/SKILL.md
│   ├── VaultOperations/SKILL.md
│   ├── WikiLink/SKILL.md
│   ├── ObsidianBase/SKILL.md
│   ├── ObsidianTemplates/SKILL.md
│   ├── ProjectConventions/SKILL.md
│   ├── Draft/SKILL.md
│   └── Promote/SKILL.md
├── hooks/
│   ├── hooks.json
│   ├── session-start.sh
│   └── skill-load.sh
├── .claude-plugin/plugin.json
└── README.md

Quick Start

# As a Claude Code plugin (standalone)
claude plugin install forge-obsidian

# Or as part of forge-core (submodule, already included)
git submodule update --init Modules/forge-obsidian

Once active, Claude Code discovers skills automatically when you work with vault files.

Configuration

module.yaml — checked into git:

name: forge-obsidian
version: 0.6.0
description: Obsidian vault conventions. USE WHEN working with Obsidian vault files.
events:
  - SessionStart

User Extensions

Inline overrides (User.md)

Create skills/ObsidianConventions/User.md (gitignored) with your personal rules:

## My Overrides

- Always use ISO 8601 dates in frontmatter
- Link people with [[FirstName LastName]] format

How It Works

Different AI providers load skills differently:

Provider	How it discovers skills	How it loads content
Claude Code	Reads SKILL.md frontmatter at session start	Loads full skill on demand
OpenCode	SessionStart hook emits metadata	forge-load library transforms content
Cursor / Copilot	Baked into static config via adapters	Content included at session start

Note for Claude Code users: The SessionStart hook exists for non-Claude-Code providers. Claude Code's skill discovery handles content loading directly.

Dependencies

Dependency	Required	Purpose
Obsidian 1.12+	Recommended	CLI for vault operations — see /ObsidianCLI
Local REST API plugin	Deprecated	Replaced by Obsidian CLI. See /ObsidianREST for legacy reference
Actions URI plugin	Deprecated	Replaced by Obsidian CLI. See /ObsidianActions for legacy reference

All dependencies degrade gracefully — skills fall back to file-system operations (Glob, Grep, safe-write).

Path Resolution

Use Core/bin/paths.sh as the shared cross-platform path contract.

From the repository root:

eval "$(bash Core/bin/paths.sh)"

Then use the exported values (FORGE_ROOT, FORGE_USER_ROOT, SAFE_READ_CMD, SAFE_WRITE_CMD, memory paths, journal path, backlog path) instead of re-implementing path/env resolution inside skills.