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 |
ProjectManagement | Project lifecycle — create, update, close projects, backlog rules, safe file operations |
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 |
