---

name: openclaw-porter description: > This skill should be used when converting a Claude Code plugin or skill to an openclaw extension: translating UserPromptSubmit hooks to before_agent_start, adapting tool amplification lines for openclaw's tool surface, porting SKILL.md files, or registering a new extension in openclaw.json.

Also use when debugging a freshly ported extension (missing injection, gateway crash, configSchema strip), or when deciding whether a given CC plugin feature can port at all.

Do NOT use for: building net-new openclaw extensions from scratch (no CC source to port), general openclaw plugin development unrelated to porting, or Claude Code-only work where openclaw is not involved.

openclaw Porter

A reference for converting Claude Code plugins to openclaw extensions. The architectures differ enough that every conversion re-discovers the same facts — this skill captures those facts so you don't have to.

---

1. Plugin Type Classification

Identify the plugin type first. Different types require different conversion strategies.

| Type | CC Pattern | openclaw Pattern | |------|-----------|-----------------| | Text-injection | UserPromptSubmit bash → stdout | api.on("before_agent_start") → { prependContext } | | Tool-registration | N/A in CC | api.registerTool(...) | | Hybrid | N/A in CC | Both above | | Skill-only | skills/<name>/SKILL.md | Same format, manifest "skills": ["./skills"] |

Most CC plugins with hooks are text-injection type.

---

2. Manifest Conversion

.claude-plugin/plugin.json  →  openclaw.plugin.json

| CC field | openclaw field | Notes | |----------|----------------|-------| | name | id | kebab-case | | description, keywords | (drop) | Not in manifest | | configSchema | configSchema | Same JSON Schema; validator strips undeclared keys | | N/A | skills: ["./skills"] | Add if skill dir exists | | N/A | uiHints | Optional gateway UI labels |

configSchema is REQUIRED in every openclaw.plugin.json even if the plugin has no config. If the CC source had no configSchema, add: "configSchema": { "type": "object", "properties": {} }

CRITICAL: The gateway validator strips any config key not declared in configSchema.properties. Never rely on undeclared config keys at runtime. If a key isn't in the schema, it will be silently removed — no error, no warning.

---

3. Hook Conversion: UserPromptSubmit → before_agent_start

CC bash hook pattern:

# hooks/inject-*.sh
cat << 'EOF'
...injected text...
EOF

openclaw JS pattern (plain ESM — no build step when zero npm dependencies):

const INJECTION_TEXT = `...`;   // embedded string

export default {
  id: "my-plugin",
  register(api) {
    api.on("before_agent_start", async (_event, ctx) => {
      // Skip subagents — same pattern as moltgraph
      if (ctx.sessionKey?.includes(":subagent:")) return;
      return { prependContext: INJECTION_TEXT };
    });

    api.logger.info("my-plugin: registered");
  }
};

Config-aware pattern — only when configSchema has meaningful properties:

export default {
  id: "my-plugin",
  register(api) {
    const cfg = api.pluginConfig ?? {};
    const disabled = new Set(cfg.disabledFeatures ?? []);

    api.on("before_agent_start", async (_event, ctx) => {
      if (ctx.sessionKey?.includes(":subagent:")) return;
      const text = buildInjection(disabled);   // generate text from config
      return { prependContext: text };
    });

    api.logger.info(`my-plugin: registered (${disabled.size} features disabled)`);
  }
};

Why before_agent_start and not before_prompt_build? before_prompt_build is described in docs as "injecting context before prompt submission" while before_agent_start is labelled "legacy." Use before_agent_start to match moltgraph's proven production pattern until divergence is confirmed in production.

The subagent skip guard is mandatory. Without it, every subagent invocation also receives the injection, wasting tokens and potentially confusing the subagent.

The return { prependContext: ... } is required. Returning void or omitting the return silently does nothing — the gateway won't error, injection simply won't happen.

---

4. Tool Amplification Line Adaptation

Every → TOOLS: line in the injected text must be audited. openclaw has a different tool surface than Claude Code.

| CC tool / agent type | openclaw status | Action | |----------------------|-----------------|--------| | Read, Bash, Grep, Glob | ✗ Not available | Drop | | Task(Explore subagent) | ✗ No Explore type | Drop | | Task(parallel agents) | Partial (sessions_spawn) | Drop unless confident | | WebSearch | ⚠ Depends on deployment | Verify — check tools.web.search.enabled and tools.deny in your agent config. Blocked by default in this deployment (group:web denied). Drop if unavailable. | | kg_search_facts, kg_search_nodes, kg_add_memory | ✓ moltgraph tools | Keep | | AskUserQuestion | ✓ Available | Keep | | canvas, image, read (openclaw native) | ✓ Available | Keep |

Skill reference lines require text adaptation (no longer scoped by plugin):

# CC:
→ SKILL: fields:narrative-architecture — [purpose]

# openclaw:
→ SKILL: narrative-architecture framework (in your system context) — [purpose]

Branding: Remove "Claude Code" branding from preamble:

"NATIVE TOOL PRIORITY: When a Claude Code tool exists..."
→
"TOOL PRIORITY: When a native tool exists..."

Detection triggers:

Drop -cc suffix fields entirely (/code-cc, /explore-cc) — these exist solely to direct CC-specific tools.

Keep cognitive fields even if they had TOOLS lines in CC (/cog-debug, /code, /critic, etc.) — just strip the → TOOLS: amplification lines that reference unavailable tools.

Add conversational triggers that make more sense in openclaw's messaging context:

- Seeking advice, major decisions, thought partnership → /interview
- Request scope is unclear or unbounded → /scope

Remove /planning if it depends on TaskCreate which doesn't exist in openclaw.

---

5. Skill Porting

SKILL.md format is identical between CC and openclaw. Copy verbatim.

Audit the skill body: If a skill references CC-specific tools (Read, Bash, Task(Explore)), drop or adapt those lines using the tool-adaptation table in section 4.

Register in manifest via "skills": ["./skills"].

The skill directory structure is the same:

skills/
└── <skill-name>/
    └── SKILL.md

---

6. Extension Placement

~/.openclaw/extensions/<plugin-id>/
├── openclaw.plugin.json
├── index.js                  # ESM, no compile step
└── skills/
    └── <skill-name>/
        └── SKILL.md

Important: ~/.openclaw/ on the host IS the container mount (/home/node/.openclaw). The extensions/ dir is auto-discovered — no CI rebuild, no docker restart needed to pick up new extension files. The gateway reads extensions on startup.

Multi-gateway deployments: Each gateway mounts its own config dir. If you have a rumble gateway at ~/.openclaw-rumble/, extension files must also be reachable there. Symlinks across config dirs don't work inside containers — add an explicit volume mount in the compose file instead:

volumes:
  - ${OPENCLAW_CONFIG_DIR:-/home/unihorn/.openclaw-rumble}:/home/node/.openclaw
  - /home/unihorn/.openclaw/extensions/<id>:/home/node/.openclaw/extensions/<id>:ro

This preserves a single source of truth without copying files.

Restart the gateway after adding files:

cd ~/ops && docker compose down && docker compose up -d

---

7. Config Registration

Both config files must be updated — ~/.openclaw/openclaw.json (unicorn gateway) and ~/.openclaw-rumble/openclaw.json (rumble gateway).

Local extensions (files in ~/.openclaw/extensions/<id>/) only need plugins.allow:

{
  "plugins": {
    "allow": ["...", "new-plugin-id"]
  }
}

The gateway will log: loaded without install/load-path provenance; treat as untracked local code and pin trust via plugins.allow — this is expected and harmless; plugins.allow IS the trust pin.

Do NOT add a plugins.entries item for local extensions. That pattern is for CI-built/npm-installed plugins (like moltgraph). Adding entries.new-plugin-id for a local extension causes the gateway to crash with plugin not found: new-plugin-id on startup.

plugins.entries is only for installed plugins where you need to pass config or override defaults:

{
  "plugins": {
    "allow": ["installed-plugin-id"],
    "entries": {
      "installed-plugin-id": {
        "enabled": true,
        "config": { "someKey": "value" }
      }
    }
  }
}

---

8. Verification

# 1. Confirm registered — check logs after gateway restart
docker logs ops-openclaw-gateway-1 2>&1 | sed 's/\x1b\[[0-9;]*m//g' | grep "<plugin-id>:"
# Expected: <plugin-id>: registered (N fields disabled)

# Also expect this harmless warning in the logs:
# [plugins] <plugin-id>: loaded without install/load-path provenance; treat as untracked local code and pin trust via plugins.allow
# This is NOT an error — the extension loaded from extensions/ (not from marketplace).
# Since it's in plugins.allow, trust is already pinned.

# 2. Check for crash / missing module
docker logs ops-openclaw-gateway-1 2>&1 | sed 's/\x1b\[[0-9;]*m//g' | grep -i "error\|Cannot find"

# 3. Send a test message → verify injected text shapes response

# 4. Test configSchema — add a config value, restart, verify it takes effect

# 5. Rumble gateway: same pattern, container name rumble-openclaw-gateway-1

---

9. Common Failure Modes

| Symptom | Root Cause | Fix | |---------|-----------|-----| | Gateway starts but plugin is silent | plugins.allow missing the id | Add to allow array (no entries item needed for local extensions) | | Gateway crash-loops with plugin not found: id | Added plugins.entries.id for a local extension — entries is only for installed plugins | Remove the entries item; allow is sufficient | | Config is invalid: plugin manifest requires configSchema | openclaw.plugin.json missing the configSchema field | Add "configSchema": {"type": "object", "properties": {}} | | Config key has no effect at runtime | Key not in configSchema.properties (stripped by validator) | Declare key in schema | | Cannot find module './X.js' in logs | File not in extension dir | Copy missing file | | Injection never fires | Forgot return { prependContext } | Check return value | | Subagents also get injection | Missing subagent skip check | Add ctx.sessionKey?.includes(":subagent:") guard | | Plugin missing after deploy | Silent build failure (CI succeeds, module absent) | docker exec <container> ls /app/extensions/<plugin-id>/ | | before_prompt_build doesn't inject | Wrong hook name | Use before_agent_start |