Create, test, and improve OpenCode skills. Use this skill when the user wants to make a new skill, edit an existing skill, optimize a skill description, or understand how skills work. Also use when the user mentions "create a skill", "make a skill", "skill doesn't trigger", "improve my skill", "test my skill", or "write a SKILL.md". Apply this skill whenever configuring OpenCode skills, skills directory, .opencode/skills, skill frontmatter, or Agent Skills spec.
Skills are folders with a SKILL.md file containing instructions that OpenCode
loads dynamically. The workflow: decide what the skill does, write the
SKILL.md, test with realistic prompts, evaluate and improve based
on feedback, repeat until satisfied.
skill-name/
└── SKILL.md # Required: metadata + instructions
Optional directories for larger skills:
skill-name/
├── SKILL.md # Required
├── scripts/ # Optional: executable code
├── references/ # Optional: documentation
└── assets/ # Optional: templates, resources
Do NOT include a README.md inside the skill folder. All documentation
belongs in or . A README is only appropriate at the
repository level when distributing skills via GitHub.
SKILL.mdreferences/Each SKILL.md must start with YAML frontmatter followed by Markdown content.
| Field | Required | Description |
|---|---|---|
name | Yes | Skill identifier (1-64 chars, lowercase alphanumeric with hyphens) |
description | Yes | What the skill does and when to use it (1-1024 chars) |
license | No | License name or reference |
allowed-tools | No | Restrict which tools the skill can use (e.g., "Bash(python:*) WebFetch") |
compatibility | No | Environment requirements (max 500 chars) |
metadata | No | Key-value map for additional data |
---