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. EOF

Place 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