Agent skill
build-skill
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.
Install this agent skill to your Project
npx add-skill https://github.com/dmmulroy/.dotfiles/tree/main/home/.config/opencode/skill/build-skill
SKILL.md
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
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
dmmulroy/.dotfiles
pr-walkthrough
Generate an interactive visual walkthrough of any pull/merge request as a local HTML webapp. Produces a multi-slide presentation with SVG diagrams, annotated code, and architecture visuals. Pass a PR/MR URL and optional audience context (e.g. "assume I don't know Rust"). Use when the user says "walkthrough this PR", "explain this MR", "visual walkthrough", "PR presentation", or provides a PR/MR URL and asks for a walkthrough.
dmmulroy/.dotfiles
tdd
Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development.
dmmulroy/.dotfiles
write-a-prd
Create a PRD through user interview, codebase exploration, and module design. Use when user wants to write a PRD, create a product requirements document, or plan a new feature.
dmmulroy/.dotfiles
grill-me
Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
dmmulroy/.dotfiles
prd-to-todos
Break a PRD into independently-grabbable file-backed todos using tracer-bullet vertical slices. Use when the user wants to convert a PRD into implementation tasks, create vertical-slice todos, or break down a PRD into work items.
dmmulroy/.dotfiles
tmux
Remote control tmux sessions for interactive CLIs (python, gdb, etc.) by sending keystrokes and scraping pane output.
Didn't find tool you were looking for?