How to Manually Install Obsidian Skills for OpenCode: Complete Setup Guide

Clone the kepano/obsidian-skills repository into ~/.opencode/skills/obsidian-skills and restart OpenCode to auto-discover all Obsidian capabilities.

The kepano/obsidian-skills repository provides a comprehensive collection of Agent Skills that enable OpenCode to understand and manipulate Obsidian-specific formats including Markdown, Canvas files, and Bases. To manually install obsidian skills for OpenCode, you must clone the entire repository structure into OpenCode's designated skills directory rather than copying individual skill folders.

Step-by-Step Manual Installation

Clone the Repository to the Skills Directory

OpenCode discovers Agent Skills by scanning the ~/.opencode/skills/ directory for SKILL.md files. Execute the following command to clone the complete repository into the correct location:

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

Verify the Directory Layout

After cloning, confirm that the repository structure matches OpenCode's expectations. The loader requires SKILL.md files to reside under <skill-root>/skills/<skill-name>/ according to the repository's installation guidelines.

tree ~/.opencode/skills/obsidian-skills

Expected structure:

~/.opencode/skills/obsidian-skills/
├── README.md
├── LICENSE
└── skills/
    ├── obsidian-markdown/
    │   └── SKILL.md
    ├── obsidian-bases/
    │   └── SKILL.md
    ├── json-canvas/
    │   └── SKILL.md
    ├── obsidian-cli/
    │   └── SKILL.md
    └── defuddle/
        └── SKILL.md

Restart OpenCode to Activate

Once the files are in place, restart OpenCode or reload the skill list. No modifications to opencode.json or other configuration files are necessary. As documented in the repository's README.md, the system automatically walks the directory tree, loads every SKILL.md, and registers the skill set without requiring manual configuration changes.

Why You Must Clone the Entire Repository

According to the README.md in the kepano/obsidian-skills repository, copying only the inner skills/ directory breaks the relative path resolution that OpenCode expects. The installation requires the full repository at ~/.opencode/skills/obsidian-skills/ so that the nested skills/ subdirectory maintains the correct depth in the file hierarchy. This ensures paths like ~/.opencode/skills/obsidian-skills/skills/obsidian-markdown/SKILL.md resolve correctly during the discovery phase.

Available Obsidian Capabilities

Once installed, OpenCode gains access to five specialized skills defined in their respective SKILL.md files:

• obsidian-markdown: Handles wikilinks, embeds, callouts, and YAML front-matter as implemented in skills/obsidian-markdown/SKILL.md
• obsidian-bases: Provides commands for working with .base files and database-style queries
• json-canvas: Enables creation and editing of .canvas files for visual note mapping
• obsidian-cli: Interfaces with the Obsidian CLI for plugin and theme development workflows
• defuddle: Wraps the Defuddle CLI to extract clean Markdown from web pages

Verification Steps

Confirm successful installation by listing available skills:

opencode skills list

The output should include obsidian-markdown, obsidian-bases, json-canvas, obsidian-cli, and defuddle. Alternatively, invoke help within the OpenCode interface to see the new commands registered under these skill names.

Summary

• Clone location: Must be ~/.opencode/skills/obsidian-skills/, not just the inner skills/ folder
• Discovery mechanism: OpenCode automatically scans for SKILL.md files under the skills directory without configuration changes
• Repository structure: The full kepano/obsidian-skills repository is required to maintain correct relative paths
• Activation: Restart OpenCode after cloning to load obsidian-markdown, obsidian-bases, json-canvas, obsidian-cli, and defuddle capabilities
• Verification: Use opencode skills list to confirm the five Obsidian skills are registered

Frequently Asked Questions

Can I copy only the skills folder instead of cloning the entire repository?

No. The README.md explicitly warns that copying only the inner skills/ directory breaks the path resolution required by OpenCode's loader. The system expects the repository root at ~/.opencode/skills/obsidian-skills/ with the nested skills/ subdirectory containing individual skill folders.

Do I need to edit opencode.json to register these skills?

No configuration changes are required. OpenCode's loader recursively searches ~/.opencode/skills/ for SKILL.md files and automatically registers them based on the YAML front-matter containing name and description fields parsed from each skill definition.

Where are the SKILL.md files located within the repository?

Each skill's definition file resides in skills/<skill-name>/SKILL.md. For example, the Markdown skill definitions are in skills/obsidian-markdown/SKILL.md, while the Canvas capabilities are defined in skills/json-canvas/SKILL.md.

How do I update the Obsidian Skills after installation?

Navigate to the skills directory and pull the latest changes:

cd ~/.opencode/skills/obsidian-skills
git pull origin main

Then restart OpenCode to load any updated skill definitions.

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