/create-claw-skill

name: create-claw-skill
description: >
  This skill should be used when the user asks to "create an OpenClaw skill",
  "make a claw skill", "build a skill for OpenClaw", "write a SKILL.md for openclaw",
  "add a skill to openclaw", "generate openclaw skill frontmatter", "create a clawhub skill",
  "port a skill to OpenClaw", "convert a Claude Code skill to claw",
  "migrate my skill to openclaw", or wants to author a new skill or port an existing
  Claude Code skill for the pi-coding-agent / OpenClaw ecosystem.
argument-hint: "[skill|command] [name] - or leave empty to interview"

OpenClaw Skill & Command Generator

Generate well-structured OpenClaw skills or slash commands. Both are SKILL.md files with YAML frontmatter — they share the same structure but differ in how they're triggered and described. OpenClaw uses the AgentSkills spec (pi-coding-agent) with its own frontmatter fields, tool names, and path conventions distinct from Claude Code.

Phase 0: Fetch Current Documentation

**Before generating**, retrieve the latest OpenClaw skill documentation:

clawdocs get "tools/skills" --no-header -q

Capture any frontmatter fields or options not already listed in `{baseDir}/references/frontmatter-options.md`. If `clawdocs` is unavailable, proceed with current references — they are sufficient. If new fields appear, use them and note the update.

Phase 1: Understand Requirements

Parse `$ARGUMENTS` for type hint. Users are often unclear on OpenClaw-specific conventions. Interview to gather:

1. **Primary objective** — What should this skill do? 2. **Trigger scenarios** — When should it activate? What exact phrases would a user say? 3. **Inputs/outputs** — What does it receive and produce? 4. **Complexity** — Simple, standard, or complex workflow? 5. **Gating needs** — Does it require specific binaries, env vars, or config keys? (drives `metadata.openclaw.requires.*`) 6. **Execution needs** — Sub-agent delegation via `sessions_spawn`? Command dispatch (bypass model)?

Proceed to Phase 2 when at minimum Objective and Trigger Scenarios are established.

Port Mode

When the user provides an existing Claude Code skill to port (file path or pasted content), skip the interview and apply this translation sequence:

1. Read the source skill and all its supporting files (scripts, references, examples) 2. **Frontmatter** — Remove invalid fields (`model`, `context`, `agent`, `allowed-tools`, `hooks`, `license`). Add `metadata` with `requires` if scripts need specific binaries. See `{baseDir}/references/frontmatter-options.md` for valid fields. 3. **Tool names** — Apply the translation table from `{baseDir}/references/claw-patterns.md`: `Bash`→`exec`, `Read`→`read`, `Write`→`write`, `Edit`→`edit`, `Glob`/`Grep`→`exec`+`find`/`rg`, `WebSearch`→`web_search`, `WebFetch`→`web_fetch`, `Task`→`sessions_spawn`, `AskUserQuestion`→conversational asking 4. **Paths** — Replace `$CLAUDE_PLUGIN_ROOT` with `{baseDir}`. Remove `@file` injection and bang-backtick references. 5. **Scripts/references** — Copy as-is if they are platform-neutral Python with no Claude Code SDK dependencies. Update any internal tool name references. 6. Proceed directly to Phase 2 Step 7 (Validate) with translated content, then Phase 3 (Deliver).

Phase 2: Generate

Apply throughout generation: use imperative voice and terse phrasing because every token in a generated skill body costs budget on every invocation. Prefer instruction over example — state the rule with its reasoning so it generalizes to every input.

**Initialize directory first (when creating a new skill directory, not editing an existing file):**

python3 {baseDir}/scripts/init_claw_skill.py <name> --path <dir> [--resources scripts,references,assets]

Exit 0 = directory scaffolded, proceed to Step 1. Exit 1 = naming collision; ask user whether to overwrite or rename.

Step 1 — Choose type

• **Skills:** Trigger-rich, third-person description ("This skill should be used when..."); auto-triggered by routing
• **Commands:** Concise, verb-first description, under 60 chars; user-invoked via `/` menu
• **Dispatch commands:** `command-dispatch: tool` with `command-tool` — bypasses model entirely, routes directly to a named tool (rare; for pure pass-through cases)

Step 2 — Write frontmatter

Read `{baseDir}/references/frontmatter-options.md` for the full OpenClaw field catalog, description patterns, and the `metadata` single-line JSON constraint.

Key constraint: **`metadata` must be a single-line JSON object on one line.** Multi-line YAML mappings under `metadata` are not valid in OpenClaw.

**Description density rules:** Keep descriptions under ~400 characters / ~100 tokens (600 chars / 150 tokens absolute max) — they load every session. Per the OpenClaw cost formula, each skill costs `195 + 97 + field lengths` characters in the system prompt; a 10-skill install with verbose descriptions burns significant context on routing metadata alone. Derive trigger phrases from the user's actual words in Phase 1, not paraphrases. See the token budget and trigger derivation principles in `{baseDir}/references/frontmatter-options.md`.

**Intensional over extensional** — state the rule with its reasoning rather than listing examples that imply the rule. An intensional rule generalizes to every input the skill will encounter; an extensional list only covers the shapes shown.

Step 3 — Validate description discoverability

Before writing the body, verify the description will route correctly. Mentally generate:

1. **3 should-trigger prompts** — realistic user messages that should activate this skill. Include at least one naive phrasing from a user who has never heard of the skill. 2. **3 should-NOT-trigger prompts** — messages in adjacent domains that are close but should not activate. These test whether the description is too broad.

Evaluate: does the description cover all should-trigger prompts? Would it plausibly reject the should-NOT-tr