build-plugin git:20261003.d3978cbA

Immutable. This exact content never changes and is served at /api/v1/blob/0bde076aca920189.

---
name: build-plugin
label: Build a plugin
description: Build, validate, install and update Minnow plugins with tools, connections, custom UI panels and bundled skills.
---

Build the requested extension as a Minnow API v1 plugin in the current workspace. Any user workspace works; the Minnow core source is not required. Use the supplied Minnow editing and plugin tools. A provider's native read-only sandbox does not imply these tools are read-only: honor actual Minnow tool permission errors and the current mode.

1. Call `plugin_inspect` with `docs: true` for the runtime contract. Call `minnow_docs_read` with `path: "manual/plugins.md"` for the full reference. Inspect installed packages to avoid duplicate ids.
2. Plan the smallest complete plugin that solves the request: tools, connections, skills, apps, menus and DOM/UI contributions. A panel in Settings is optional; use a trusted UI module for workspace UI. Use the existing workspace conventions. In Plan mode, document the design without installing or changing plugins.
3. Call `plugin_manage` with `action: scaffold`, a lowercase hyphenated `id`, and a workspace-relative `path`. This creates source files without installing them. Edit source with normal file tools. Do not edit Minnow's installation or managed package releases.
4. Implement native ESM `.mjs` handlers with a default function `(args, ctx)`. Use `ctx.workspaceRoot`, `ctx.dataDir`, `ctx.connections` and `ctx.signal`. Do not assume the current working directory is the user's workspace. Bundle third-party dependencies before installation. Do not run background daemons. Never place credentials in source, tool arguments, logs, results or panels.
5. Panels are self-contained HTML/CSS/JS. Use `await minnow.callTool(toolId, args)` for this plugin's declared tools. Handle errors and pending state, label inputs, support keyboard navigation and responsive layouts. Panels cannot access the host DOM or tokens. Use data URLs for static assets or inline them at build time.
   For UI contributions, declare `ui: {entry: 'ui.mjs'}` and export a default activation function `(ctx)`. Bundle frontend dependencies into that module. Use `ctx.registerApp` for app rail entries, `ctx.registerMenu` for menu rows, `ctx.registerCommand` for palette actions, and `ctx.mount`/`ctx.mountSlot` for DOM additions that follow rerenders. UI modules run as trusted code in Minnow's document and may use direct DOM APIs. Register direct changes, timers and listeners with `ctx.onCleanup`, respect `ctx.signal`, and use the existing `--mn-*` theme tokens. Return cleanup from app mount callbacks.
   Use `ctx.getChatUsage`/`ctx.onChatUsage` and `ctx.getWorkspaceUsage`/`ctx.onWorkspaceUsage` for token counters. Display cumulative ledger totals directly; never sum successive snapshots or streamed estimates. Counts include completed requests and reset when history is cleared. The `chat.throughput` slot is beside the bottom strip's TPS; `chat.message-throughput` and `chat.message-metrics` address message chips, and `menubar` addresses top chrome. No core edits are needed for these extension points.
   For direct `/` actions, use `ctx.registerSlashCommand({id,label,description,alias?,run})`; the handler receives `{args,chatId,workspacePath}` and runs locally without a model. Canonical names are `/plugin-<package>--<id>`; short aliases cannot shadow existing commands or skills. For reusable agent instructions, bundle a namespaced slash skill in `skills`. Verify picker discovery, execution and revocation for either kind.
6. Write meaningful tests for normal behavior, invalid arguments, provider errors, timeouts and persistence where relevant. Validate the package using `plugin_inspect` with `path`. Resolve all failures before activation.
7. Installation executes trusted local code when tools are called. Explain the concrete capabilities. Respect existing authorization and Minnow's tool approval flow; do not disable permissions to make an install work. Call `plugin_manage` with `action: install`, `path`, and the inspected `digest`. Existing plugins use `update` with `id`, `path` and `digest`, or `reload` from their last source. Tool and skill discovery refresh live.
8. Verify any installed tool through its `plugin__<id>__<tool>` name, launch contributed apps from the rail, open menu actions and verify DOM additions across rerenders. UI-only plugins need no native tool. Verify disable/remove cleanup and reload. Open any optional panel in Settings → Plugins. If credentials are required, have the user configure the encrypted fields there; never invent credentials. Report actual validation performed and any untested external connection.

Keep source, a README, and tests in the workspace. Document configuration, example calls, errors, data storage, installation and removal. Disable the plugin if verification exposes a defect, fix the source, inspect, update and re-enable. Removal revokes tools/panels/skills and clears connections; persistent plugin data is retained.