skill creatorfor OpenCode

Documentation

From install to
your first skill.

A practical path through creating, evaluating, and improving skills in OpenCode.

Install

OpenCode Skill Creator combines a bundled skill with plugin tools. Use the installer for OpenCode V2, then restart OpenCode to load the plugin.

Global installation

Make the plugin available across your projects:

Terminal
npx opencode-skill-creator install --global

The installer updates an existing ~/.config/opencode/opencode.jsonc when present; otherwise it creates or updates opencode.json. It adds the package to the plugins array and preserves your other plugin entries.

Project-only installation

Run this from the project where you want to use the plugin:

Terminal
npx opencode-skill-creator install --project

Manual V2 configuration

Add the package to your existing plugins array. Preserve the other entries, then restart OpenCode.

OpenCode V2 config
{
  "plugins": ["opencode-skill-creator"]
}

Show the supported V1 manual setup

For OpenCode V1 ≥ 1.18.29, add the package to the singular plugin array in your global or project configuration, retain your other entries, and restart OpenCode.

Supported OpenCode V1 config
{
  "plugin": ["opencode-skill-creator"]
}

Do not add the package to both arrays as a routine setup. See the full V1 compatibility notes for mixed configurations and upgrades.

Create your first skill

After restarting OpenCode, describe a task you actually repeat. Include when the skill should be used and what a useful result looks like.

Prompt in OpenCode
Use opencode-skill-creator to create a skill that reviews Docker Compose files. Check service configuration, identify risky defaults, and explain each suggested change.

The bundled skill guides the agent through drafting SKILL.md, supporting files, and evaluation cases. Treat the first draft as a candidate, then examine its instructions and test it.

Draft in a temporary staging directory, outside your repository. Keep evaluation artifacts in a separate workspace and install the finished skill only after you have reviewed it.

Example staging paths · macOS / Unix
/tmp/opencode-skills/compose-review/
/tmp/opencode-skills/compose-review-workspace/

For a concrete starting point, use the repository’s Docker Compose helper example, or follow the first-skill guide.

Evaluate the trigger

A skill description helps the agent decide when to use that skill. Check both sides of the boundary: requests that should activate it, and similar requests that should not.

  • Positive cases: representative work the skill is intended to handle.
  • Negative cases: adjacent requests where using the skill would be a mistake.
  • Held-out cases: examples kept out of the improvement prompt, so you can check whether a revision generalizes.
Prompt in OpenCode
Use skill_eval to evaluate this skill against labeled should-trigger and should-not-trigger cases. Include near misses. Explain false positives and false negatives before proposing changes.

Evaluation results are tracked per eval-set item, not by query text. Keep each item’s label and position intact when comparing results; repeated query text can represent separate cases.

Improve the description

Use the failure patterns to decide what the description is missing. Clarify the task, its boundary, and the context that should activate it. Avoid expanding the description to promise unrelated capabilities.

Prompt in OpenCode
Use skill_optimize_loop to improve the skill description. Preserve the intended task, keep training and held-out cases separate, and compare candidate results before selecting a revision.

The optimization workflow evaluates candidates across training and test sets. A stronger test result can guide a revision, but keep reviewing the underlying task output. Read the description improvement guide for a practical decision process.

Review the result, not just the score

The review tools support human comparison of skill-assisted outputs with a baseline. By default, each eval-* directory needs with_skill plus either without_skill or old_skill.

Use skill_serve_review for the local viewer or skill_export_static_review for a standalone HTML review. Missing comparison pairs fail clearly unless you intentionally choose a partial-data review.

Prompt in OpenCode
Prepare paired outputs for each eval: with_skill and without_skill. Open them with skill_serve_review so I can compare the results. Stop the review server with skill_stop_review when I finish.

When automating or testing the review flow, pass openBrowser: false or set OPENCODE_SKILL_CREATOR_OPEN_BROWSER=0. This keeps automated work from launching a browser.

Tools, at a glance

The plugin registers these tools for the agent to call during the workflow. These are tool names, not shell commands.

skill_validate

Check SKILL.md structure and frontmatter.

skill_parse

Read the skill name and description.

skill_eval

Evaluate whether a skill triggers for labeled queries.

skill_improve_description

Propose a revised description from evaluation feedback.

skill_optimize_loop

Run the evaluation and improvement loop.

skill_aggregate_benchmark

Aggregate grading results into statistics.

skill_generate_report

Generate an HTML optimization report.

skill_serve_review

Start the human review viewer.

skill_stop_review

Stop a running review server.

skill_export_static_review

Export a standalone HTML review file.

For parameters and examples, use the upstream tool documentation.

Common questions

I installed it, but nothing changed.

Fully restart OpenCode. Configuration is read at startup. Confirm that your runtime uses plugins for V2 or plugin for supported V1, and that you edited the intended global or project configuration.

I already use other plugins.

Keep the existing entries. Add opencode-skill-creator to the same array for your runtime rather than replacing the configuration.

Where is the bundled skill installed?

On first startup, the plugin copies its bundled skill into ~/.config/opencode/skills/opencode-skill-creator/. This is the plugin’s own workflow skill; the skills you author have their own names and installation paths.

Does open source mean model calls are free?

The project is open source. Evaluation and optimization still use the models configured in OpenCode, and those providers may charge for usage. Review your provider settings before running a large evaluation.

Where should I report a problem?

Open a GitHub issue with the OpenCode version, plugin version, relevant configuration without credentials, and a small reproducible example.