How Agent Skills Are Integrated into Claude-Obsidian: Architecture and Implementation

Agent Skills in Claude-Obsidian are self-describing units stored as SKILL.md files in the skills/ directory, discovered by hosts through claude_obsidian/package_validation.py, and executed via a portable core script that enforces strict vault boundaries and transactional safety.

The AgriciDaniel/claude-obsidian repository implements a host-agnostic Agent Skills architecture designed for portable, safe interaction with Obsidian vaults. Each skill is a self-contained Markdown file with standardized front-matter, enabling any compatible runtime—from Claude Code to Codex or Gemini—to discover and invoke capabilities without configuration changes.

SKILL.md Structure and Discovery

Every Agent Skill in Claude-Obsidian follows a strict minimal contract defined in SKILL.md files located at skills/<skill-name>/SKILL.md. These files require exactly two front-matter fields: name and description, which make the skill automatically discoverable by compatible hosts.

The discovery mechanism is implemented in claude_obsidian/package_validation.py, which scans the repository for skills/*/SKILL.md patterns to build a runtime catalog of available capabilities. This validation ensures that only properly formatted skills are exposed to the host environment.

For example, the top-level wiki skill resides at skills/wiki/SKILL.md and defines the orchestration logic for sub-skills like wiki-ingest, wiki-query, and save.

The Portable Core Execution Model

All skills invoke a single portable core script located at scripts/claude-obsidian.py. This design ensures consistent behavior regardless of which host runs the skill.

Skills access the core by absolute path, passing vault selection criteria and operation parameters through a uniform CLI interface. The core handles:

• Vault resolution (targeting a separate directory of Markdown/JSON files)
• Operation-transaction contracts
• Mutation safety checks

CORE=/absolute/path/to/scripts/claude-obsidian.py
python3 "$CORE" --help

Because the core is invoked by absolute path rather than relative imports, skills remain portable across different installation contexts and host environments.

Intent Routing and Skill Orchestration

The wiki skill acts as a top-level orchestrator that routes user intents to specialized sub-skills based on a static intent-to-skill mapping table defined within its SKILL.md.

When you invoke the skill using the namespaced command:

/claude-obsidian:wiki

The orchestrator parses the request and delegates to the appropriate handler:

Intent	Target Skill
Ingest supplied sources	wiki-ingest
Answer from vault	wiki-query
Save conversation result	save
Automated research	autoresearch

Each sub-skill operates independently but conforms to the same Agent Skills contract, residing in its own skills/<sub-skill>/SKILL.md file.

Transaction Safety and Vault Boundaries

Claude-Obsidian enforces strict architectural boundaries between the application code and user data. The vault is always treated as a separate directory of ordinary Markdown and JSON files—the core never treats the product checkout or plugin cache as the vault.

When sub-skills process operations, they return drafts and evidence objects. The portable core merges these into a single recoverable claude-obsidian.transaction.v1 bundle before applying any writes. This transaction pattern ensures that:

1. Changes are batched atomically
2. Failed operations can be rolled back
3. User vaults remain isolated from application state

Cross-Host Compatibility

The Agent Skills integration is intentionally host-agnostic. Because the contract is fully described in SKILL.md front-matter and AGENTS.md, any runtime implementing the Agent Skills specification can invoke Claude-Obsidian functionality.

Claude Code uses the namespaced syntax:

/claude-obsidian:wiki

Generic Agent Skills hosts use native syntax:

<host-specific-invoke> wiki

The README.md highlights this compatibility with an Agent Skills badge, emphasizing that Claude-Obsidian requires no host-specific modifications to function across different AI platforms.

Summary

• Self-describing skills: Each capability lives in skills/<name>/SKILL.md with name and description front-matter
• Automated discovery: claude_obsidian/package_validation.py scans and validates available skills at runtime
• Portable execution: The scripts/claude-obsidian.py core provides a host-agnostic CLI invoked by absolute path
• Intent routing: The wiki skill orchestrates sub-skills (wiki-ingest, wiki-query, save) via static mapping tables
• Transaction safety: All operations compile into a claude-obsidian.transaction.v1 bundle before vault modification
• Vault isolation: User data resides in a separate directory, never mixed with application code or caches

Frequently Asked Questions

What file format is required for Agent Skills in Claude-Obsidian?

Each skill must be a Markdown file named SKILL.md located in skills/<skill-name>/. The file must include YAML front-matter with exactly two fields: name (the skill identifier) and description (human-readable purpose). This minimal contract allows claude_obsidian/package_validation.py to detect and validate skills automatically without additional configuration.

How does the portable core script handle vault selection?

The core script at scripts/claude-obsidian.py receives vault paths through its CLI interface when invoked by the skill implementation. It resolves these paths absolutely and validates that the target is a directory of Markdown/JSON files rather than the application checkout or system directories, enforcing the architectural boundary that keeps user data isolated from code.

Can Claude-Obsidian skills run on AI platforms other than Claude Code?

Yes. Because skills follow the standardized Agent Skills specification documented in AGENTS.md, they are fully portable across any compatible host including Codex, Gemini, or custom runtimes. The same SKILL.md files work without modification; only the invocation syntax differs between hosts (e.g., /claude-obsidian:wiki versus invoke wiki).

How does the transaction system protect user vault data?

Before any write operation, the core aggregates outputs from sub-skills into a claude-obsidian.transaction.v1 bundle. This intermediate format contains drafts and evidence records that can be inspected, validated, or discarded atomically. Only after successful bundle validation does the core apply changes to the vault, ensuring that partial failures or corrupted operations never leave the vault in an inconsistent state.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}