v1.1.0

v1.1.0

skill_management gives every installed OpenCode skill a switch: list what is installed, find out
why one will not load, hide it from the model, and put it back. Disabling writes one global
skill permission rule — no skill file is ever moved, edited or deleted.

Breaking change in 1.1.0

All four actions now return one JSON object instead of Markdown. The tool also declares an
output JSON Schema, so the host validates every result; this is a real structured tool result,
not Markdown wrapped in a JSON string.

• Envelope: schemaVersion (currently 1), action, ok, warnings.
• Failures use ok: false plus error: { code, message }; success is no longer inferred from
  ✅ / ❌ in the text.
• list returns callerAgent, summary, skills[], config, sidecar, consistency.
  description is still the first line, no longer truncated to 60 characters.
• inspect returns skill, idDerivation, agents[], caller, conclusion. Missing and
  ambiguous targets use skill_not_found / name_ambiguous.
• disable / enable return changed, reason, before, diff, verification, backup,
  sidecar; enable also returns location, rule, candidates, relatedRules.
• enable now returns ok: false with config_unparsable when the target config cannot be
  parsed and no candidate rule exists, instead of claiming "nothing to change".

Nothing else broke: actions, input fields, the written rule shape, the same-line marker format
and the single-file layout are unchanged.

Also since v1.0.0

• New bilingual documentation site (Astro + Starlight; English at the root, Chinese under
  /zh-cn): https://sogeisetsu.github.io/opencode-skill-management/
• README now documents the minimal npm install (opencode plugin add) and the package contents.
• Theme/language menus, card alignment and mobile spacing fixes on the docs site.

What it does

Action	What you get	Writes config
list	Every registered skill and its effective state for the calling agent (available / disabled / ask)	No
inspect	Why one skill is (not) usable: the matched rule, per-agent differences, how the id was derived	No
disable	Hidden from the model-visible list and rejected at load (effect: "ask" keeps it listed with confirmation)	Yes
enable	Deletes the one blocking rule, whoever wrote it	Yes

Permissions are evaluated for the calling agent only: last match wins (findLast, with *
and ? globs), and no match falls back to ask, not allow.

The rule disable writes is exactly this line (the trailing comment is the provenance marker
enable uses):

{ "action": "skill", "resource": "windows-shell", "effect": "deny" } // skill_management

Writes are atomic, preserve indentation, key order, line endings (CRLF/LF) and BOM, keep one
backup, and are verified by reloading the host and polling the caller's rule set; a write the
host did not pick up is rolled back.

Usage

skill_management({ action: "list" })
skill_management({ action: "inspect", id: "windows-shell" })
skill_management({ action: "disable", id: "windows-shell" })
skill_management({ action: "disable", id: "windows-shell", dryRun: true })
skill_management({ action: "disable", id: "windows-shell", effect: "ask" })
skill_management({ action: "enable",  id: "windows-shell" })

A list result looks like this (abridged):

{
  "schemaVersion": 1,
  "action": "list",
  "ok": true,
  "warnings": [],
  "callerAgent": { "id": "build", "verified": true },
  "summary": { "total": 29, "disabled": 1, "ask": 0, "diverged": 2, "derivedIds": 0 },
  "skills": [
    { "id": "windows-shell", "state": "available", "source": "config", "path": "..." },
    { "id": "pdf-tools", "state": "disabled", "source": "catalog", "path": "..." }
  ],
  "config": { "file": ".../opencode.jsonc", "hadPermissions": true, "notes": [] },
  "sidecar": { "file": ".../skill_management.state.json", "ok": true, "error": null },
  "consistency": { "staleSidecarIds": [], "unrecordedRules": [], "missingFromRegistry": [] }
}

Full field tables and error codes are on the four action pages of the docs site.

Install

Channel	Command / asset	Notes
npm (recommended)	opencode plugin add opencode-skill-management@1.1.0	Installs the package and registers it in the global config; no token needed
git spec	opencode plugin add github:sogeisetsu/opencode-skill-management	Bypasses the npm registry
Single file	asset skill_management.js	Drop it into <config>/plugins/; best for offline use
npm tarball	asset opencode-skill-management-1.1.0.tgz	The same tarball npm publishes; for auditing or internal mirrors

Verify it loaded in a new process:

opencode plugin list --builtin
# skill_management   1.1.0   opencode-skill-management@1.1.0

Compatibility and verification

• Targets OpenCode V2; 1.1.0 was accepted on host 2.0.32 on Windows and Linux.
• node tools/verify.mjs: 260 assertions pass, entirely against a temporary config directory.
• New-process runs against the real host returned parseable JSON for both list and the
  "skill not found" error path, and both passed the host's output validation.
• One file, pure Node built-ins, no runtime dependencies, no shell calls.

Full diff: v1.0.0...v1.1.0