How OpenCode skills load, and how to control them

What are OpenCode skills?

OpenCode skills are reusable instructions stored as SKILL.md files. OpenCode lists the available ones to the agent by name and description, and the agent loads a skill’s full text on demand through a native skill tool. You can put them in .opencode/skills/ or .agents/skills/ in a project, or in ~/.config/opencode/skills/ for every project. Or run npx skills add owner/repo -a opencode.

OpenCode also reads the Claude Code and agent-compatible folders, so skills you already have may load without copying. Of the 195 repositories we have reviewed, 61 say they support OpenCode.

Where OpenCode searches for skills

The OpenCode skills docs list six locations, each holding <name>/SKILL.md:

• .opencode/skills/ in the project, and ~/.config/opencode/skills/ globally
• .claude/skills/ in the project, and ~/.claude/skills/ globally
• .agents/skills/ in the project, and ~/.agents/skills/ globally

For project paths, OpenCode walks up from your working directory to the git worktree root and loads matching skills along the way. Skill names must be unique across all locations.

SKILL.md rules in OpenCode

The frontmatter requires name and description (1 to 1,024 characters). license, compatibility and a string-to-string metadata map are optional, and unknown fields are ignored. Names are 1 to 64 characters of lowercase letters and digits with single hyphens, matching the regex ^[a-z0-9]+(-[a-z0-9]+)*$, and they must match the folder name. In OpenCode 1, metadata does not control slash commands or automatic skill selection.

If a skill doesn’t appear, the docs give four checks: the file is named SKILL.md in capitals, the frontmatter has both required fields, the name is unique, and no permission rule denies it. A skill set to deny is hidden from the agent entirely.

Two details trip people up. First, the folder name must equal the name field, so a cloned pack whose folders are named differently will not load until you rename them. Second, because OpenCode walks up to the git worktree root, a skill in a parent folder of a monorepo also applies in the subfolders below it. If a skill loads when you didn’t expect it, check the parent directories.

Installing OpenCode skills

With the skills CLI, from the project root:

npx skills add owner/repo -a opencode
npx skills add owner/repo -a opencode -g

The first writes to .agents/skills/. With -g, the skill goes to ~/.config/opencode/skills/. Both are folders OpenCode searches. You can also copy a skill folder into any of the six locations by hand. Our guide to installing skills covers the same steps for Claude Code.

A minimal skill

---
name: git-release
description: Draft release notes and a version bump from merged pull requests
---
List the merged pull requests since the last tag, group them by type,
and draft release notes. Ask before tagging or pushing.

Save it as .opencode/skills/git-release/SKILL.md. The folder name matches the name field, which OpenCode requires. The agent sees “git-release” and its description in the skill tool’s list and calls skill({ name: "git-release" }) when a task fits.

Sharing skills with Claude Code

Because OpenCode also searches .claude/skills/ and ~/.claude/skills/, one set of skills can serve both agents. The catch is the uniqueness rule: names must be unique across all locations, so the same skill copied into both .claude/skills/ and .agents/skills/ is a duplicate to clean up. Pick one home for each skill. If you use several agents, .agents/skills/ is the project folder that Codex, Cursor, OpenCode and Gemini CLI all read.

Controlling skills with permissions

OpenCode lets you decide in config which skills an agent may load. Rules go under permission.skill in opencode.json, matched by name pattern:

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

allow loads the skill immediately, deny hides it and rejects access, and ask prompts you before it loads. Wildcards work. Custom agents can set their own permission.skill in their frontmatter, and built-in agents take agent.<name>.permission.skill in opencode.json. To remove skills from an agent altogether, set tools.skill: false (or agent.<name>.tools.skill: false), and the <available_skills> section disappears from its prompt.

A sensible starting point for untrusted packs is "*": "ask", then allow the skills you have read. That way an unfamiliar skill can’t load without a prompt. The permission covers loading a skill, not what its scripts later do, so it doesn’t replace reading them.

The same mechanism works per agent. A read-only plan agent, for example, can get its own rule that hides internal skills, while your build agent keeps the defaults. If an agent should never use skills at all, turning the tool off is simpler than writing rules.

Which OpenCode skills to start with

Among the 61 repositories that list OpenCode, none were free of notes in our review: 35 are marked “review before installing” and 26 “broad access”. Two examples:

• kepano/obsidian-skills is Markdown only and written by the people who maintain the Obsidian formats. It drives separate command-line tools that we did not review. Verdict: install.
• addyosmani/web-quality-skills is MIT-licensed audit guidance for performance, accessibility and SEO, with one local shell script. It was last pushed in August. Verdict: install.

The best skills page ranks the full directory, and the security checklist applies here as anywhere. The pack list below is filtered to repositories that mention OpenCode.