OpenCode skills: where OpenCode finds them and how they load

Where OpenCode looks

From OpenCode’s version 2 skills page:

In a project, OpenCode looks in each of those folders from the one you start in upward, so a monorepo can keep skills at its root and in each package. A source can hold a skill as a folder with a SKILL.md inside, which is the portable form, or as a single name.md file at its top level.

When two sources have a skill with the same ID, the one registered later wins, in this order from lowest to highest: OpenCode’s built-in skills, then .claude/skills/, then .agents/skills/ (in each, your home folder first and then the project from the outermost folder in), then ~/.config/opencode/skills/, then the project’s .opencode/skills/, then the skills array. One consequence surprises people: a skill in your personal ~/.config/opencode/skills/ overrides a skill of the same ID that a repository keeps in .agents/skills/ or .claude/skills/. OpenCode ships two skills of its own, opencode, for questions about OpenCode itself, and report, for filing a bug.

Writing one

The format is the open Agent Skills standard, and the portable version looks the same as for any agent:

.opencode/skills/release-notes/SKILL.md

---
name: release-notes
description: Drafts release notes from the merged pull requests since the last tag. Use when asked for release notes or a changelog entry.
---

1. Find the last tag with `git describe --tags --abbrev=0`.
2. List the merged pull requests since it with `gh pr list --state merged`.
3. Group them under Added, Changed and Fixed, one line each.

OpenCode 2 is looser than the standard, which is worth knowing if the skill will travel. The folder name is the skill’s ID, and the name field is only a label shown beside it, so OpenCode’s own docs give an example named “Git Release”, with a capital and a space. Every field is optional, but a skill without a description is never shown to the model. OpenCode reads four fields: name, description, disable-model-invocation and metadata, where opencode/autoinvoke: false does what disable-model-invocation does. It accepts license and compatibility without acting on them, and allowed-tools, which Claude Code uses to pre-approve tools, has no effect. For a skill other agents will read, keep to the standard: a lowercase-and-hyphens name that matches its folder, and a description that says what the skill does and when to use it.

How a skill loads

At each step OpenCode lists, for the model, the skills it is allowed to use that have a description: ID, name and description only, never the body. When the task matches, the model calls the skill tool with the ID, and OpenCode checks the agent’s permission, adds the body without its frontmatter to the conversation, and says where the skill’s folder is, with a sample of up to ten files in it. Files beside SKILL.md are read only when the instructions send the agent to them. In our run, asked “What is the probe-agents word?”, the model made one skill call with {"id":"probe-agents"} and answered from the instructions it got back, which began:

<skill_content name="probe-agents">
# Skill: probe-agents
...
Base directory for this skill: .../.agents/skills/probe-agents
Relative paths in this skill (e.g., scripts/, reference/) are relative to this base directory.

To load a skill yourself, mention it as @release-notes in your message. In OpenCode 2 skills are not slash commands; in version 1 every skill also became a /name command and was identified by its name field rather than its folder, which is the main thing to check when you move skills written for version 1.

Permissions, and switching one off

Skills have a permission action of their own, skill, with the skill’s ID as the resource. Rules go in the permissions array of opencode.json and run in order, the last match winning:

{
  "permissions": [
    { "action": "skill", "resource": "*", "effect": "allow" },
    { "action": "skill", "resource": "internal-*", "effect": "deny" },
    { "action": "skill", "resource": "deploy-*", "effect": "ask" }
  ]
}

allow lists and loads the skill without asking, ask lists it and asks before loading, and deny hides it from the model and refuses the tool call. Version 1 writes the same thing as a map, "permission": { "skill": { "internal-*": "deny" } }. The same rules under agents.<id>.permissions apply to one agent only, which is how you keep a review agent away from a deploy skill. To keep a skill out of the model’s list but usable when you name it, set disable-model-invocation: true. A skill grants no tools of its own: any command it tells the agent to run goes through the agent’s ordinary tools and their permissions.

Skills beside OpenCode’s other pieces

• AGENTS.md is guidance OpenCode loads in every session, from ~/.config/opencode/AGENTS.md and each AGENTS.md up the tree; a skill costs nothing until it is used. OpenCode 2 reads AGENTS.md only and, unlike version 1, no longer falls back to CLAUDE.md.
• Commands (.opencode/commands/review.md becomes /review) are prompts you type; skills are chosen by the model or mentioned with @. OpenCode’s docs warn that a command’s embedded shell blocks run when you invoke it, outside the agent’s permission checks; the commands a skill asks for go through them.
• Agents such as Build, Plan and your own in .opencode/agents/ don’t list skills; which skills each may use is its skill permission rules.
• Plugins can add, change or remove skills in code. Version 1 plugins don’t run in version 2.

One folder for OpenCode, Claude Code, Codex and Pi

Because OpenCode reads both .claude/skills/ and .agents/skills/, the arrangement that already serves Claude Code and Codex serves it too: keep the folder in .agents/skills/ and put a symlink to it in .claude/skills/.

mkdir -p .claude/skills
ln -s ../../.agents/skills/release-notes .claude/skills/release-notes

We checked it on October 9, 2026, with OpenCode 2.0.26, Claude Code 2.1.295, Codex 0.160.0 and Pi 1.1.0. First a repository with one probe skill in each of six folders: OpenCode loaded the ones in .opencode/skills/, .opencode/skill/, .claude/skills/ and .agents/skills/ and answered “skill not found” for .pi/skills/ and .codex/skills/; in a throwaway home folder it read ~/.agents/skills/, ~/.claude/skills/ and ~/.config/opencode/skills/. Then the shared setup: OpenCode listed the shared skill once, though it reached it through both folders, and used it; Claude Code and Codex found and used it; Pi listed it once we had trusted the folder, and listed no project skill at all before that. One more difference the test turned up, with a skill named “Display Probe” in a folder called display-probe: OpenCode showed it under the folder’s ID with the name as a label, Claude Code by the folder’s name, and Codex and Pi by the name as written, so Pi’s command for it became /skill:Display Probe. A name that follows the standard avoids all of that. What Agent Skills are has the full table of who reads what.

Before you use someone else’s

A skill is instructions your agent follows with your access, and often scripts it will run. OpenCode’s docs describe no step that asks you before a repository’s own skills load: open a cloned project and its .opencode/skills/, .claude/skills/ and .agents/skills/ are in play, as they were for Claude Code and Codex run non-interactively in our test. Read a skill and the files beside it before you run OpenCode where it lives, and use a deny or ask rule for any you are not sure of.