@vaur94/opencode2-skill-forge

opencode2-skill-forge

Independent OpenCode V2 automatic skill-evolution plugin.

The plugin preserves the existing skill-forge behavior and on-disk locations:

• project skills: .opencode/skills/
• global skills: ~/.config/opencode/skills/
• evolution state: .opencode/.skill-power/
• global evolution state: ~/.opencode/.skill-power/

Ships with an opt-in prompt-editor subsystem (independent of the skill evolution system) — see Prompt Editor below.

Reviews are deny-first and isolated. Background reviews may not mutate user-owned, pinned, protected, or unmanaged skills, and the embedded skill-creator is kept in memory only. Automatic evolution remains opt-in through evolutionMode.

Support resources are confined to the target skill and symbolic links are rejected. Background reviews must read an existing support file before changing it and cannot create, modify, or remove executable files under scripts/. Review mutations are transactional per skill and are rolled back when review or graduation fails.

Configure the plugin with its own options object. Existing skill options can be moved unchanged from opencode-omni into this plugin.

Review trigger policy

Reviews are deliberately rare. An automatic background review runs only when one of these conditions holds:

• the conversation reached trigger.stepThreshold agent steps (default 100); "step" counts a completed assistant/model run (adım), and the counter resets after each review, so a review fires at most once per 100 agent steps;
• the conversation ends (session deleted) and it had at least trigger.endOfSessionMinSteps steps (default 10) — shorter chats are never reviewed;
• the user explicitly asked for skill work: a correction/durable-instruction or a skill-forge request (explicit-correction / explicit-skill-request signals). This immediate path can be disabled with trigger.explicitImmediate: false.

Tune frequency entirely through the plugin options object:

{
  "package": "@vaur94/opencode2-skill-forge",
  "options": {
    "enabled": true,
    "evolutionMode": "active",
    "skills": {
      "trigger": {
        "stepThreshold": 100,
        "endOfSessionMinSteps": 10,
        "explicitImmediate": true,
      },
    },
  },
}

Other frequency controls stay unchanged: backoff.maxFailures (default 3) puts a session into a backoff.cooldownMs (default 60 min) pause after repeated model/timeout review failures, and only one review per conversation may be in flight at a time.

OpenCode can activate the plugin for multiple project locations in one server process. Each activation keeps its location-scoped transforms and hooks, while the wrapper routes a session's skill-forge lifecycle to exactly one activation. Reviewer sessions are recorded at creation and delivered only to their owner; foreign reviewers and parented/hidden/subagent sessions never become review sources and never have their tools stripped or get queued as orphan cleanup. This process-wide routing prevents duplicate attempts and SPR-on-SPR recursion.

Prompt Editor

A separate, opt-in subsystem (options.promptEditor, default off) that intercepts a human user message before it reaches the main agent and lets a small editor agent rewrite it into a clearer, agent-friendly prompt (prompt engineering). It is independent from the skill evolution system: it runs even when the master enabled is false, uses its own model setting, and keeps its own state. With automatic approval enabled it is fail-open: an editor error, timeout, or missing model sends the original message untouched. With automatic approval disabled, no message is dispatched until the user explicitly chooses the candidate, sends the original, or re-evaluates it.

Behavior

• Interception. A session.hook("context") callback finds the newest user message, dedups by message id (LRU + in-flight guard), and runs a hidden editor session with the omni-prompt-editor agent. In blocking mode (the default), the editor prompt is dispatched and OpenCode V2 session.wait gates the main context until the editor session is idle and the rewritten message has been applied.
• Manual approval. Each pending candidate has a process-unique gate id and revision. Decisions from the web UI are scoped to both, so stale/replayed clicks cannot authorize a new run. Restart, interruption, and shutdown cancel pending gates without dispatching them.
• Session lifecycle. The transient editor session is interrupted and deleted after every run, including timeout and error paths. Its lifecycle events are hidden from the skill-forge event loop, so the spr reviewer never runs for prompt-editor sessions.
• Editor agent. mode: "subagent", hidden: true, steps: 15 by default (maxSteps, configurable in the hard range 1..100), deny-first permissions: read-only read/grep/glob plus the single terminal omni_prompt_submit tool. Short, intent-preserving rewrites; small clarifying details only.
• Learning. Each run may return a short (≤500 chars) lesson that the plugin appends to a single global learn.md (~/.opencode/.skill-power/prompt-editor/learn.md, overridable with promptEditor.learnFile). The file is injected back into every future editor run and is capped (learnMaxBytes, default 16 KB, oldest entries trimmed).
• Persistence / UI. When persist is enabled (default), the plugin updates the stored message at the server level (part.update, emitting a PartUpdated event) so the TUI and web UIs reflect the rewritten prompt. Persistence is best-effort: if the server lacks the part API the rewrite stays request-scoped. It begins only after the intercepted context has committed the rewrite and never delays provider dispatch.
• Web display (opencode2-web). Every successful rewrite is also stored in ~/.opencode/.skill-power/prompt-editor/rewrites.jsonl (newest 200, with original + improved text). opencode2-web serves it via GET /api/v1/plugins/skillforge/prompt-editor/rewrites and shows an "Improved prompt" toggler on the user message.
• Live state. Each editor run appends a lifecycle record to ~/.opencode/.skill-power/prompt-editor/states.jsonl (editing → completed, plus accepted / rejected / re-evaluating once a decision or re-run happens). opencode2-web polls GET /api/v1/plugins/skillforge/prompt-editor/states to render a left-to-right shine while the editor works, a working panel with elapsed time, and — once completed — the swapped prompt with the original collapsed behind an AI badge, plus a Yes / No / Re-evaluate confirmation.
• Session runtime flags. Per-session enabled / autoAccept toggles live in ~/.opencode/.skill-power/prompt-editor/session-flags.json (defaults: both true). They are runtime-only (not global config) and are surfaced by the web's two composer icon buttons via GET/PUT /api/v1/plugins/skillforge/prompt-editor/session-flags?session=…; the plugin skips editing sessions whose enabled flag is off.
• Decisions. The web sends accept / reject / re-evaluate through POST /api/v1/plugins/skillforge/prompt-editor/request; the plugin poller records decisions as state and re-runs the editor (with re-evaluation guidance) for re-evaluate.
• Telemetry. Every run is appended to ~/.opencode/.skill-power/prompt-editor/journal.jsonl (outcome, lengths, duration, model, persist status).

Configuration

{
  "package": "@vaur94/opencode2-skill-forge",
  "options": {
    "enabled": true, // skill evolution subsystem (unchanged)
    "spr": {
      // Optional model override for the SPR reviewer; maps onto the core's
      // reviewModel option and updates the registered agent definition.
      "model": "opencode/mimo-v2.5-free", // omit to keep the packaged default
      "variant": null,
    },
    "promptEditor": {
      "enabled": true, // opt-in; default false
      "model": "opencode-go/deepseek-v4-flash", // null -> session model
      "variant": null,
       "maxSteps": 15, // default editor step budget; valid range 1..100
      "timeoutMs": 30000, // fail-open on timeout
      "minChars": 20, // shorter messages are never rewritten
      "maxChars": 12000, // longer messages pass through unedited (range 1000..200000)
      "learnFile": null, // default ~/.opencode/.skill-power/prompt-editor/learn.md
      "learnMaxBytes": 16384,
      "tools": ["read", "grep", "glob"], // read-only allowlist
      "persist": true, // write the rewrite back to the message
      "blocking": true, // wait for the edited prompt before the main agent starts
    },
  },
}

The editor agent (system prompt/permissions/model) can additionally be tuned via prompt-editor-agent.jsonc next to the plugin bundle; the options block wins over that file.

An explicit spr.model overrides the packaged spr-agent.jsonc model for review sessions (the core's reviewModel knob) and also updates the registered spr agent definition; spr.variant applies to that definition. Invalid values are warned about and ignored, keeping the packaged default.

If edits frequently finish without a change, check the journal (~/.opencode/.skill-power/prompt-editor/journal.jsonl): entries marked "outcome": "error" with "editor run timed out" mean the editor ran out of time on your model/provider — raise timeoutMs rather than assuming the message needed no improvement. Oversized messages above maxChars skip editing immediately by design.

Guardrails

• No write tools are granted; write-capable tools are stripped even if listed.
• Editor/review/goal-role sessions and subagent/hidden agent sessions are never rewritten (prevents rewrite loops and double-processing of agent instructions).
• Commands (/…), messages below minChars, and messages above maxChars are skipped.
• learn.md content is treated as data by the editor; per-entry size limits, a file cap, and full journaling contain prompt-injection risk.
• Builds require the preserved core bundle at dist/skillforge-core.js and fail closed if it is missing; dist/plugin.js is only the wrapper.

Build & verify

Run bun run typecheck, bun test, then bun run build:plugin. See scripts/build-plugin.sh. After a source change, restart the shared OpenCode service from your terminal (opencode2 service restart) and confirm the plugin is loaded with opencode2 api get /api/plugin.

Build with bun run build:plugin; the wrapper remains separate from and imports the adjacent preserved dist/skillforge-core.js artifact. The published surface also includes the agent configs and native helper artifacts.