Files
Wesam Abousaid a3f328c043 docs: refresh for OpenCode v1.17.13, add Go coverage, and rebrand
- 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
2026-07-05 14:11:51 +02:00

6.5 KiB
Raw Permalink Blame History

Agent Skills

Mental model: A skill is a discoverable workflow. The agent sees the skill's name and description in 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:

  1. Trigger phrases in the description. "Use when preparing a release", "Use for any payment-related change", "Use when generating release notes".
  2. Be concrete about output. Models load skills more readily when the description names a specific artifact they can produce.
  3. One skill, one job. Don't bundle "release notes + version bump + deploy" — the description gets vague and load decisions get muddled.
  4. 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.