Plugin Packaging

Every marketplace plugin package is a ZIP file with these files at the root:

my-plugin.zip
├── claw.plugin.json        # Required — marketplace manifest
├── actionspec.json          # Required — action specification bundle
├── skill.json               # Required — plugin-local skill hints
├── README.md                # Required — capability package pointer doc
├── plugin/                  # Required — bundled runtime code
│   ├── index.js             # Entry point
│   └── ...                  # Additional modules/assets
├── skills/                  # Recommended — operational guidance
│   └── my-plugin/
│       └── SKILL.md         # When to use, inputs, safety, outcomes
├── openclaw.plugin.json     # Optional — OpenClaw/theclaw compatibility
├── portal.html              # Optional — configuration UI
└── docs/                    # Optional — additional documentation

The ZIP must have claw.plugin.json at the root (not inside a subdirectory). Max file size is governed by marketplace policy.

The marketplace uses claw.plugin.json (not plugin.json, which is for server-local plugins). The manifest must include id, name, version, type, entry, permissions, install hints, and support contact.

{
  "id": "discord-hub",
  "name": "Discord Hub",
  "version": "1.0.0",
  "type": "CONNECTOR",
  "platform": "Discord",
  "tasks": ["message.send", "channel.route", "server.notify"],
  "entry": {
    "kind": "node_module",
    "path": "plugin/index.js"
  },
  "permissions": {
    "network": ["https://discord.com/*"],
    "secrets": ["DISCORD_BOT_TOKEN", "DISCORD_DEFAULT_CHANNEL_ID"],
    "storage": ["read", "write"]
  },
  "install": {
    "installPathHint": "plugins/discord-hub",
    "postInstall": ["registerPlugin", "runHealthCheck"]
  },
  "support": {
    "email": "support@clawmagic.dev"
  }
}

Every marketplace plugin must include an actionspec.json file. This is a single bundle file (not split per action) that declares all actions the plugin exposes. Agents use this for deterministic tool selection without trial-and-error.

{
  "schema_version": "cm.actionspec.v1",
  "plugin_id": "discord-hub",
  "namespace": "plugins.discord_hub",
  "actions": {
    "discord.send_message": {
      "title": "Send Discord Message",
      "description": "Send a message to a Discord channel via bot API",
      "tool_name": "plugins.discord_send",
      "tool_args_template": {
        "channelId": "{{channelId}}",
        "content": "{{content}}"
      },
      "inputs_schema": {
        "type": "object",
        "properties": {
          "channelId": { "type": "string" },
          "content": { "type": "string", "maxLength": 2000 }
        },
        "required": ["channelId", "content"]
      },
      "constraints": ["Channel must be accessible by bot"],
      "procedure": ["Resolve channel ID", "Format message", "Send via API"],
      "verification_steps": ["Check HTTP 200 response", "Verify message ID returned"],
      "fallback": ["Retry once on 429", "Queue for retry on 5xx"],
      "examples": [
        { "input": { "channelId": "123", "content": "Hello" }, "expected": "Message sent" },
        { "input": { "channelId": "456", "content": "Status update" }, "expected": "Message sent" }
      ],
      "danger_level": "write",
      "requires_confirmation": true,
      "tags": ["messaging", "discord", "write"]
    }
  }
}

Schema version must be cm.actionspec.v1. Max file size: 512 KiB. Each action should include at minimum a description and either tool_name or cli_command_template. See /docs/plugin-development for the full ActionSpec reference including danger levels and field definitions.

Required for marketplace plugins. Tells agents when to use this plugin and which actions to try first.

{
  "schema_version": "cm.plugin.skill.v1",
  "plugin_id": "discord-hub",
  "goal": "Send messages to Discord channels via bot API",
  "when_useful": [
    "Sending automated notifications to Discord",
    "Posting status updates to team channels",
    "Routing messages to specific Discord servers"
  ],
  "recommended_action_keys": [
    "discord.send_message",
    "discord.route_channel",
    "discord.server_notify",
    "plugin.diagnostics"
  ],
  "optional_for_execution": false
}

The actionspec.json, skill.json, and SKILL.md must be consistent. Validation checks:

1. Every key in recommended_action_keys (skill.json) must exist as an action in actionspec.json.
2. Skill guidance (SKILL.md) must not contradict ActionSpec constraints or safety classifications.
3. If the skill describes the plugin as read-only, all actions in actionspec.json must have danger_level: "read_only" (not write or destructive).
4. plugin_id must match across all three files and claw.plugin.json.

ClawMagic uses two different manifest formats depending on context:

When an agent installs a marketplace plugin, the claw.plugin.json is used for install validation. The server runtime reads it alongside any plugin.json if both exist.

The marketplace API validates packages on submission. Fix all validation errors before submitting to avoid delays.

• ZIP structure: MIME type check, max file size, claw.plugin.json must exist at root.
• Manifest parse: valid JSON, required fields present, schema validation.
• Listing parity: slug, version, type, and platform must match the marketplace listing.
• Entry file: the file at entry.path must exist inside the ZIP.
• ActionSpec validation: actionspec.json must be valid JSON with schema_version: "cm.actionspec.v1". Max 512 KiB.
• Skill alignment: recommended_action_keys in skill.json must reference actions that exist in actionspec.json.
• Security scanning: optional malware scanning and checksum pipelines.

# Scaffold ActionSpec and skill.json templates for your plugin
npm run spec:scaffold -- --plugin my-plugin

# This creates:
#   plugins/installed/my-plugin/actionspec.json  (template)
#   plugins/installed/my-plugin/skill.json       (template)
#   plugins/installed/my-plugin/skills/my-plugin/SKILL.md (template)

# After filling in templates, validate locally:
npm run test:spec-packeting    # ActionSpec test suite (20 tests)
npm run check                  # Boundary checker + syntax validation

See /docs/plugin-development for the full ActionSpec development guide and /docs/submission-and-review for submission rules.

• Humans: clear setup steps in SKILL.md, support email in manifest, permissions declared so users know what the plugin accesses.
• Agents: checksum-safe install path, machine-readable actionspec.json for deterministic tool selection, skill.json so the agent knows when to use the plugin, install.postInstall steps for automated setup.
• Both: deterministic folder structure, stable semver versioning, declared secrets so configuration is predictable.

To make your plugin compatible with both ClawMagic and OpenClaw, add an openclaw.plugin.json alongside your existing files:

{
  "id": "discord-hub",
  "name": "Discord Hub",
  "version": "1.0.0",
  "configSchema": {
    "DISCORD_BOT_TOKEN": { "type": "string", "required": true },
    "DISCORD_DEFAULT_CHANNEL_ID": { "type": "string", "required": true }
  },
  "skills": ["message.send", "channel.route"]
}

• configSchema maps secrets to JSON Schema for OpenClaw’s config system.
• Add export function register(api) to your entry point. ClawMagic ignores this (uses higher-priority exports) but OpenClaw requires it.
• If you only target ClawMagic, claw.plugin.json alone is sufficient.