ClawHub
SkillsPluginsOfficialDocsSupport
K
skills/noelillinger/build-agent-plugins
DevelopmentAgents
#agent-plugins#mcp#agent-skills

Build Agent Plugins

Design portable agent capabilities safely

Noel Illinger@noelillinger

Build Agent Plugins

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.

Related skills

More in Development
Downloads
Security audit
Pass
Last updated
2mo ago
Current version
v0.1.0
License
MIT-0

Install

$
openclaw skills install @noelillinger/build-agent-plugins
Downloads
Security audit
Pass
Last updated
2mo ago
Current version
v0.1.0
License
MIT-0
ClawHub

Skills and plugins for OpenClaw agents. Part of the wider OpenClaw ecosystem.

Explore docs

SkillsPluginsOfficialAudits

Publish SkillPublish PluginCreate org

OverviewOpenClawDocsBlog

SupportGitHubDiscord

Built alongside the OpenClaw ecosystem

LobsterCrabboxClickClackCrabfleetOctopoolClawSweeperagent-skillsdiscrawlgitcrawlslacrawlnotcrawltelecrawlgraincrawlcrawlkitcrawlbaracpxmcporterTachikomaclawpatchclawbenchPeekaboocookbookplugin-inspectorwacrawlcrabpotAll projectsLobsterCrabboxClickClackCrabfleetOctopoolClawSweeperagent-skillsdiscrawlgitcrawlslacrawlnotcrawltelecrawlgraincrawlcrawlkitcrawlbaracpxmcporterTachikomaclawpatchclawbenchPeekaboocookbookplugin-inspectorwacrawlcrabpotAll projects

© 2026 OpenClaw Foundation

Privacy policy·Status·Deployed on Vercel·Powered by Convex

....:: clawhub/openclaw ::....  skills plugins publishers trust signals   :::: signed manifests ::::: moderated releases ::::: version history ::::   openclaw ecosystem    crabbox clickclack crawler packs gateway plugins
>>> install scan publish verify    @@ gateway @@ registry @@ agents @@     hooks runners slash-commands skill.md templates scanners review-bots   ---- downloads installs stars lineage ownership docs package integrity
  30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship   openclaw ecosystem    crabbox clickclack crawler packs gateway plugins     safe browse paths   official gateways   publisher handles   org trust
:::: signed manifests ::::: moderated releases ::::: version history ::::   ---- downloads installs stars lineage ownership docs package integrity   ....:: clawhub/openclaw ::....  skills plugins publishers trust signals
  hooks runners slash-commands skill.md templates scanners review-bots     safe browse paths   official gateways   publisher handles   org trust   >>> install scan publish verify    @@ gateway @@ registry @@ agents @@
openclaw ecosystem    crabbox clickclack crawler packs gateway plugins   ....:: clawhub/openclaw ::....  skills plugins publishers trust signals     30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship
---- downloads installs stars lineage ownership docs package integrity   >>> install scan publish verify    @@ gateway @@ registry @@ agents @@   :::: signed manifests ::::: moderated releases ::::: version history ::::
  safe browse paths   official gateways   publisher handles   org trust     30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship     hooks runners slash-commands skill.md templates scanners review-bots
....:: clawhub/openclaw ::....  skills plugins publishers trust signals   :::: signed manifests ::::: moderated releases ::::: version history ::::   openclaw ecosystem    crabbox clickclack crawler packs gateway plugins
>>> install scan publish verify    @@ gateway @@ registry @@ agents @@     hooks runners slash-commands skill.md templates scanners review-bots   ---- downloads installs stars lineage ownership docs package integrity
  30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship   openclaw ecosystem    crabbox clickclack crawler packs gateway plugins     safe browse paths   official gateways   publisher handles   org trust
:::: signed manifests ::::: moderated releases ::::: version history ::::   ---- downloads installs stars lineage ownership docs package integrity   ....:: clawhub/openclaw ::....  skills plugins publishers trust signals
  hooks runners slash-commands skill.md templates scanners review-bots     safe browse paths   official gateways   publisher handles   org trust   >>> install scan publish verify    @@ gateway @@ registry @@ agents @@
openclaw ecosystem    crabbox clickclack crawler packs gateway plugins   ....:: clawhub/openclaw ::....  skills plugins publishers trust signals     30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship
---- downloads installs stars lineage ownership docs package integrity   >>> install scan publish verify    @@ gateway @@ registry @@ agents @@   :::: signed manifests ::::: moderated releases ::::: version history ::::
  safe browse paths   official gateways   publisher handles   org trust     30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship     hooks runners slash-commands skill.md templates scanners review-bots
....:: clawhub/openclaw ::....  skills plugins publishers trust signals   :::: signed manifests ::::: moderated releases ::::: version history ::::   openclaw ecosystem    crabbox clickclack crawler packs gateway plugins
>>> install scan publish verify    @@ gateway @@ registry @@ agents @@     hooks runners slash-commands skill.md templates scanners review-bots   ---- downloads installs stars lineage ownership docs package integrity
  30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship   openclaw ecosystem    crabbox clickclack crawler packs gateway plugins     safe browse paths   official gateways   publisher handles   org trust
:::: signed manifests ::::: moderated releases ::::: version history ::::   ---- downloads installs stars lineage ownership docs package integrity   ....:: clawhub/openclaw ::....  skills plugins publishers trust signals
  hooks runners slash-commands skill.md templates scanners review-bots     safe browse paths   official gateways   publisher handles   org trust   >>> install scan publish verify    @@ gateway @@ registry @@ agents @@
openclaw ecosystem    crabbox clickclack crawler packs gateway plugins   ....:: clawhub/openclaw ::....  skills plugins publishers trust signals     30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship
---- downloads installs stars lineage ownership docs package integrity   >>> install scan publish verify    @@ gateway @@ registry @@ agents @@   :::: signed manifests ::::: moderated releases ::::: version history ::::
  safe browse paths   official gateways   publisher handles   org trust     30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship     hooks runners slash-commands skill.md templates scanners review-bots
....:: clawhub/openclaw ::....  skills plugins publishers trust signals   :::: signed manifests ::::: moderated releases ::::: version history ::::   openclaw ecosystem    crabbox clickclack crawler packs gateway plugins
>>> install scan publish verify    @@ gateway @@ registry @@ agents @@     hooks runners slash-commands skill.md templates scanners review-bots   ---- downloads installs stars lineage ownership docs package integrity
  30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship   openclaw ecosystem    crabbox clickclack crawler packs gateway plugins     safe browse paths   official gateways   publisher handles   org trust
:::: signed manifests ::::: moderated releases ::::: version history ::::   ---- downloads installs stars lineage ownership docs package integrity   ....:: clawhub/openclaw ::....  skills plugins publishers trust signals
  hooks runners slash-commands skill.md templates scanners review-bots     safe browse paths   official gateways   publisher handles   org trust   >>> install scan publish verify    @@ gateway @@ registry @@ agents @@
openclaw ecosystem    crabbox clickclack crawler packs gateway plugins   ....:: clawhub/openclaw ::....  skills plugins publishers trust signals     30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship
---- downloads installs stars lineage ownership docs package integrity   >>> install scan publish verify    @@ gateway @@ registry @@ agents @@   :::: signed manifests ::::: moderated releases ::::: version history ::::
  safe browse paths   official gateways   publisher handles   org trust     30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship     hooks runners slash-commands skill.md templates scanners review-bots
....:: clawhub/openclaw ::....  skills plugins publishers trust signals   :::: signed manifests ::::: moderated releases ::::: version history ::::   openclaw ecosystem    crabbox clickclack crawler packs gateway plugins
>>> install scan publish verify    @@ gateway @@ registry @@ agents @@     hooks runners slash-commands skill.md templates scanners review-bots   ---- downloads installs stars lineage ownership docs package integrity
  30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship   openclaw ecosystem    crabbox clickclack crawler packs gateway plugins     safe browse paths   official gateways   publisher handles   org trust
:::: signed manifests ::::: moderated releases ::::: version history ::::   ---- downloads installs stars lineage ownership docs package integrity   ....:: clawhub/openclaw ::....  skills plugins publishers trust signals
  hooks runners slash-commands skill.md templates scanners review-bots     safe browse paths   official gateways   publisher handles   org trust   >>> install scan publish verify    @@ gateway @@ registry @@ agents @@
openclaw ecosystem    crabbox clickclack crawler packs gateway plugins   ....:: clawhub/openclaw ::....  skills plugins publishers trust signals     30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship
---- downloads installs stars lineage ownership docs package integrity   >>> install scan publish verify    @@ gateway @@ registry @@ agents @@   :::: signed manifests ::::: moderated releases ::::: version history ::::
  safe browse paths   official gateways   publisher handles   org trust     30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship     hooks runners slash-commands skill.md templates scanners review-bots
....:: clawhub/openclaw ::....  skills plugins publishers trust signals   :::: signed manifests ::::: moderated releases ::::: version history ::::   openclaw ecosystem    crabbox clickclack crawler packs gateway plugins
>>> install scan publish verify    @@ gateway @@ registry @@ agents @@     hooks runners slash-commands skill.md templates scanners review-bots   ---- downloads installs stars lineage ownership docs package integrity
  30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship   openclaw ecosystem    crabbox clickclack crawler packs gateway plugins     safe browse paths   official gateways   publisher handles   org trust
:::: signed manifests ::::: moderated releases ::::: version history ::::   ---- downloads installs stars lineage ownership docs package integrity   ....:: clawhub/openclaw ::....  skills plugins publishers trust signals