Share Claude Code skills with OpenCode, Hermes Agent and Pi from one folder

Our coding agents and our assistant were all loading their skills, and none of them was doing what the skills said. A voice skill could not open the voice file it pointed at, and a publishing skill could not find the SEO rules. When we went looking on 22 August, we found 413 SKILL.md files on one Mac, about 60 of them ours, spread across four agents with up to four copies of the same skill. This guide covers how to share Claude Code skills with OpenCode, Hermes Agent and Pi from one folder, and the silent failure that sent us looking.

Everything here was checked on our test machine, a 48 GB M4 Pro, with Pi 0.85.1 and the Hermes Agent and OpenCode builds current in September 2026.

Where Claude Code, OpenCode, Hermes Agent and Pi look for skills

All four agents read the same basic format: a folder containing a SKILL.md file that opens with a name and a description. Anthropic’s Agent Skills overview sets the limits. A name is at most 64 characters of lowercase letters, numbers and hyphens, and a description is at most 1,024 characters. The agent loads only the name and description at startup and reads the rest of the file when a request matches.

What differs is where each agent looks.

The Claude Code and OpenCode paths come from Anthropic’s overview and from OpenCode’s skills documentation. Hermes’s skills documentation calls ~/.hermes/skills/ “the primary directory and source of truth” and says its skills are compatible with the agentskills.io open standard. For Pi we used pi --help on version 0.85.1, which lists --skill <path> to “Load a skill file or directory (can be used multiple times)” and --no-skills to switch discovery off.

Most of Hermes’s 99 are not ours. Hermes ships its own set and adds to it, which is why its count is the highest.

How to share Claude Code skills with OpenCode without copying them

OpenCode reads Claude Code’s folder directly. Its documentation lists ~/.claude/skills/*/SKILL.md among its global search paths, so a skill placed there is picked up by both agents with nothing copied and nothing linked.

That makes ~/.claude/skills/ the natural shared location for these two. A skill you keep in ~/.config/opencode/skills/ is invisible to Claude Code, while one in ~/.claude/skills/ works in both.

We keep the canonical copy of every skill in one library folder, ~/Documents/skills/active/, which holds 37 skills. From there a skill can be placed in ~/.claude/skills/ as a symbolic link, so editing the library edits what both agents load:

ln -s ~/Documents/skills/active/brief ~/.claude/skills/brief

The descriptions are what every agent carries into each session, so their length matters more than the length of the skill. Across our 37 skills the descriptions total 15,702 characters, and the longest is 960, inside Anthropic’s 1,024 limit. The bodies are much larger: the median skill body is 5,036 characters and the largest is 40,999, but a body costs nothing until the agent opens it.

Our brand voice setup across OpenCode, Hermes and Pi predates this library and used instruction files instead of skills. The two approaches sit together: instruction files load every session, and skills load on demand.

How to load the same skills in Hermes Agent and Pi

Hermes does not read ~/.claude/skills/. It has its own folder and a setting for extra folders. Its documentation describes skills.external_dirs in config.yaml for pointing Hermes at directories outside ~/.hermes/skills/, which lets it read the same library.

Hermes also runs a curator that tidies skills on a schedule. Our config has it enabled with stale_after_days: 30, archive_after_days: 90 and interval_hours: 168. On 4 September we copied two skills into ~/.hermes/skills/stridenote/ and noted that the curator could remove them if they went unused, so any copy placed there needs checking after a month. A library folder listed in external_dirs avoids copying in the first place.

Pi has the least automatic discovery of the four. We found no global skills folder documented, so we pass skills explicitly, and we point the flags straight at the library rather than at a copy. The shell function in our ~/.zshrc runs on every Pi session:

pi() {
  lmstudio-ensure-ctx
  command pi \
    --skill ~/Documents/skills/active/ai-bug-patterns \
    --skill ~/Documents/skills/active/thermo-nuclear-code-quality-review \
    "$@"
}

The first line is a small script of ours that makes sure LM Studio has the model loaded at the context window Pi needs before Pi starts. The two --skill flags read the canonical files, so an edit in the library reaches Pi on its next session with nothing to copy.

Pi’s context files follow different rules from its skills. Pi reads AGENTS.md when a session starts, and its /reload command does not re-read it, so an edited instruction file needs a new session.

What broke when we moved our skills folder: 106 dead paths

The failure that started this was not in any agent. We had renamed a folder, Stride Note to Stridenote, and moved several project folders into a new parent. Our skills referred to files by path, and the paths no longer existed.

A scan found 106 dead path references across 27 skill files. The voice skill could not load its voice guide, the publishing skill could not find the SEO rules and the brand skill could not find the brand guide. Every one of those skills still loaded without error. The agent read the skill, followed the instruction to open a file, found nothing, and carried on without the rules. No error appeared anywhere, so nothing looked wrong.

The same move broke OpenCode’s global instructions. ~/.config/opencode/AGENTS.md was a symbolic link to the old folder, so OpenCode loaded no global instructions at all until the link was pointed at the new location.

Duplication made it harder to see. The survey found 80 of our own files but only 71 distinct contents, and one skill for a client publication existed as four byte-identical copies in four places. Hermes’s usage log showed that of 77 tracked skills only 13 had ever been used, and only one of those, our article-writing skill, was ours, with 10 uses.

Nine copied files also held a WordPress application password in plain text. In the library those are replaced with an environment variable, but the originals kept the value, which is worth a search before any skills folder goes into version control.

Two checks would have caught all of this. After any folder rename, search every SKILL.md for the old path. When a skill appears to do nothing, confirm the files it names still open before rewriting its instructions. We treat an agent that fails quietly the same way as in our guide to background agents that fail silently: the absence of an error is not evidence that anything worked.

Skills and MCP servers solve different problems, and a shared skills folder does nothing for tools an agent calls over MCP. That split is set out in agent skills vs MCP. What a shared folder does fix is the drift: one canonical file, read by four agents, means a path repaired once is repaired everywhere.