What I do
- Define the steps and checks for adding a new OpenCode skill
- Ensure the skill is discoverable by the
skill tool - Validate naming, frontmatter, and placement rules
When to use
- Adding a new reusable workflow or playbook as a skill
- Updating skill metadata to meet OpenCode discovery requirements
Workflow
- Pick a skill name that matches
^[a-z0-9]+(-[a-z0-9]+)*$ and is 1–64 chars. - Create
.opencode/skill/<name>/SKILL.md and ensure the folder matches the name. - Add YAML frontmatter with
name and description (optional: license, compatibility, metadata). - Write the body with clear sections (Purpose/What I do, When to use, Workflow, Completion criteria).
- Confirm discovery: run OpenCode in the repo and check
skill tool list. - If permissions block it, update
opencode.json with permission.skill rules.
Placement rules (from opencode.ai docs)
- Project:
.opencode/skill/<name>/SKILL.md - Project (Claude compatible):
.claude/skills/<name>/SKILL.md - Global:
~/.config/opencode/skill/<name>/SKILL.md - Global (Claude compatible):
~/.claude/skills/<name>/SKILL.md
Validation checklist
SKILL.md is all caps and contains YAML frontmattername matches folder namedescription is 1–1024 characters- No duplicate skill names in the repo
Example
---
name: git-release
description: Create consistent releases and changelogs
compatibility: opencode
---
## What I do
- Draft release notes from merged PRs
- Propose a version bump
- Provide a `gh release create` command
Completion criteria
- Skill appears in
skill tool list skill({name}) loads without errors- Instructions are clear enough to execute without extra context
