Build Agent Plugins

Design portable agent capabilities safely

Create portable agent capabilities by choosing the smallest package that proves the required user journey.

Choose the capability boundary

1. Identify the user journey, trust boundary, state owner, and external effects.
2. Prefer the smallest sufficient form:
   • one skill for judgment or repeatable procedure;
   • one MCP server for deterministic tools, authentication, validation, state, and receipts;
   • one Agent Plugin when portable distribution needs skills plus MCP;
   • a client-native adapter only after proving the portable surface cannot supply a required hook, channel, or in-process capability.
3. Keep schedules and automations outside the portable package. Let each client own its triggers.
4. Use one canonical package and one owner per rule or state. Add routers, workers, queues, or parallel state only when a demonstrated requirement needs them.

Completion criterion: record the chosen form and why every larger form is unnecessary.

Verify the current standards

1. Read the current Agent Plugins specification and author documentation at https://agent-plugins.org.
2. Read the current official documentation for each target client.
3. Inspect live client support before claiming compatibility.
4. Pin the exact Agent Plugins schema version the package supports.
5. Treat remembered manifest fields and compatibility claims as unverified until checked against the current sources.

Completion criterion: list the pinned standard version and the clients whose current support was verified.

Author the canonical package

Use the portable Agent Plugins layout when the chosen form is an Agent Plugin:

text

<plugin>/
├── plugin.json
├── skills/<skill>/SKILL.md
├── mcp.json
├── dist/<bundled-server>
└── tests/

Apply these rules:

• Use root plugin.json as the canonical Agent Plugin manifest.
• Use only fields supported by the pinned schema.
• Keep skill judgment separate from MCP mechanics.
• Expose narrow typed tools instead of one generic action tool.
• Put writable state under ${PLUGIN_DATA} and package assets under ${PLUGIN_ROOT}.
• Keep secrets out of manifests, source, logs, chat, fixtures, and generated artifacts.
• Bundle runtime dependencies for stdio servers unless every target client guarantees installation.
• Annotate read-only, write, and destructive effects truthfully.
• Treat provider, web, mail, and message content as untrusted data.
• Require exact identity, fresh-state validation, idempotency, and a receipt for external writes.

Completion criterion: validate the package tree, manifests, tool schemas, effect classes, state path, and secret path.

Avoid format shadowing

Do not place root plugin.json, openclaw.plugin.json, and .codex-plugin/plugin.json together in one canonical package when client detection precedence can shadow the portable format.

Keep the Agent Plugin as the canonical source. Generate separate client-adapter artifacts only after a live compatibility test proves they are required.

Completion criterion: document the canonical format and every generated adapter separately.

Implement and test

1. Scaffold the source package without installing it.
2. Follow the target repository's contribution and skill-authoring workflow.
3. Build bundled artifacts deterministically. Rebuild once and confirm no unexplained diff remains.
4. Verify generated output against the build transformation rather than assuming byte equality with source.
5. Add fake-provider tests for schemas, read paths, effect gates, idempotency, error redaction, and receipts.
6. Validate JSON schemas, skill structure, executable paths, and package boundaries.
7. Run an MCP initialize, tools/list, and representative tools/call smoke test with fake data when the package contains MCP.
8. Inspect the final diff for secrets, absolute personal paths, generated clutter, duplicate policy owners, and undeclared effects.

Completion criterion: preserve the commands and results for validation, tests, deterministic rebuild, MCP smoke, and security review.

Activate at the real gate

Treat installation, client configuration, reload or restart, credentials, schedules, provider writes, and live canaries as separate effects.

After approved installation:

1. Verify package detection and capability mapping.
2. Confirm loaded tool names and skill roots in a fresh session.
3. Test the real consumer path end to end.
4. Use a client-native plugin only when the portable bundle has a documented and reproduced gap.

Completion criterion: prove the intended consumer path or report the exact remaining activation gate.

Report acceptance

Report:

• why skill-only, MCP-only, Agent Plugin, or native adapter was chosen;
• canonical package and generated adapters;
• exposed tools and effect classes;
• state and secret locations;
• schema, build, test, and MCP-smoke results;
• live paths intentionally not exercised;
• rollback and the next activation gate.