claw3d/CREATING_SKILLS.md

Creating Skills

This repository ships developer-created marketplace skills as packaged assets that Claw3D can install into an OpenClaw workspace through the gateway.

Use the existing todo-board skill as the reference implementation.

Mental model

• assets/skills/<package-id>/ is the human-friendly source layout for each packaged skill.
• src/lib/skills/packaged.ts contains the client-safe embedded copy of those files used by the marketplace install flow.
• src/lib/skills/catalog.ts registers the skill so it appears in the marketplace.
• src/lib/skills/install-gateway.ts installs the packaged files into the selected workspace by creating a temporary gateway agent and asking it to write the files.

Folder structure

Follow this structure for every packaged skill:

assets/
  skills/
    <package-id>/
      SKILL.md
      <optional companion files>

Current example:

assets/
  skills/
    todo-board/
      SKILL.md
      todo-list.example.json

1. Create the skill files

Create a new folder under assets/skills/<package-id>/.

Required file:

• SKILL.md

Optional files:

• Example JSON files.
• Templates.
• Any additional files the installed skill should include.

SKILL.md requirements

Your SKILL.md should include frontmatter, a trigger section, and clear operating instructions for the agent.

Use this pattern:

---
name: my-skill
description: Short description of what the skill does.
metadata: {"openclaw":{"skillKey":"my-skill-key"}}
---

# My Skill

Explain when the skill should be used, where it stores state, how it reads and writes files, and the exact workflow rules the agent must follow.

Notes:

• name is the user-facing skill name.
• metadata.openclaw.skillKey must stay stable and should match the installed folder name.
• Every skill must define a ## Trigger section that explains what activates the skill and what the agent should physically do in Claw3D when it activates.
• Write instructions as if the model will follow them directly.
• If the skill stores state, define the exact file path and schema.
• Be explicit about read-before-write, validation, ambiguity handling, and response behavior.

Trigger requirements

Every skill must contain a trigger.

At minimum, the trigger section should define:

• What kind of user request or external event activates the skill.
• What physical behavior the agent should perform in the office when the skill starts.
• Whether that movement should be skipped when the agent is already at the right location.

Example:

## Trigger

```json
{
  "activation": {
    "anyPhrases": [
      "todo",
      "todo list",
      "blocked task"
    ]
  },
  "movement": {
    "target": "desk",
    "skipIfAlreadyThere": true
  }
}
```

When this skill is activated, the agent should go to its assigned desk before handling the request.

- Treat requests from Telegram or other external channels as valid triggers when they match this skill.
- If the agent is already at the desk, continue immediately.

Current runtime support for movement.target values:

• Defined in one source of truth: src/lib/office/places.ts.
• Current values:
• desk
• github
• gym
• qa_lab

Important:

• The JSON block is what Claw3D parses at runtime.
• Keep the prose explanation too, but do not rely on prose alone for the trigger behavior.
• activation.anyPhrases should contain short, stable phrases that are likely to appear in the user request.
• If a skill has no trigger block, Claw3D can fall back to the central default trigger registry in src/lib/office/places.ts.

2. Mirror the files into src/lib/skills/packaged.ts

Claw3D installs packaged skills from client-safe embedded strings, not by reading assets/skills/... directly at runtime.

That means every new packaged skill must also be added to src/lib/skills/packaged.ts.

For each file in assets/skills/<package-id>/, add a matching entry in the packaged file map:

const PACKAGED_SKILL_FILES: Record<string, PackagedSkillFile[]> = {
  "my-package-id": [
    {
      relativePath: "SKILL.md",
      content: MY_SKILL_MD,
    },
    {
      relativePath: "example.json",
      content: MY_EXAMPLE_JSON,
    },
  ],
};

Important:

• Keep the embedded strings exactly synchronized with the asset files.
• Do not change spacing, frontmatter, or filenames between the asset copy and packaged copy.
• tests/unit/packagedSkills.test.ts exists to catch drift for the current example. Extend it when you add more packaged skills.

3. Register the skill in src/lib/skills/catalog.ts

Add a PackagedSkillDefinition entry:

{
  packageId: "my-package-id",
  skillKey: "my-skill-key",
  name: "my-skill",
  description: "Short description.",
  installSource: "openclaw-workspace",
  creatorName: "your-handle",
  creatorUrl: "https://x.com/your-handle/",
}

Field meanings:

• packageId: internal packaged asset ID, usually the folder name under assets/skills/.
• skillKey: the OpenClaw skill key and installed folder name.
• name: the human-facing skill name shown in the UI.
• installSource: where the skill is installed. For current packaged skills this should be "openclaw-workspace".
• creatorName and creatorUrl: shown as Powered by ... in the marketplace.

4. Add marketplace presentation metadata

If you want custom category, tagline, badges, or capability labels, add an override in src/lib/skills/marketplace.ts.

Example fields:

• category
• tagline
• capabilities
• editorBadge
• hideStats

For packaged skills, creator attribution normally comes from src/lib/skills/catalog.ts.

For developer-created packaged skills, prefer real attribution over fake popularity numbers.

5. Understand where the files get installed

The current packaged install flow writes files into the selected workspace here:

<workspace>/skills/<skillKey>/

For the TODO example, that becomes:

<workspace>/skills/todo-board/
  SKILL.md
  todo-list.example.json

The skill itself can then manage additional workspace files such as:

<workspace>/todo-skill/todo-list.json

That state file is runtime data created by the skill instructions. It is separate from the installed skill package.

6. Keep the example production-ready

Use the todo-board example as the quality bar:

• The skill must define a clear trigger and physical office behavior.
• The instructions should be explicit and deterministic.
• State storage should be file-backed and documented.
• Ambiguous requests should force clarification instead of guessing.
• The installed package should contain only the files needed by the skill.
• Marketplace metadata should be honest and attributed.

7. Verify your changes

After creating or editing a packaged skill, run:

npm test -- tests/unit/packagedSkills.test.ts tests/unit/skillsInstallGateway.test.ts
npm run lint
npm run typecheck

If you add new packaged skills, update or extend the packaged skill tests so asset files, embedded copies, and marketplace metadata stay aligned.