---

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:

Copymkdir 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

CopyWhat 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