| name | skill-writer |
| description | Create or update opencode skills. Use this skill when asked to write, add, or update a skill for opencode. |
Writing Agent Skills
Skills are markdown files that give Claude and OpenCode context and instructions for specific tasks.
Location
Skills live in the dotfiles source tree (not directly in ~/.config):
~/.local/etc/<group>/agents/skills/<skill-name>/SKILL.md
After editing, run dots install to install them to ~/.config/agents/skills/ (which is shared by Claude and OpenCode).
Choosing the right group
Place skills based on scope:
base/agents/skills/ -- default for broadly useful skills you want available across machines/contexts
machines/server/agents/skills/ -- server-only skills (home infra, media automation, server operations)
machines/work/agents/skills/ -- work-laptop-specific skills (for example pr-workflow)
Rule of thumb: start in base unless the skill is clearly tied to one machine/profile.
Note: See the dotfile-management skill for detailed information about working with the dotfiles repository and the dots utility.
Frontmatter
Every skill must have frontmatter with name and description:
---
name: skill-name
description: One sentence describing when to use this skill.
---
name: must match the directory name
description: used by opencode to decide when to load the skill — make it specific about the trigger condition
When to create a new skill vs update an existing one
- New skill: the task is distinct enough to warrant its own trigger condition
- Update existing: the new info belongs to an existing skill's domain (e.g. adding a new service to
server-admin)
Workflow
- Choose group scope (
base, machines/server, or machines/work)
- Create the directory and
SKILL.md in ~/.local/etc/<group>/agents/skills/<name>/
- Write the skill content
- Run
dots install to install it
- Restart/reload the relevant agent service if needed
- Test the skill by asking something that should trigger it
- Iterate until satisfied
- When committing changes, always read
~/.local/etc/AGENTS.md first to follow the correct commit message format: <component>: <imperative description>
- Ask Evan if he'd like to commit and push the skill