- Bump every version pin, pricing table, and model ID to the verified 2026-07-05 state (v1.17.13): Claude Fable 5 / Sonnet 5 on Zen, new free tier, deprecation sunset table, v1.17.x changelog section - Cover gaps: OpenCode Go vs Zen billing, Anthropic subscription-login removal (PR #18186), MCP resources, --mini mode, --auto flag, yolo mode - Fix correctness bugs: command-template !`cmd` syntax in docs and .opencode/commands, protect-secrets regex missing 'cat .env', dual plugin exports, quickstart PATH fix, Playwright MCP flags, ctrl+d keybind conflict, agent/command required-field claims - Fix links: cursor.com, windsurf.com, platform.claude.com, code.claude.com, opencode.ai/discord, Vercel Grep announcement - Rebrand: banner (Images/banner.svg), 1280x640 social preview asset, hero redesign with star CTA, ecosystem stats, private vulnerability reporting channel, CI-matching local checks, MD060 lint opt-out
6.5 KiB
Agent Skills
Mental model: A skill is a discoverable workflow. The agent sees the skill's
nameanddescriptionin its tool surface and decides on its own to load the full content when the task matches. You don't have to remember to invoke it — the model does.
Skill vs. Command — when to use which
| Agent Skill | Custom Command | |
|---|---|---|
| Trigger | Agent decides (description match) | User types /<name> |
| File | .opencode/skills/<name>/SKILL.md (folder) |
.opencode/commands/<name>.md (file) |
| Best for | "When you're doing X, here's how" expertise | Repeatable user-driven actions |
| Discoverable | Yes — surfaces as a tool | Yes — in slash palette |
A great heuristic: write a skill when the workflow has a natural trigger ("when preparing a release", "when reviewing a payment-related change"). Write a command when the user is the one who knows it's time.
File format
A skill is a folder named after the skill, containing a SKILL.md:
.opencode/skills/
└── git-release/
├── SKILL.md # required
└── ... # optional resources the skill references
SKILL.md:
---
name: git-release
description: Draft release notes from merged PRs, propose a semver bump, and emit a copy-pasteable `gh release create` command. Use when preparing a tagged GitHub release.
license: MIT
compatibility: opencode
metadata:
audience: maintainers
workflow: github
---
## What I do
- Read merged PRs since the last tag
- Group by feat/fix/other
- Propose a semver bump (major / minor / patch)
- Emit Keep-a-Changelog-style notes
- Print a ready-to-run `gh release create` command
## When to use me
Use this when preparing a tagged release. Ask the user to confirm the
version bump before doing anything destructive.
## What I won't do
- Push tags or publish releases without confirmation
- Edit files
- Hallucinate changelog entries
Frontmatter rules
| Key | Required | Constraints |
|---|---|---|
name |
yes | ^[a-z0-9]+(-[a-z0-9]+)*$, 1–64 chars — lowercase alphanumeric with single hyphens. Must match the folder name that contains SKILL.md. |
description |
yes | 1–1024 chars. This is the discovery signal — write it carefully. |
license |
no | SPDX identifier ideal |
compatibility |
no | Open-ended string — e.g. opencode |
metadata |
no | String-to-string map (keys and values are both strings) |
Why the description matters
The description is what the model reads when deciding whether to load the skill. Bad descriptions don't get loaded:
# 👎 Vague
description: Helps with releases
# 👍 Specific, trigger-shaped
description: Draft release notes from merged PRs, propose a semver bump, and emit a `gh release create` command. Use when preparing a tagged GitHub release.
Anatomy of a good description:
- What it does (verb-first)
- What it produces (concrete output)
- When to use it (trigger phrase)
Where skills live
OpenCode searches six locations — three project-local, three global:
| Location | Scope |
|---|---|
.opencode/skills/<name>/SKILL.md |
Project |
.claude/skills/<name>/SKILL.md |
Project — Claude Code compatibility |
.agents/skills/<name>/SKILL.md |
Project — Agent-format compatibility |
~/.config/opencode/skills/<name>/SKILL.md |
Global |
~/.claude/skills/<name>/SKILL.md |
Global — Claude Code compatibility |
~/.agents/skills/<name>/SKILL.md |
Global — Agent-format compatibility |
For the project paths, OpenCode traverses upward from the working directory to the git worktree root, so a skill in a parent folder is still found. Same-named skills resolve project-first.
Permissions
Skills are gated by the skill permission. Three values plus glob patterns:
{
"permission": {
"skill": {
"*": "allow",
"pr-review": "allow",
"internal-*": "deny",
"experimental-*": "ask"
}
}
}
| Value | Behavior |
|---|---|
"allow" |
Skill loads silently when the agent decides to |
"ask" |
User must approve each load |
"deny" |
Skill is hidden from the agent's surface |
To disable skills entirely for an agent:
{
"agent": {
"build": {
"tools": { "skill": false }
}
}
}
Writing skills the model will actually use
The hardest part is getting the agent to find your skill. Tips:
- Trigger phrases in the description. "Use when preparing a release", "Use for any payment-related change", "Use when generating release notes".
- Be concrete about output. Models load skills more readily when the description names a specific artifact they can produce.
- One skill, one job. Don't bundle "release notes + version bump + deploy" — the description gets vague and load decisions get muddled.
- Test discovery. Ask your agent something the skill should handle without naming the skill. If it doesn't pull it in, refine the description.
Patterns
Procedure skill
The skill carries the exact procedure for a recurring task.
name: bump-dependency
description: Safely upgrade a single dependency — runs typecheck, tests, and changelog scan to surface breaking changes. Use when the user asks to update a specific package.
Body: step-by-step procedure, including which commands to run and how to interpret output.
Convention skill
The skill encodes domain conventions for a specific area of the codebase.
name: payment-handler
description: How to safely modify payment-handler code. Use when editing anything under packages/payments/. Encodes our idempotency, refund, and webhook conventions.
Body: conventions and rules — what to do, what not to do, with code examples.
Tool-bridge skill
The skill explains how to use an external CLI or service the agent should discover.
name: argo-rollout
description: Use Argo CD to roll out staging deployments. Use when the user wants to deploy a branch to staging. Wraps the `argocd` CLI.
Body: CLI invocation, common flags, what success and failure look like.
Compatibility with Claude Code
A skill in .claude/skills/ works in both tools — OpenCode searches that path (see the table above), and Claude Code reads it natively. The sharing comes from the search path, not the compatibility value. Useful for teams running both.
📚 Full Skills guide: opencode.ai/docs/skills.
Last reviewed: 2026-07-05 · Canonical source: opencode.ai/docs/skills.