Agent Skills: skill-authoring

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

1. Pick a skill name that matches ^[a-z0-9]+(-[a-z0-9]+)*$ and is 1–64 chars.
2. Create .opencode/skill/<name>/SKILL.md and ensure the folder matches the name.
3. Add YAML frontmatter with name and description (optional: license, compatibility, metadata).
4. Write the body with clear sections (Purpose/What I do, When to use, Workflow, Completion criteria).
5. Confirm discovery: run OpenCode in the repo and check skill tool list.
6. 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