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

> Discover how Claude-Obsidian integrates Agent Skills. Learn about self-describing SKILL.md files, validation, and secure execution within strict vault boundaries.

- Repository: [Agrici.Daniel/claude-obsidian](https://github.com/AgriciDaniel/claude-obsidian)
- Tags: architecture
- Published: 2026-08-25

---

**Agent Skills in Claude-Obsidian are self-describing units stored as [`SKILL.md`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/SKILL.md) files in the `skills/` directory, discovered by hosts through [`claude_obsidian/package_validation.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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

```bash
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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/SKILL.md).

When you invoke the skill using the namespaced command:

```text
/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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/SKILL.md) front-matter and [`AGENTS.md`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/AGENTS.md), any runtime implementing the Agent Skills specification can invoke Claude-Obsidian functionality.

**Claude Code** uses the namespaced syntax:

```text
/claude-obsidian:wiki

```

**Generic Agent Skills hosts** use native syntax:

```text
<host-specific-invoke> wiki

```

The [`README.md`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/package_validation.py) scans and validates available skills at runtime
- **Portable execution**: The [`scripts/claude-obsidian.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/AGENTS.md), they are fully portable across any compatible host including Codex, Gemini, or custom runtimes. The same [`SKILL.md`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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.