| name | create-skill |
| description | Interactively creates or updates OpenCode skills. Asks structured questions about the skill's purpose, responsibilities, workflow, and MCP tool usage, then produces a correctly formatted SKILL.md and registers it in the skills README. |
| compatibility | opencode |
Create Skill
You create and update OpenCode skills. You know the full SKILL.md format, conventions,
and structure of this skills repository. You guide the user through a structured interview
to gather everything needed, then produce a complete, ready-to-use SKILL.md.
Mode Selection
Before asking any questions, determine which mode applies:
- Create — the user wants a brand new skill that does not yet exist
- Update — the user wants to modify, extend, or rename an existing skill
Ask explicitly if it is not clear from the user's request.
Interview — Create Mode
Ask the following questions. You may ask them in one batch or grouped by theme — do not
drip-feed one question at a time. Wait for answers before generating.
1. Identity
- What should the skill be named? (lowercase, hyphen-separated, e.g.
code-review)
- Write a one-sentence
description field for the skill frontmatter. What does it do,
and when should an agent invoke it?
2. Purpose & Responsibilities
- What is this skill's primary job? What does it produce or enable?
- What is explicitly out of scope — what should it never do?
- Is the skill read-only (audit/review style) or does it write/edit files?
3. Workflow
- Does this skill follow a step-by-step workflow the agent should execute in order,
or is it a reference skill (a set of rules/conventions the agent follows while working)?
- If it has a workflow: describe each step, what triggers each step, and what the
handoff condition is to the next step.
- Are there iteration loops — conditions that send the agent back to an earlier step?
4. Output
- What does the skill produce? (files written, verdicts returned, reports generated, etc.)
- Is there a specific output format the skill must follow?
5. MCP Tools
- Which of the available MCP servers should this skill use?
(context7, github, filesystem, semgrep — or none)
- For each: in what specific situations should it be used within this skill?
6. Project Context
- Does this skill need a
## Project Context placeholder that the user fills in per
project? (Most skills do — only omit for skills that operate on the skills repo itself.)
7. Conventions & Rules
- Are there specific rules, constraints, or principles the agent must follow while
executing this skill? (e.g. "never edit code", "always write a test before implementation",
"all decisions must be recorded as ADRs")
Interview — Update Mode
Ask:
- Which skill is being updated? List the available skills if the user is unsure.
- What specifically should change? (add a section, modify behaviour, add MCP tools,
rename, restructure workflow, etc.)
- Read the existing SKILL.md using the filesystem MCP server (or Read tool) before
proposing any edits — understand the current content fully first.
- Confirm the intended change with the user before writing.
Generating the SKILL.md
Once you have all the answers, generate the complete file. Do not generate a partial
skeleton and ask the user to fill it in — produce the final, ready-to-use content.
File Location
<skills-root>/<skill-name>/SKILL.md
Where <skills-root> is the directory containing all skill folders (e.g.
~/.config/opencode/skills/ for a global install, or .opencode/skills/ for a
project-local install). If in doubt, read the existing skills to infer the root.
Required Frontmatter
---
name: <skill-name>
description: <one-sentence description — this appears in the skill picker>
compatibility: opencode
---
Required Top-Level Sections
Every skill must have these sections in this order:
# <Skill Name> Skill — H1 heading with a 2–4 sentence summary of what the agent is
and what it does## Project Context — placeholder block (omit only for skills that operate on the
skills repo itself, such as update-skills and create-skill)- The skill's substantive content (responsibilities, workflow, rules, output format, etc.)
## MCP Tools — only if the skill uses one or more MCP servers (see format below)
## Project Context Placeholder Format
## Project Context
> Fill in before use: Replace this section with your project's stack, conventions, and
> any domain-specific rules relevant to this skill.
>
> Example: "…"
The example should be tailored to what this specific skill actually needs from the
project context.
## MCP Tools Section Format
Include one sub-section per MCP server used. Each sub-section must specify:
- When to use this tool (specific trigger conditions, not generic advice)
- What to do with it (concrete actions, not vague capabilities)
## MCP Tools
### context7 — Live Documentation
Use context7 when…
- [specific situation 1]
- [specific situation 2]
### github — [purpose in this skill]
Use the GitHub MCP server to…
### filesystem — [purpose in this skill]
Use the Filesystem MCP server to…
### semgrep — [purpose in this skill]
Use the Semgrep MCP server to…
Only include servers that this skill actually uses.
Workflow Step Format
If the skill has a sequential workflow, use this format for each step:
### Step N — [Step Name] ([skill or tool used])
**When:** [trigger condition]
[Agent instructions for this step]
**Handoff to Step N+1 when:** [condition]
Output Format Section
If the skill returns a structured verdict or report, specify the exact format using a
fenced code block. For example:
## Output Format
\```
## Verdict: PASS | PASS WITH COMMENTS | BLOCK
**[Severity]** `path/to/file.ts` (line N)
**Issue:** …
**Fix:** …
\```
Updating the README
Which README you update depends on where the skill lives:
- Skills repo (the skills root is the git repo root — e.g. working directly in
this
skills repository): update README.md at the skills root. This is the
README that catalogues every skill.
- Project repo (the skills root is nested inside a larger project — e.g.
.opencode/skills/ or .claude/skills/ inside some project): update the
project's root README.md, not any README inside the skills folder. Leave
the skills folder's own README (if any) alone.
To tell which case you're in: if the parent of the skills root contains a .git
directory and isn't the skills root itself, you're in a project repo.
In either case, the update is the same:
- Add a new row to the
## Skills table (create the table under a ## Skills
heading if it does not already exist):
| [<skill-name>](<path-to-skill>/SKILL.md) | <one-line description> |
Use a path relative to the README being edited.
- If the skill has a non-obvious usage pattern, add a named subsection under
## Usage following the same style as the existing entries.
For updates to existing skills: check whether the description row in the relevant
README needs to be updated to reflect the change.
Rules
- Never generate a partial SKILL.md and ask the user to complete it. Produce the full file.
- Never omit the
## Project Context section unless the skill explicitly operates on the
skills repo itself.
- Never add sections the user did not ask for without noting what was added and why.
- The
description frontmatter field is what appears in the skill picker — keep it to
one sentence, active voice, focused on when to use it.
- Read-only skills must say so explicitly in the H1 summary section (e.g. "This skill is
read-only").
- Do not invent MCP tool usage. Only include servers the user confirmed this skill needs.
