Ryuu's Skills

OpenCode

Use slash skills, the guards, the session brief and the reply guard in OpenCode v2.

OpenCode v2 loads the skills natively from ~/.agents/skills. No extra skills install step is needed. The installer also writes a plugin when the OpenCode config directory already exists. It never creates that directory for you.

What the installer writes

The installer picks one config directory, using the first nonempty value:

  1. OPENCODE_CONFIG_DIR.
  2. XDG_CONFIG_HOME with /opencode appended.
  3. ~/.config/opencode.

It writes plugins/skills.ts there and records the file's SHA256 hash in .skills-install.json. It never uses ~/.opencode, which OpenCode treats as a project directory. A session started with a different OPENCODE_CONFIG_DIR does not get this plugin.

The plugin entry is a small written stub. It imports playbook/opencode/plugin.ts through the absolute AGENTS_DIR path, so changes in the linked checkout take effect without copying the plugin again. If that import fails or does not yield a plugin, the stub refuses every shell call with a message naming the path and the cause. The plugin's id is skills-guard; a config that disables that id turns the guards off.

The manifest records the bytes this installer wrote. An existing file is owned only if its hash still matches that record. An edited or unrecorded file, a symlink or a directory is personal and stays untouched, with a skip line in the install output. Missing files are created and recorded. An unchanged install leaves the plugin and manifest byte identical and prints nothing for them. An invalid or unreadable manifest is left alone, and writes that need it are skipped.

Subagents

The installer translates the checkout's agents/ files into v2 subagents in <config dir>/agents/:

  • comment-sicko
  • fable-judgment
  • opus-review
  • playbook-agent

Each keeps its description and body and gets mode: subagent. No model is written, so each runs on the session's model. effort is dropped because v2 frontmatter has no such key. Any key outside the v2 set makes OpenCode skip the file.

A Claude tools list becomes permissions: deny all, then allow each mapped action. comment-sicko can read and grep, never edit. Agents without a tools list get no permission rules. Unknown source keys or tool names cause a skip line instead of an agent file.

Ownership uses the same .skills-install.json manifest as the plugin. Personal files stay untouched. An agent dropped from the checkout is removed when still owned. An edited copy stays, and its manifest entry is removed so a later install cannot prune it.

Slash commands

Claude Code offers these skills by slash name. OpenCode only offers slash commands, so the installer writes one commands/<name>.md for each linked skill with disable-model-invocation: true. Each command loads the skill with the skill tool and passes $ARGUMENTS through. For example, /plans do 12 loads plans with do 12.

Commands use the same .skills-install.json ownership rules as the plugin. Edited and handwritten files stay untouched. When a skill is no longer linked or drops the flag, the installer prunes its command only if the recorded hash still matches, then removes its manifest entry.

  • /architect
  • /blast-radius
  • /coderabbit
  • /figure-it-out
  • /greptile
  • /how
  • /hub
  • /interrogate
  • /macroscope
  • /no-comments
  • /plans
  • /playbook
  • /principle-boundary-discipline
  • /principle-build-the-lever
  • /principle-encode-lessons-in-structure
  • /principle-exhaust-the-design-space
  • /principle-experience-first
  • /principle-fix-root-causes
  • /principle-foundational-thinking
  • /principle-guard-the-context-window
  • /principle-laziness-protocol
  • /principle-make-operations-idempotent
  • /principle-migrate-callers-then-delete-legacy-apis
  • /principle-minimize-reader-load
  • /principle-model-the-domain
  • /principle-never-block-on-the-human
  • /principle-outcome-oriented-execution
  • /principle-prove-it-works
  • /principle-redesign-from-first-principles
  • /principle-separate-before-serializing-shared-state
  • /principle-sequence-verifiable-units
  • /principle-subtract-before-you-add
  • /principle-type-system-discipline
  • /show-me-your-work
  • /tdd
  • /technical-writing

What the plugin runs

The plugin maps OpenCode tool inputs and session events to the existing CLI payloads and forwards their verdicts. It decides no policy itself.

  • Before shell, it runs skills hook pre-tool-use. A refusal throws the commit guard's exact reason into the tool result. A renamed tool with a string command input gets the same check.
  • After a completed edit, write or patch, it runs skills hook post-tool-use. A comment or dash finding goes first in the tool's content, before the original output.
  • Other tools, including read, run no hook. Failed edits run no post hook.
  • On a top level session's first model request, it runs skills hook session-start once and adds the session brief to the system prompt of every request in that session. Subagent sessions get no brief, and a brief that fails is not retried for that session.
  • After a top level session's execution succeeds with a finished reply, it runs skills hook stop on that reply. A reply guard block is sent to the session as a follow up prompt, and the rewrite is checked again until the guard's own limit of two rewrites. Failed or interrupted executions, subagent sessions, and a reply a newer message has already followed get no check and no prompt.

The CLI needs Bun. Without it, every shell call is refused, and the installer prints a note saying so. An unreadable pre-hook result, a failed launch or a timeout also blocks the shell call. Each CLI invocation has a 30 second timeout, the brief 10 seconds. A post-hook failure leaves the original result untouched and never fails the tool call. A brief or reply guard failure adds nothing and sends no prompt.

Subagent permission rules live in the agent files, not the plugin.

Rule groups

With AGENT_RULES set in skills.conf, the installer also manages the rule groups in the global config. It reads both opencode.json and opencode.jsonc in the selected config directory. New asks go into the last existing file, or a new opencode.jsonc when neither exists. New denies go into opencode.json when it exists, since OpenCode lets that file's policies win; otherwise they go where the asks go. Owned entries in the other file move to their list's target. OpenCode reloads config changes without a restart.

Denies go at the end of the top level policies array as tool.use statements. Asks go at the end of the top level permissions array:

{
  "policies": [
    { "action": "tool.use", "resource": "shell:gh pr merge *", "effect": "deny" }
  ],
  "permissions": [
    { "action": "edit", "resource": "/home/me/.claude/settings.json", "effect": "ask" }
  ]
}

A project permission or saved approval can override a global permission rule. Configuration policy denies run before those permissions, so they still hold with project rules, saved "always" approvals and --auto. Asks do not hold against saved "always" approvals or --auto. Allow groups such as skills-cli have no OpenCode effect: writing an allow could override a personal ask or deny.

An owned entry has exactly action, resource and effect, matches a current or default rendering of a deny or retired group, and has effect ask or deny. A policy entry must also use tool.use and deny. Even an entry you wrote yourself is owned if it matches this definition, so the installer may move or remove it. An allow effect, extra fields and every skills-cli rendering are personal. Only entries that match no owned rendering stay untouched. Comments and surrounding formatting stay byte for byte. Malformed or unsafe config files are refused with a reason and a JSON set to paste into the two arrays.

Strengthening and neutral changes apply without a prompt. Weakening changes need a terminal confirmation, including removal of publishing denies when switching from --without prs to --with prs. A non-terminal run leaves them and prints the command to rerun at a terminal. A group set to off keeps its entries but stops managing them. Each applied change gets an opencode line; personal rules that never apply or block the mode's work get a note, not an edit.

The pr-comment deny stays until the installer-owned plugin, Bun and CLI are available and neither global config disables skills-guard. The plugin takes over once that guard is wired.

Edit rules cover absolute, home-relative and nested relative paths. They miss a session started in the guarded file's own directory, where OpenCode asks about only the basename. Shell redirects do not request edit permission either. These rules catch mistakes, not deliberate attempts to bypass them.

Instructions and service environment

OpenCode reads global instructions only from <config dir>/AGENTS.md, with no CLAUDE.md fallback. The installer manages no AGENTS.md for any host. Put your own instructions there.

Plugins run in the server process. The background service keeps the environment of the client that started it. Setting AGENT_HOOKS=0 on a later client does not reach the running plugin. To change that environment for one run, set the variable on opencode run and pass --standalone, which starts a private server with it.

As on the other hosts, AGENT_HOOKS=0 turns off the comment and dash guards, the session brief and the reply guard, not the commit guard. See Configuration for hook settings.

Verify an install

The repository's scripts/verify-opencode.ts installs with AGENT_RULES=deny in prs mode into a temporary home and config directory, then asks a real OpenCode v2 model to attempt a guarded shell call against a local bare remote. It prints whether the plugin loaded, whether the shell call returned the commit guard's reason, and whether the remote stayed unchanged. It then starts a private OpenCode server and checks that a session's first reply can name the branch from the brief, and that a reply with an em dash gets a rewrite prompt. It also checks that OpenCode lists every installed command, and runs /plans do 0 to confirm the arguments reach the model and the skill loads from the scratch install. The plans directory is empty scratch space, and the script stops its server when done. Last, it removes the scratch plugin. Without that plugin, gh pr merge 7 must fail with "Blocked by configuration policy", while publishing the feature branch must run and create refs/heads/feat/x in the local bare origin. It runs by hand, never in CI, and calls a paid model. It retains your real HOME so OpenCode can use its saved authentication.

bun scripts/verify-opencode.ts opencode-go/glm-5.3-flash

The model may also be set with OPENCODE_MODEL; the command line argument wins.

On this page