Skip to content

bang404/openagent-plugin-kit

v1.13.2MIT

Create OpenAgent plugins from requirements or templates, then develop, test, and validate them for installation.

Plugin Developer

Create OpenAgent plugins from requirements or templates, then develop, test, and validate them for installation.

Plugin Developer is the installable development assistant shipped by the OpenAgent Plugin Kit repository. Its stable package ID is openagent-plugin-kit; its commands start with /openagent-plugin-kit:.

The OpenAgent source checkout is plugins/openagent-plugin-kit/. In another project, use its existing plugin directory, or plugin/<package-id>/ when it has no convention. Resolve paths from the current project root.

插件开发助手用于创建、开发、测试和验收其他插件,插件 ID 为 openagent-plugin-kit,命令以 /openagent-plugin-kit: 开头。

A standalone repository for building Agent Plugins 1.0.0 packages that OpenAgent installs. The installable kit includes a plugin development workflow from requirements through testing and developer acceptance:

  • skills/ - agent skills that teach a coding agent how to author, scaffold, validate, and release a plugin.
  • templates/ - complete starter packages, one per plugin capability, that you copy or scaffold from.
  • scripts/ - new-plugin.mjs (scaffold) and validate-plugin.mjs (validate), whose rules mirror the OpenAgent runtime loader.
  • lib/openagent-host.mjs - the shared dependency-free host bridge client for conversation, branch, Agent wake, role, and event capabilities.

The repository root is itself a valid Agent Plugin package: installing this repository adds the bundled Skills, /openagent-plugin-kit:create commands, development MCP tools and a bounded continuation hook. Start with a description or a JSON specification naming Skills and a template repository; see docs/development-workflow.md. templates/, scripts/, and docs/ are inert data - the loader only reads plugin.json, skills/, and mcp.json at the package root.

Requirements

  • Bun 1.2 or newer for the scaffold and validation scripts.
  • Node.js for installed MCP servers, portable commands and hooks; Git for repository templates, and a selected OpenAgent Runtime server for acceptance.
  • OpenAgent to install and run a generated package.
  • Development commands require a Runtime with per-execution Stop-hook execution_id, version-one MCP lease operations, portable JavaScript command launches, and the server's --control-file option. The v1.2.0 workflow was qualified against SDK revision 9cad6a4e178d9d7f9866120c02e2ba31645b3cd6; older installed runtimes lacking these capabilities must be updated. See docs/development-workflow.md.

Quick start

# From this kit checkout, scaffold under the current project's plugin directory
bun scripts/new-plugin.mjs my-plugin --template skill-pack --dir <project-root>/plugins

# Validate one package, or this repository and every bundled template
bun scripts/validate-plugin.mjs <project-root>/plugins/my-plugin
bun scripts/validate-plugin.mjs --all

# Script tests
bun test

Then install the generated directory in OpenAgent through Settings -> Plugins -> Install, or publish it as a GitHub release (see docs/publishing.md).

Templates

TemplateWhat it containsCapabilities
minimalOne plugin.json and one Skillskills
skill-packTwo Skills with workflow-style bodiesskills
mcp-toolsA dependency-free stdio MCP server plus mcp.jsonskills, mcp
mcp-lifecycleTool leases with Direct controls, commands and hook renewalmcp, commands, automation
slash-commandsA /<plugin>:<command> entry backed by a scriptcommands
sidebar-panelA sandboxed ui/panel.html sidebar viewsidebar
automation-hooksAn after_tool hook with a declared message policyautomation
daemonA supervised long-lived capability daemon declarationdaemon
full-kitEvery component in one package, as the complete referenceall

Every template is a complete package. bun scripts/validate-plugin.mjs --all fails if any of them drifts from the contract.

OpenAgent's product-owned standard packages are published separately so they can be subscribed to directly from GitHub:

Each package publishes verified release archives for the host updater. Packages do not register a Runtime implementation; they use the same generic Host Bridge and own their domain state and orchestration.

Packages that orchestrate other Agents should start with docs/host-bridge.md; the host surface is uniform, so the package owns the domain workflow instead of adding a Runtime-specific integration.

Layout

plugin.json                     kit manifest (makes this repo installable)
skills/                         agent skills shipped by the kit
templates/<name>/               starter packages, each with its own plugin.json
scripts/new-plugin.mjs          copy a template and rewrite its identity
scripts/validate-plugin.mjs     validate packages against the 1.0.0 contract
scripts/lib/plugin-spec.mjs     shared rules and package inspection
fixtures/conformance/           one package per validator rule, run by the tests
tests/                          Bun tests for the scripts and the corpus
docs/plugin-format.md           field-by-field package reference
docs/publishing.md              versioning, releases, and updates

Documentation

  • docs/plugin-format.md - every plugin.json field, the manifest rules the loader enforces, Skill rules, MCP transports, and each OpenAgent extension.
  • docs/publishing.md - repository metadata, semantic versioning, release assets, and how OpenAgent validates and activates an update.
  • docs/development-workflow.md - slash commands, saved gates, continuation, production API acceptance and reports. docs/mcp-lifecycle.md owns tool leases.
  • skills/ - the same guidance in agent-facing form, loaded by OpenAgent when the kit is installed.

License

MIT. See LICENSE.