- name
- build-skill
- description
- Create effective skills for OpenCode agents. Load FIRST before writing any SKILL.md. Provides required format, naming conventions, progressive disclosure patterns, and validation. Use when building, reviewing, or debugging skills.
Building Skills
Skills extend agent capabilities with specialized knowledge, workflows, and tools.
Quick Start
Minimal viable skill in 30 seconds:
mkdir my-skill && cat > my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: Does X when Y happens. Use for Z tasks.
---
# My Skill
Instructions go here.
EOFPlace in .opencode/skills/ (project) or ~/.config/opencode/skills/ (global).
Skill Type Decision Tree
What are you building?
├─ Instructions only → Simple skill (SKILL.md only)
│ Example: code-review guidelines, commit message format
│
├─ Domain knowledge → Reference-heavy skill (+ references/)
│ Example: API docs, database schemas, company policies
│
├─ Repeatable automation → Script-heavy skill (+ scripts/)
│ Example: PDF processing, data validation, file conversion
│
├─ Complex multi-step workflow → Multi-file skill (all directories)
│ Example: release process, deployment pipeline
│
└─ Large platform → Progressive skill
Example: AWS, GCP, Cloudflare (60+ products)When to Create a Skill
Create a skill when:
- Same instructions repeated across conversations
- Domain knowledge model lacks (schemas, internal APIs, company policies)
- Workflow requires 3+ steps with specific order
- Code rewritten repeatedly for same task
- Team needs shared procedural knowledge
When NOT to Create a Skill
| Scenario | Do Instead |
|---|---|
| Single-use instructions | AGENTS.md or inline in conversation |
| Model already knows domain | Don't add redundant context |
| < 3 steps, no reuse | Inline instructions |
| Highly variable workflow | Higher-freedom guidelines |
| Just want to store files | Use regular directories |
Reading Order
| Task | Files to Read |
|---|---|
| New skill from scratch | anatomy.md → frontmatter.md |
| Optimize existing skill | progressive-disclosure.md |
| Add scripts/resources | bundled-resources.md |
| Find skill pattern | patterns.md |
| Debug/fix skill | gotchas.md |
In This Reference
| File | Purpose |
|---|---|
| anatomy.md | Skill directory structures |
| frontmatter.md | YAML spec, naming, validation |
| progressive-disclosure.md | Token-efficient design |
| bundled-resources.md | scripts/, references/, assets/ |
| patterns.md | Real-world skill patterns |
| gotchas.md | Common mistakes + fixes |
Scripts
| Script | Purpose |
|---|---|
scripts/init_skill.sh | Scaffold new skill |
scripts/validate_skill.sh | Validate skill structure |
scripts/package_skill.sh | Create distributable zip |
Pre-Flight Checklist
Before using a skill:
- [ ] SKILL.md starts with
---(line 1, no blank lines) - [ ]
name:field present, matches directory name - [ ]
description:includes what + when to use - [ ] Closing
---after frontmatter - [ ] SKILL.md under 200 lines (use references/ for more)
- [ ] All internal links resolve
Run: ./scripts/validate_skill.sh ./my-skill
Skill Locations
| Priority | Location |
|---|---|
| 1 | .opencode/skills/<name>/ (project) |
| 2 | ~/.config/opencode/skills/<name>/ (global) |
| 3 | .claude/skills/<name>/ (Claude-compat) |
Discovery walks up from CWD to git root. First-wins for duplicate names.
See Also
- Cloudflare Skill - Reference implementation