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

Reading Order

In This Reference

Scripts

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

Discovery walks up from CWD to git root. First-wins for duplicate names.

See Also

• Cloudflare Skill - Reference implementation