User plugins: bundled skills, instructions, hooks and MCP servers¶
Status¶
Accepted by the owner on 2026-11-06 (user-level only; no plugin slash commands).
Context¶
The owner wants users to create, share and install plugins: one folder that bundles the extension points Ru already has. Today each lives in its own fixed place:
- Skills:
SkillRoots.For/ForUser(project, user and%LOCALAPPDATA%\Ru\skillsroots), GitHub packages under ADR 0036. - Instructions:
RuInstructionLoader(~/.ru/AGENTS.md, then workspace files). - Slash commands:
CustomPromptCommands, expanded by the CLI only. - Hooks:
HookConfiguration.Loadover~/.ru/hooks.jsonand, once trusted,<workspace>/.ru/hooks.json. - MCP servers:
McpConfiguration, the user's~/.ru/mcp.jsononly (ADR 0025).
Several documents state that plugins are not loaded or discoverable
(runtime-behavior.md, harness.md, coding-agent-capabilities.md, CONTEXT.md).
Hooks and MCP servers run programs as the user, so a plugin is executable content
and needs the boundaries the owner chose: full contents, with consent.
Decision¶
-
A plugin is a folder with
ru-plugin.json. The manifest is strict (unknown fields rejected):id(^[a-z][a-z0-9-]{0,23}$, so<id>-<server>still fits the MCP name limit),name,description,version. Optional parts are found by fixed names:skills/,AGENTS.md,hooks.json,mcp.json, each with the same format and limits as today. Plugins carry no slash commands: reusable prompts are skills, which the model loads on demand. -
User-level only. Plugins live in
~/.ru/plugins/<id>(local and created) and%LOCALAPPDATA%\Ru\plugins\<id>(managed GitHub installs). There are no project plugins: they would reopen workspace-declared MCP servers (ADR 0025) and trust-gated workspace hooks. A plugin is off until the user enables it, and the enabled set is stored on the Host side, never inside the plugin folder. -
Each part joins its existing loader at the lowest precedence:
- Skills: enabled plugins'
skills/are appended after the user roots inSkillRoots.ForUser. At most 8 enabled plugins may carry skills (the catalog caps roots at 16). A plugin skill shadowed by a user or project skill is reported in Customize, not dropped silently. - Instructions: a new
PromptInstructionOrigin.Plugin, source idplugin:<id>, read after~/.ru/AGENTS.mdand before workspace files; within the existing 64/256 KiB limits and block cap. - Hooks: plugin hooks are user-level sources, behaving exactly like
~/.ru/hooks.jsonat all threeHookConfiguration.Loadcall sites. -
MCP: servers merge into
McpServerHostas<id>-<server>. A name the user's own file already declares wins; the plugin's server is refused with a diagnostic. Per-call approval (ExternalTerminal) is unchanged. -
Consent for executable parts. The executable surface of a plugin is the canonical list of hook events, matchers, commands and timeouts, plus each MCP server's transport, command, args, cwd, url and environment variable names (never values; the digest still covers the values, so changing one asks again). Enabling a plugin with an executable surface shows that list and records its SHA-256 once the user allows it; the approval request carries the digest the user was shown and fails with
plugin_changedif the plugin changed meanwhile. A plugin hook receives its folder asRU_PLUGIN_ROOT; a plugin MCP server starts in its plugin folder unless itscwdsays otherwise. Every load recomputes the digest; on a mismatch the hooks and MCP servers of that plugin are suspended (fail closed) and Customize shows "changed, approve again". Skills, commands and instructions need only enable, like today's files. Instructions and skills remain guidance and never grant permission. -
Protection. Both plugin roots join
ProtectedPathCatalog(version bump), so the agent's structured file tools cannot edit installed plugins inplanandstandard;full_accessstays literally full. The digest is the backstop for anything that changes the files outside those tools; the terminal is not confined, the same boundary as today. -
Creating a plugin.
- Customize → Plugins → New plugin scaffolds
~/.ru/plugins/<id>from a short form (id, name, description, parts) and opens the folder. -
A built-in
create-pluginskill lets the user describe a plugin in chat. Because installed roots are protected, the skill writes a draft folder inside the workspace (a non-dot folder); the user imports it with Add plugin from folder, which copies it into~/.ru/pluginsand goes through enable and consent. A plugin the agent wrote is never enabled automatically. -
Installing from GitHub. A
PluginPackageInstallerreuses ADR 0036's mechanics: tree URLs pinned to a full commit, codeload with redirects disabled, size and file limits, an exclusive lock, staging and rollback, and per-file hashes in a managed manifest. It never runs scripts or installs dependencies. An update that changes the executable-surface digest asks for consent again. New routes joinpublic-route-contract.json. -
Lifecycle. Enabling, disabling, consent and updates apply to new runs; run-local skill snapshots (ADR 0032) are unchanged. Disabling a plugin stops its MCP servers.
Alternatives and consequences¶
- Project plugins were rejected for v1 (decision 2).
- Safe-only plugins (no hooks or MCP) were the owner's alternative; they chose full contents with consent.
- Plugin slash commands were dropped: the owner wants the model, not a composer
shortcut, to use a plugin's prompts, which skills already provide.
.ru/commandsstays a CLI feature. - Skill ids stay un-namespaced to keep
/skill <id>and existing preferences working; shadowing is reported instead. - This amends "plugins are not loaded" in
runtime-behavior.md,harness.md,coding-agent-capabilities.md,CONTEXT.mdand the CLI README, and extends ADR 0025 (a second, user-level MCP source behind consent) and ADR 0036 (a second managed package kind).
Implementation phases¶
Each phase is built, tested and committed on its own.
- Manifest and loader; user plugins with skills and instructions; the plugin list with enable/disable in Customize → Plugins (Computer use stays); New plugin scaffolding. Done.
- Hooks and MCP with the consent digest and path protection (policy change: full matrix). Done.
- GitHub install and update (new routes: full matrix and route guards). Done:
SkillPackageInstallertakes a package kind; a plugin package needsru-plugin.json(whose id must match the folder), writes.ru-plugin-package.json, reportsplugin_*codes, and installs under%LOCALAPPDATA%\Ru\plugins. A local plugin with the same id refuses the install (plugin_target_exists). create-pluginskill and Add plugin from folder. Done: Ru ships built-in skills inskills-builtinnext to the Host (BuiltInSkills.Root), searched after plugin skills so any other skill with the same id wins.create-pluginwrites a draft underru-plugin-drafts\<id>in the workspace. Theimportaction onPOST /agent/v1/plugins/settings(no new route) copies a draft into~/.ru/plugins/<id>after checking the manifest, refusing links, more than 256 files or 64 MiB, and any id already installed locally or managed; it skips.gitand installer metadata, copies through a staging folder, and never enables the plugin: importing (or freshly installing from GitHub) an id clears any enable flag and approval left from an earlier plugin with that id.