OpenClaw plugin delivery

The OpenClaw plugin is the push delivery tier. On each heartbeat its reconciler converges a node's on-disk skills with the tenant's active catalog — so an approved skill reliably lands on the node and shows up in the agent's skill list, no search required. This page covers how it behaves and how to configure it.

The reconcile loop

Each heartbeat the reconciler:

1. Pulls the active catalog from POST /api/v1/skills/installable (active-only when the tenant has opted in — see Delivery).
2. Writes each skill to a managed skills directory as <slug>/SKILL.md.
3. Prunes skills it manages that are no longer in the catalog.
4. Reports the outcome on the heartbeat for observability (below).

The bundled memclaw usage skill is protected — it's never pruned.

Target directories

By default the reconciler manages exactly one directory — the plugin's own skills/ dir, in owned mode. Operators can add more via the MEMCLAW_SKILL_TARGETS environment variable, a JSON array of { dir, mode, register? }:

MEMCLAW_SKILL_TARGETS='[
  { "dir": "/srv/shared/skills", "mode": "additive", "register": true }
]'

owned vs additive

additive mode is fail-safe by design, tracked with a per-skill .memclaw-owned marker file:

• A slug already occupied by an unowned skill is a collision — skipped, never overwritten (reported separately from catalog-shape errors).
• An unowned skill is never removed, even when the catalog is empty.
• Only marker-bearing entries are updated or pruned.

This confines the "empty catalog / wrong tenant wipes the directory" hazard to owned dirs only — an additive dir can lose MemClaw's own entries but never the client's.

register: reaching agents

Writing a skill to disk isn't enough if OpenClaw doesn't scan that directory. The plugin's own owned dir is published as a plugin skill automatically; an extra dir is not. Set register: true and the reconciler adds the dir to skills.load.extraDirs in ~/.openclaw/openclaw.json — OpenClaw's documented, watched mechanism for extra skill directories. The write is append-only and idempotent (it never duplicates an entry, preserves existing/foreign entries, and refuses to clobber a malformed config).

Observability on the heartbeat

The reconciler's summary rides the heartbeat and is stored as the latest snapshot per node, surfaced via GET /api/v1/fleet/nodes. It carries:

• installed — active skills currently on the node (standing truth, every tick).
• added / removed — this tick's deltas.
• skipped — catalog rows that were malformed.
• collisions — additive-dir slugs skipped because an unowned skill held the slot (kept distinct from skipped).
• protected — catalog-absent skills deliberately kept (e.g. memclaw).
• targets[] — the same fields broken down per target dir, so an operator can see which dir a skill landed in or collided in.
• registeredDirs — the dirs MemClaw has ensured are on skills.load.extraDirs.

So an operator who flips a skill to active can confirm on /fleet/nodes that it actually reached each node — closing the loop from "approved" to "installed on the fleet."

Where to look in the source

• Reconciler, target modes, ownership marker, extraDirs registration: plugin/src/reconcile-skills.ts
• Delivery contract + OSS deep-dive: docs/mcp-skill-delivery.md
• Installing the plugin: OpenClaw integration.