OpenCode skills. Where they live and how to install them.

What skills are in OpenCode

OpenCode discovers reusable instructions from SKILL.md files in your repository or home directory. The agent sees a list of available skills, each with a name and description, inside the description of a native skill tool. When a task fits, the agent calls the tool, for example skill({ name: "git-release" }), and the full content loads then. Skills therefore stay out of the context until they are needed.

OpenCode recognises only these frontmatter fields: name and description (both required), plus optional license, compatibility and metadata (a string-to-string map). Unknown fields are ignored, so a skill written for another agent still loads, though extras such as allowed-tools have no effect here.

Where OpenCode looks for skills

For project locations, OpenCode walks up from the current working directory until it reaches the git worktree root. It loads matching skill folders in .opencode/, .claude/ and .agents/ along the way. Skill names must be unique across all of these locations.

Install a skill

OpenCode's documentation describes placing files rather than any install command, so installation goes through a separate tool or a manual copy. The examples use frontend-design from anthropics/skills, located at skills/frontend-design.

Option 1: the skills CLI

npx skills add anthropics/skills --skill frontend-design -a opencode

This installs into .agents/skills/ in the current project. Add -g for a global install into ~/.config/opencode/skills/.

Option 2: GitHub CLI

gh skill install anthropics/skills frontend-design --agent opencode
gh skill install anthropics/skills frontend-design --agent opencode --scope user

Needs GitHub CLI 2.90.0 or later, where gh skill is a public preview.

Option 3: copy the folder

git clone --depth 1 https://github.com/anthropics/skills.git skills-src
mkdir -p .opencode/skills
cp -r skills-src/skills/frontend-design .opencode/skills/frontend-design
rm -rf skills-src

Use ~/.config/opencode/skills/ for a global install.

Check that it loaded

Ask OpenCode which skills it can use, or ask it to perform a task that matches the skill's description. OpenCode lists the available skills with their names and descriptions in the skill tool, so the agent can tell you what it sees. If the skill is missing, work through the checks below.

Update and remove

• Remove: delete the skill folder, or run npx skills remove frontend-design.
• Update: run npx skills update, or gh skill update for skills installed with gh, or copy a newer version of the folder over the old one.
• Hide a skill without deleting it: set it to deny in opencode.json, as shown below.

Control which skills the agent can use

Permissions live in opencode.json under permission.skill. Each pattern maps to allow (loads immediately), deny (hidden from the agent) or ask (you are prompted first). Wildcards work:

{
  "permission": {
    "skill": {
      "*": "allow",
      "internal-*": "deny",
      "experimental-*": "ask"
    }
  }
}

You can override the defaults per agent, and setting tools.skill to false for an agent turns skills off for it entirely.

Troubleshooting

• Check the filename is spelled SKILL.md in capitals.
• Check the frontmatter has both name and description, and that the name matches the folder name exactly. Names must match ^[a-z0-9]+(-[a-z0-9]+)*$ and be at most 64 characters, with no leading, trailing or doubled hyphens.
• The description must be 1 to 1024 characters.
• Make sure names are unique across every location. A duplicate in .claude/skills and .opencode/skills is a conflict.
• Check your permission.skill rules: a skill set to deny is hidden from the agent.

Safety

A skill can instruct the agent to run commands and edit files, and the agent does that with your account's permissions. Read SKILL.md and any bundled scripts before installing. If you use third-party skills regularly, ask rules in permission.skill give you an approval step before a skill loads, which is a useful default for names you have not reviewed.