Menu
Principles and patterns for writing skill definitions
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Continue working on an OpenSpec change by creating the next artifact. Use when the user wants to progress their change, create the next artifact, or continue their workflow.
Fast-forward through OpenSpec artifact creation. Use when the user wants to quickly create all artifacts needed for implementation without stepping through each one individually.
Start a new OpenSpec change using the experimental artifact workflow. Use when the user wants to create a new feature, fix, or modification with a structured step-by-step approach.
How to write specs, name capabilities, and structure requirements. Load this when creating or reviewing proposals, specs, or capability lists.
How to invoke the openspec CLI. Load this BEFORE running any openspec commands.
Principles and patterns for writing agent definitions
| name | skill-design |
| description | Principles and patterns for writing skill definitions |
How to write and maintain skills in .opencode/skills/<name>/SKILL.md.
A skill is loaded into context to provide knowledge. It doesn't make decisions, route work, or execute workflows.
| Skill (reference) | Not a skill |
|---|---|
| How to write user stories | Query Zenhub and report status (agent job) |
| Git worktree commands and conventions | Commit, push, create PR (command job) |
| GitHub CLI read operations | Decide what to work on next (agent job) |
If a skill is trying to be two things, split it. Each skill should have a single clear answer to "what does this teach?"
Signs a skill should be split:
---
name: <kebab-case-name>
description: <what this skill teaches>
---
# <Skill Title>
<1 sentence: what this skill covers>
## <Topic>
### <Subtopic>
<Content>
Concise over comprehensive: Skills get loaded into context. Every extra paragraph costs tokens. Include what's needed for correct behavior, cut the rest.
Examples over rules: A good/bad comparison table teaches faster than a paragraph of explanation.
No implementation details unless the skill IS about implementation: A "product management" skill shouldn't reference class names. A "git worktree" skill should reference specific commands. Match the abstraction level to the concern.
Discoverable: The description field should make it obvious when
to load the skill. Agents and humans both use it to decide relevance.
When to create a new skill: You notice agents repeatedly getting something wrong, and the correction is knowledge-based (practices, conventions, patterns) not capability-based (that's an agent or tool gap).
When to update a skill: The team learns something new about the practice. Capture it immediately -- skills are the system's long-term memory for how to do things well.
When to split a skill: You realize you're loading a skill but only using half of it. Split along the usage boundary.