@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.

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. Fail-open by design — on any error, timeout, or missing model the original message passes through untouched.

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.
• Editor agent. mode: "subagent", hidden: true, steps <= 10 (maxSteps), 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 API is unreachable the rewrite stays request-scoped and the journal records persist: failed.
• 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)
    "promptEditor": {
      "enabled": true,               // opt-in; default false
      "model": "opencode-go/deepseek-v4-flash", // null -> session model
      "variant": null,
      "maxSteps": 10,                // hard editor step cap
      "timeoutMs": 30000,            // fail-open on timeout
      "minChars": 20,                // shorter messages are never rewritten
      "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
    }
  }
}

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.

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 (/…) and messages below minChars 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.
• First build preserves the released core bundle as dist/skillforge-core.js; dist/plugin.js is the wrapper (core + prompt-editor).

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 published surface is dist/plugin.js plus the adjacent spr-agent.jsonc and native helper artifacts.