OpenCode Skills: Paths, Frontmatter and Claude Skills
OpenCode skills explained: where OpenCode looks for SKILL.md files, the frontmatter it reads, how the agent loads skills and whether Claude skills work as is.
Josh Pocock7 min read
AI Coding
OpenCode skills
Stride AI Academy
OpenCode skills are Markdown instruction files, usually a folder with a SKILL.md inside, that the OpenCode agent can load when a task matches. OpenCode looks in its own .opencode/skills folders and also in .claude/skills and .agents/skills, both in your project and in your home directory. That means most skills you wrote for Claude Code show up in OpenCode without moving them.
This guide covers where OpenCode finds skills, the frontmatter fields it reads, how the model loads a skill, how to control skills with permissions and what to check before you reuse your Claude Code skills. Everything here was checked against OpenCode's skills docs, OpenCode's rules docs and Claude Code's skills docs on November 22, 2026. We wrote it from the docs and didn't run a separate test for this post.
What a skill is in OpenCode
A skill packages a repeatable workflow: instructions, plus optional supporting files like scripts or templates. OpenCode doesn't put every skill into the conversation up front. At each model step it shows the model a short list of the skills it's allowed to use, with only each skill's ID, name and description. The model then loads the full skill when it needs it.
This is the same idea Claude Code uses, so if you've already followed how to create Claude Code skills, the concepts carry over.
Where OpenCode looks for skills
Per the OpenCode skills docs, these are the skill locations:
| Scope | Paths |
|---|---|
| Global | ~/.config/opencode/skills, ~/.claude/skills, ~/.agents/skills |
| Project | .opencode/skills, .claude/skills, .agents/skills |
For project paths, OpenCode searches from your current directory up to the project root and includes matching folders at each level. So a monorepo can have skills at the root and inside a package folder.
You can also add more sources with a skills array in opencode.json or opencode.jsonc:
{
"skills": [
"./team-skills"
]
}Relative paths resolve from the active OpenCode working directory, ~/ resolves from your home folder, and an http:// or https:// URL loads a skill catalog over HTTP.
How files are discovered
The docs list a few rules for what counts as a skill:
- A plain Markdown file must sit at the source root, such as
skills/review.md. - A file named exactly
SKILL.mdcan be nested, such asskills/teams/release/SKILL.md. - A folder that contains
SKILL.mdcounts as one skill. OpenCode doesn't look inside it for more. - Hidden files, hidden folders and
node_modulesare skipped. - The search stops six folders below the source root.
Skill IDs come from the path
This one matters if you're used to Claude Code. In OpenCode, the file path sets the skill's ID, and the name field in the frontmatter is only a display label. For skills that also work elsewhere, the docs recommend a lowercase, hyphenated ID of 1 to 64 characters that matches the folder name:
^[a-z0-9]+(-[a-z0-9]+)*$The docs say the current version doesn't enforce that pattern, the length or a match between name and the folder. Following it anyway keeps your skills portable.
OpenCode skill frontmatter
All frontmatter fields are optional at runtime. These are the ones OpenCode reads:
| Field | What it does |
|---|---|
name |
Display name. Defaults to the ID from the path. |
description |
The summary the model sees. A skill without one isn't advertised to the model. |
disable-model-invocation |
Set to true to hide the skill from the model's list. |
metadata.opencode/autoinvoke |
Set to false for the same effect. If both are set, this one wins. |
OpenCode also accepts license and compatibility but doesn't act on them. A hidden skill stays registered, so you can still load it yourself.
Here's a minimal skill that works in both tools:
---
name: git-release
description: Prepare release notes, version bumps and GitHub releases. Use when the user asks to cut a release.
---
## Workflow
1. Read the commits since the last tag.
2. Group them into features, fixes and chores.
3. Draft release notes and propose the next version number.
4. Wait for approval before tagging.Save it as .claude/skills/git-release/SKILL.md and both Claude Code and OpenCode will find it.
How OpenCode loads a skill
When the model decides a skill fits, it calls the skill tool with the exact ID:
{"id": "git-release"}OpenCode then checks the agent's skill permission, adds the skill's Markdown body (without the frontmatter) to the conversation, and passes the skill's base folder plus up to ten supporting file paths. Supporting files aren't loaded automatically. The agent reads them only when the skill tells it to.
You can load a skill yourself by mentioning it in your prompt:
@git-release draft notes for the 2.4 releaseAllow, ask or deny skills with permissions
Skill permissions use the skill action with the skill ID as the resource, and the last matching rule wins. This example from the docs allows everything, blocks internal skills and asks before experimental ones:
{
"permissions": [
{ "action": "skill", "resource": "*", "effect": "allow" },
{ "action": "skill", "resource": "internal-*", "effect": "deny" },
{ "action": "skill", "resource": "experimental-*", "effect": "ask" }
]
}allowshows and loads matching skills with no prompt.askshows them but asks before loading.denyhides them and rejects loading.
To scope rules to one agent, put them under agents.<id>.permissions.
Do Claude Code skills work in OpenCode?
Mostly yes, because OpenCode reads .claude/skills and ~/.claude/skills directly. A few things to check before you rely on that:
Claude Code-only fields are ignored or behave differently. Claude Code's docs list fields that only Claude Code understands, such as context: fork, model, effort, hooks, paths and argument-hint. OpenCode's docs don't list these, so don't expect a skill that forks into a subagent or pins a model in Claude Code to do the same in OpenCode. The instructions in the body still load.
Invocation is different. In Claude Code you type /skill-name. In OpenCode you mention @skill-id, or let the model load it.
IDs can clash. If two locations define the same ID, the one registered later wins. The docs give this order, lowest to highest:
- Built-in skills
.claude/skills(global first, then folders toward your current directory).agents/skills(same order)~/.config/opencode/skills- Project
.opencode/skills - Explicit
skillsentries in your config
So a .opencode/skills/review skill overrides a .claude/skills/review skill with the same ID. That's handy when you want an OpenCode-specific version of one skill.
Scripts need to make sense to OpenCode. If a skill tells the agent to run a script with a Claude Code tool name or a Claude-specific path, rewrite that step in plain language ("run scripts/check.py") so either agent can follow it.
Turning off the .claude lookup
If you don't want OpenCode to read your Claude Code setup, the rules docs list two environment variables:
# Skip every CLAUDE.md file
export OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1
# Also skip .claude skills
export OPENCODE_DISABLE_CLAUDE_CODE=1The server reads them at start. If you run OpenCode as a background service, the docs say to persist them with opencode service set env and then run opencode service restart.
The same rules page says OpenCode reads AGENTS.md and falls back to CLAUDE.md in any folder that has no AGENTS.md. If you keep both tools on one project, our comparison of AGENTS.md vs CLAUDE.md covers how to share instructions.
Where to put skills if you use both tools
A simple setup that works for both agents:
- Shared skills in
.claude/skills/<id>/SKILL.md(or.agents/skills). Both tools read them. - OpenCode-only overrides in
.opencode/skills/<id>/SKILL.mdwith the same ID. - Plain instructions in the skill body, with any tool-specific fields treated as extras.
Still deciding between the two agents? See Claude Code vs OpenCode for features, models and cost, and the best AI coding agents for the wider field.
Learn to build with Claude Code
The Stride AI Coding course teaches Claude Code and Codex for building client tools, written for non-programmers, with weekly live calls to review your builds. Many of the free guides cover Claude Code setups, and the Claude Code community is where members compare theirs.
FAQ
Where does OpenCode look for skills?
Globally in ~/.config/opencode/skills, ~/.claude/skills and ~/.agents/skills. In a project it checks .opencode/skills, .claude/skills and .agents/skills from your current folder up to the project root. You can add more with a skills array in opencode.json.
Can OpenCode use my Claude Code skills?
Yes. OpenCode reads .claude/skills in your project and home folder, so skills there appear without copying. Claude Code-only frontmatter, like forking into a subagent, isn't listed in OpenCode's docs, so check those skills behave the way you expect.
What frontmatter does an OpenCode skill need?
None is required, but add a description. Without one, OpenCode doesn't advertise the skill to the model. name is only a display label, because the file path sets the ID.
How do I run a skill manually in OpenCode?
Mention it with @skill-id in your prompt, for example @git-release. The model can also load it on its own through the skill tool when a task matches the description.
How do I stop OpenCode reading my .claude folder?
Set OPENCODE_DISABLE_CLAUDE_CODE=1 to skip .claude skills, and OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1 to skip CLAUDE.md files. Restart OpenCode after setting them.