kepano/obsidian-skills: Teach AI Agents to Edit Obsidian Vaults

kepano/obsidian-skills: Teach AI Agents to Edit Obsidian Vaults

Developers who rely on Obsidian for knowledge management face a growing friction: their AI coding assistants can read and write code across entire repositories, but cannot natively manipulate the Markdown^{↗ Smart Converter}, canvas files, and structured databases that power their second brains. The result is context switching—copying notes into chat interfaces, manually reformatting agent outputs, or abandoning vault-integrated workflows entirely. kepano/obsidian-skills closes this gap by providing standardized agent skills that teach compatible AI systems to work directly with Obsidian's native formats and CLI.

What is kepano/obsidian-skills?

kepano/obsidian-skills is an open-source repository that implements the Agent Skills specification, enabling AI agents to create, read, and modify content within Obsidian vaults. The project is maintained by Kepano (Stephan Ango) and distributed under the MIT License. With 42,252 GitHub stars and 3,012 forks, it represents one of the more widely adopted skill packs in the emerging agent-skills ecosystem.

The repository's significance lies in its standardization approach. Rather than building Obsidian integrations for each AI assistant separately, it follows a cross-platform specification that works with Claude Code, Codex, and OpenCode—three distinct agent frameworks with different configuration conventions. This abstraction layer means skills written once can propagate across the agent ecosystem without vendor-specific rewrites.

The project addresses a specific temporal inflection point: as AI agents move from chat interfaces to file-system operations, they need structured capabilities for formats beyond generic text. Obsidian's ecosystem—spanning flavored Markdown, proprietary .base files, JSON Canvas diagrams, and a dedicated CLI—represents a complex target that raw LLM prompting handles poorly. The skills provide deterministic, versionable instruction sets that constrain agent behavior to valid Obsidian syntax.

Notably, the repository's primary language is listed as "Unknown" in GitHub's classification, reflecting that the skills themselves are specification documents (SKILL.md files) and configuration rather than executable code in a traditional sense.

Key Features

The repository ships five distinct skills, each targeting a specific Obsidian capability:

obsidian-markdown — Full support for Obsidian Flavored Markdown, including wikilinks ([[ ]]), embeds (![[ ]]), callouts (> [!note]), YAML frontmatter properties, and other syntax extensions that diverge from CommonMark. This is the foundational skill; most vault operations require it.

obsidian-bases — Handles Obsidian Bases (.base files), a structured database format with views, filters, formulas, and summaries. This enables agents to perform CRUD operations on tabular data without flattening to Markdown tables or external spreadsheets.

json-canvas — Supports JSON Canvas (.canvas files), an open format for infinite canvas diagrams with nodes, edges, groups, and connections. Agents can generate visual knowledge maps, architecture diagrams, or relationship graphs programmatically.

obsidian-cli — Wraps the Obsidian CLI for vault-level operations including plugin and theme development workflows. This extends agent capabilities beyond file editing to vault management tasks.

defuddle — Integrates Defuddle for web content extraction, converting cluttered HTML to clean Markdown while stripping navigation, ads, and tracking elements. This reduces token consumption when agents process web-derived context.

The cross-platform compatibility is architectural, not incidental. Each skill follows the Agent Skills specification's directory structure (skills/<skill-name>/SKILL.md), enabling auto-discovery by compliant runtimes.

Use Cases

Automated knowledge base maintenance — A development team uses Obsidian as a living documentation system. With obsidian-skills, their Claude Code instance can update API endpoint documentation directly from source code changes, preserving wikilink integrity and frontmatter schema without human copy-editing.

Structured data workflows — A product manager maintains feature roadmaps in Obsidian Bases. The obsidian-bases skill lets an agent incrementally update status fields, recalculate priority scores from formulas, and generate filtered views for stakeholder reports—all within the .base format rather than exporting to CSV.

Visual system design — A software architect uses JSON Canvas to map microservice dependencies. The json-canvas skill enables an agent to generate updated topology diagrams from infrastructure-as-code definitions, maintaining node positioning and edge routing conventions.

Content pipeline ingestion — A researcher building a literature database uses the defuddle skill to strip academic publisher HTML to essential Markdown, then the obsidian-markdown skill to normalize citation formats and insert into a structured vault hierarchy.

Plugin development automation — A theme developer leverages obsidian-cli to script vault state for testing CSS changes across multiple configurations, using agent-driven regression checks.

Installation & Setup

The repository supports three installation paths, with manual configuration varying by agent platform.

Marketplace Installation

/plugin marketplace add kepano/obsidian-skills
/plugin install obsidian@obsidian-skills

This method is agent-agnostic within marketplace-compatible environments. The first command registers the repository as a skill source; the second installs the specific skill pack.

npx Installation

npx skills add git@github.com:kepano/obsidian-skills.git

For HTTPS preference:

npx skills add https://github.com/kepano/obsidian-skills

The npx skills CLI handles repository cloning and path resolution automatically, assuming Node.js and the skills CLI are installed globally.

Manual Installation

Claude Code:

Copy the repository contents to /.claude at your Obsidian vault root (or your configured Claude Code working directory). Refer to official Claude Skills documentation for path customization.

Codex:

Copy the skills/ directory to ~/.codex/skills/. The Agent Skills specification defines the expected format.

OpenCode:

Clone the full repository—not just the skills/ subdirectory:

git clone https://github.com/kepano/obsidian-skills.git ~/.opencode/skills/obsidian-skills

The directory structure must resolve to ~/.opencode/skills/obsidian-skills/skills/<skill-name>/SKILL.md. OpenCode auto-discovers all SKILL.md files under ~/.opencode/skills/ without configuration changes. Restart OpenCode after cloning.

Real Code Examples

The README provides installation commands as its primary code content. Below are the exact commands with operational context.

Example 1: Marketplace-based skill registration

/plugin marketplace add kepano/obsidian-skills

This command registers the GitHub repository as a trusted skill source in marketplace-enabled agents. The kepano/obsidian-skills identifier maps to the repository's release artifacts. After registration, individual skills become available for installation.

Example 2: Direct skill installation

/plugin install obsidian@obsidian-skills

The obsidian@ prefix scopes the installation to the skill pack namespace, preventing collision with other marketplace entries. This installs all five skills (obsidian-markdown, obsidian-bases, json-canvas, obsidian-cli, defuddle) as an atomic unit.

Example 3: npx-based HTTPS installation

npx skills add https://github.com/kepano/obsidian-skills

This alternative to SSH-based cloning avoids key management overhead. The npx execution model downloads the skills CLI if absent, then delegates to its add subcommand. The HTTPS transport is preferable in environments with restrictive egress rules or where GitHub SSH keys are not configured.

Example 4: OpenCode full-repository clone

git clone https://github.com/kepano/obsidian-skills.git ~/.opencode/skills/obsidian-skills

OpenCode's auto-discovery requires the full repository structure, including top-level metadata that may not exist in a subdirectory copy. The clone target path embeds the repository name (obsidian-skills) as a namespace directory, preventing collisions with other skill packs. The trailing path component is mandatory; omitting it would flatten skills into ~/.opencode/skills/skills/, breaking resolution.

The README does not provide operational examples of skill invocation (e.g., specific agent prompts or SKILL.md content). This reflects the specification-driven design: skill behavior is encapsulated in the SKILL.md files themselves, consumed by each agent's runtime rather than executed as standalone scripts.

Advanced Usage & Best Practices

Version pinning for reproducibility. The npx and manual installation methods clone the repository's default branch. For production vaults, consider pinning to a specific release tag or commit hash to prevent skill behavior drift. The MIT License permits local modification—fork if you need customized skill variants.

Skill granularity selection. Not all five skills are required for every workflow. If your vault uses only standard Markdown without Bases or Canvas, omitting obsidian-bases and json-canvas reduces agent context window consumption. Evaluate which skills your actual vault content requires.

Defuddle preprocessing for web content. The defuddle skill is compositional: use it upstream of obsidian-markdown when ingesting web-derived content. This two-stage pipeline (extract → normalize) yields cleaner results than direct Markdown conversion.

Vault backup before agent operations. Agent skills execute file modifications with the agent's permissions. While the specification constrains behavior to documented formats, complex vault structures may have edge cases. Version control (Git) or Obsidian's built-in snapshots provide recovery paths.

For teams standardizing on agent-assisted workflows, consider establishing vault conventions (frontmatter schemas, folder hierarchies) that align with skill assumptions. The skills handle syntax correctly, but semantic consistency improves agent output quality.

Comparison with Alternatives

Custom MCP servers offer flexibility but impose maintenance burden. Direct prompting is simplest for one-off tasks but scales poorly across team members or model changes. REST API plugins provide broad language support but introduce runtime dependencies. kepano/obsidian-skills occupies a middle ground: specification-governed, format-native, and agent-runtime-integrated without requiring Obsidian plugin installation for basic file operations.

FAQ

Which agents are compatible? Claude Code, Codex, and OpenCode per the README. Any agent implementing the Agent Skills specification should work.

Is Obsidian itself required? The skills manipulate Obsidian-native formats. Obsidian application use is optional for file operations but required for rendering .base and .canvas files.

What license applies? MIT License, permitting commercial use, modification, and distribution with attribution.

Can I use only specific skills? Yes. The repository structure supports selective installation, though marketplace and npx methods may install the full pack.

How current is the project? Last commit dated 2026-06-08 per repository metadata. Verify GitHub for subsequent activity.

Does this require programming knowledge? Installation requires command-line familiarity. Skill usage depends on your agent's interface—no direct coding required for basic operations.

Where are the SKILL.md specifications documented? The Agent Skills specification at agentskills.io/specification defines the format.

Conclusion

kepano/obsidian-skills addresses a specific, growing need: bridging AI agents with the rich, structured formats that power modern knowledge work in Obsidian. Its 42,252-star adoption signals developer demand for specification-based interoperability over fragmented, vendor-specific integrations.

The tool suits developers and technical teams already using Obsidian for documentation, research, or project management who want to extend agent capabilities without abandoning their vault-native workflows. It is less relevant for users of simpler note systems or those satisfied with copy-paste AI interactions.

The MIT License and open specification reduce lock-in risk. The primary limitation is documentation depth: operational examples beyond installation are sparse, requiring experimentation or community knowledge to exploit full capability.

To evaluate whether the skills match your workflow, clone the repository and inspect the SKILL.md files directly, or begin with the obsidian-markdown skill for basic Markdown operations. The project source and full documentation are available at https://github.com/kepano/obsidian-skills.