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 frontmatter

• name matches folder name

• description 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