| name | opencode-gadgets |
| description | Creates reusable OpenCode gadget plugins from completed or repeatable workflows. Use when the user wants to turn recent work into a reusable tool or workflow, or extract reusable CSS, layouts, components, or templates for future gadgets. |
OpenCode Gadgets
A gadget is an OpenCode plugin tool that saves a repeatable procedure.
A blueprint is a passive reusable artifact, such as CSS, a layout, component, template, prompt, or configuration fragment.
Use the current session as evidence whenever possible. Do not make the user repeat information already available.
1. Reconstruct the workflow
For completed work, inspect what actually happened.
For a new gadget, perform enough of the workflow once to determine how it should work.
Capture:
- input sources
- tools, APIs, commands, files, and services used
- transformation, filtering, ranking, and formatting rules
- defaults chosen by the user or project
- outputs and created artifacts
- external side effects
- values expected to change between otherwise identical runs, and the source of each difference
Ask the user to resolve missing behavior that would affect the interface or result.
2. Define the interface
Ask whether the gadget should be installed for the current project or globally.
Separate the captured values into:
- inputs — values callers can change
- defaults — stable choices the gadget should reuse
- variable fields — fields that may change between otherwise identical runs, each paired with the reason it changes
- result — returned data or artifacts
- side effects — changes not represented by the return value
Define:
- an input JSON Schema
- the result schema or artifact format
- all expected side effects
The contract must be specific enough to verify after implementation.
3. Reuse existing blueprints
Before recreating reusable CSS, layouts, components, templates, or similar passive artifacts, check for existing blueprints.
Read the applicable AGENTS.md and look for a documented blueprint location.
If a location is documented:
- search it for relevant blueprints
- reuse or adapt an existing blueprint when it fits
- do not recreate an equivalent asset unnecessarily
Do not force an existing blueprint when it does not fit the requested behavior or design.
If no blueprint location is documented and blueprints are needed, ask the user where they should be stored. Suggest a location appropriate to the gadget's scope, but let the user choose.
4. Map dependencies
For each external operation, identify the concrete tool, service, file, command, or existing gadget that will perform it.
A gadget tool call must finish. Delegate scheduling, watchers, servers, and other ongoing work to an existing tool or external system.
Preserve credential lookup paths and environment variable names. Never copy credential values into the gadget.
If a required capability does not exist, ask the user whether to use an alternative or create that capability first.
5. Implement
Read references/opencode-plugin.md before writing the plugin.
Choose a tool name and description based on how a future user would ask for the operation. The description should say what the tool produces and where or when it applies.
Put:
- caller-controlled values in the input schema
- stable defaults in the implementation
Write the complete TypeScript module, then call opencode_gadgets.create_opencode_plugin with the requested scope.
Global installation adds @opencode-ai/plugin to the user's ~/.config/opencode/package.json. Mention this side effect when the user has not already accepted it.
6. Verify
Verify the saved gadget without creating unwanted side effects.
Check:
- the plugin loads
- schemas and types are valid
- the implementation matches the defined contract
- returned values, artifacts, destinations, and declared side effects when they can be checked safely
Run the gadget with the original inputs or a stable fixture only when doing so is safe.
For gadgets with external or user-visible side effects, use a dry run, fixture, mock, sandbox, or test environment when available.
Do not create, update, send, publish, delete, deploy, purchase, or otherwise change real external state solely to verify the gadget.
If no safe execution path exists, skip live execution and verify everything that can be checked without causing the side effect.
When execution is safe, compare stable fields exactly. Ignore a difference only when the field and its reason were identified in step 2.
Run relevant tests and typechecks. If verification finds a mismatch with the original workflow or contract, fix the gadget and verify again.
Do not report the gadget as complete until all safely verifiable checks pass.
7. Save reusable blueprints
After verification, suggest extracting a blueprint only when a specific CSS rule, layout, component, template, or other passive artifact is likely to be reused by another gadget.
If the user chooses to create a blueprint and no blueprint location has been established, ask where reusable blueprints should be stored. Suggest a location appropriate to the gadget's scope, but let the user choose.
Save the blueprint in the chosen location.
If that location is not already documented, add it to the applicable AGENTS.md:
- project
AGENTS.md for project-scoped blueprints
- global
AGENTS.md for globally reusable blueprints
Record the chosen path clearly enough that future agents know where to search before creating similar assets.
