OpenCodeAgent SkillsSKILL.mdNbility

Build OpenCode Skills That Load When Needed

OpenCode Skills advertise an ID and description before loading SKILL.md. Learn discovery paths, duplicate precedence, and the difference between hiding and denying a skill.

Build OpenCode Skills That Load When Needed

An OpenCode Skill stores a procedure that is useful for a particular kind of task. V2 first shows the model permitted skills' IDs, names, and descriptions. The body is loaded through the skill tool when needed. A file existing on disk does not establish that every conversation has read it.

This article checks the current Skills guide against the v2.3.2 source on November 21, 2026. The example is a public, non-mutating review procedure. No complete OpenCode model task was run for this article.

What belongs in a skill?

Keep everyday project conventions in persistent instructions such as AGENTS.md. Put specialized release checks, reviews, and migration procedures in skills. The instructions and skills explainer covers this division.

A rule against committing credentials should not depend on an optional skill being invoked. Actual access also needs permission controls. Loading instructions does not grant tools new authority.

Create this demonstration structure:

.opencode/skills/review-public/
├── SKILL.md
└── references/
    └── checklist.md

Use this entry file:

---
name: review-public
description: Review a public demo change and report correctness risks without editing files
---

Read `references/checklist.md` relative to this skill directory.
Inspect the user-specified diff without changing files or running commands.
Report each supported finding with a file reference and a concrete failure case.
If evidence is insufficient, state what remains unverified.

The checklist can ask concrete questions such as what happens with empty input and whether errors reach the caller. Use public examples. The description explains when the procedure is useful; the body explains how to perform it.

Where does OpenCode discover skills?

V2 searches ~/.config/opencode/skills, compatible global and project .claude/skills and .agents/skills directories, and project .opencode/skills. Project discovery walks from the current directory to the project root and includes matching directories along the way.

Global, compatibility, and project sources contribute definitions selected by ID

The ID comes from the path, not the frontmatter display name:

PathID
.opencode/skills/review-public/SKILL.mdreview-public
.opencode/skills/teams/review-public/SKILL.mdreview-public
.opencode/skills/review-public.mdreview-public

Grouping directories do not automatically create namespaces. Two teams' release/SKILL.md files can collide on release. IDs are case-sensitive; unique lowercase kebab-case names are a practical portability choice.

Hidden entries and node_modules are skipped. Discovery does not search for more skills inside a directory that already contains SKILL.md, and traversal has a depth limit. Reduce a missing skill to the simple structure above before investigating more elaborate layouts.

Why does an old definition keep loading?

Later registered sources win for the same ID. The documented order includes built-ins, .claude/skills, .agents/skills, the global OpenCode directory, project .opencode/skills, and explicit skills entries. Ancestor order and array order also matter within those groups.

Additional sources can be declared as:

{
  "$schema": "https://opencode.ai/config.json",
  "skills": ["./team-skills"]
}

That relative path resolves from OpenCode's active working directory, not the configuration file. Entries from multiple configuration files combine. A global ./team-skills entry can therefore resolve differently when the launch directory changes.

Inventory every definition of the ID, reduce to one public demonstration definition, and restore sources deliberately. Changing a display name alone does not resolve an ID collision.

Does hiding a skill prevent loading it?

No. metadata.opencode/autoinvoke: false omits the skill from the model's advertised list while keeping it registered for explicit loading. disable-model-invocation: true has a similar effect; opencode/autoinvoke takes precedence when both appear.

Advertised skills, explicit-only skills, and permission-denied skills have different loading behavior

To restrict loading, use permissions:

{
  "permissions": [
    { "action": "skill", "resource": "*", "effect": "deny" },
    { "action": "skill", "resource": "review-public", "effect": "allow" }
  ]
}

This denies all skills before allowing one exception. The last match wins. The same rules can live under agents.<id>.permissions for a specific agent.

Issue #63455 requests UI controls for enabling and disabling skills. It remained open with two replies when checked. Its bot response points to configuration controls corroborated by the official guide; the request does not establish that a unified management interface has shipped.

How can you verify actual loading?

In a public demonstration project, ask:

Use @review-public to review the public diff I specify.
First identify the loaded skill ID and directory, then apply its checklist.
Do not edit files or run commands.

Check that the actual skill call loads review-public, then verify that references/checklist.md was read. Directory skills provide a base path and a sample of supporting paths, not the contents of every reference file. Repeating the advertised description does not demonstrate that the full workflow ran.

Check the path and ID, description and permissions, actual load, and reference-file access

For a missing skill, check the exact SKILL.md filename, path-derived ID, description, advertisement settings, current agent permissions, and duplicate definitions. If the model request fails, use the connection checks before blaming discovery. Save completed work in a form that remains useful after context compaction.

Related posts

Run your Agent workflow through Nbility

Get an API key and connect OpenAI-compatible models and developer tools from one place.

Get an API key