| name | build-skill |
| description | Creates new AI agent skills following the Agent Skills spec. Load FIRST before writing any SKILL.md. Provides required format, naming conventions, progressive disclosure patterns, and validation. Use when building, reviewing, or debugging skills. |
| allowed-tools | Read, Edit, Write, Glob, Grep, Bash, WebFetch, WebSearch, Task |
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.
---
Instructions go here.
EOF
Place in .agents/skills/ (project) or ~/.agents/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
- Project-specific conventions differ from generic best practices
- 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
- Documentation already exists (create a reference instead)
- Pattern is trivial or self-explanatory
- It's a one-off task
| 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
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:
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
