coderClaw

Skills (CoderClaw)

CoderClaw uses AgentSkills-compatible skill folders to teach the agent how to use tools. Each skill is a directory containing a SKILL.md with YAML frontmatter and instructions. CoderClaw loads bundled skills plus optional local overrides, and filters them at load time based on environment, config, and binary presence.

Locations and precedence

Skills are loaded from three places:

  1. Bundled skills: shipped with the install (npm package or CoderClaw.app)
  2. Managed/local skills: ~/.coderclaw/skills
  3. Workspace skills: <workspace>/skills

If a skill name conflicts, precedence is:

<workspace>/skills (highest) → ~/.coderclaw/skills → bundled skills (lowest)

Additionally, you can configure extra skill folders (lowest precedence) via skills.load.extraDirs in ~/.coderclaw/coderclaw.json.

Per-agent vs shared skills

In multi-agent setups, each agent has its own workspace. That means:

If the same skill name exists in more than one place, the usual precedence applies: workspace wins, then managed/local, then bundled.

Plugins + skills

Plugins can ship their own skills by listing skills directories in coderclaw.plugin.json (paths relative to the plugin root). Plugin skills load when the plugin is enabled and participate in the normal skill precedence rules. You can gate them via metadata.coderclaw.requires.config on the plugin’s config entry. See Plugins for discovery/config and Tools for the tool surface those skills teach.

ClawHub (install + sync)

ClawHub is the public skills registry for CoderClaw. Browse at https://clawhub.com. Use it to discover, install, update, and back up skills. Full guide: ClawHub.

Common flows:

By default, clawhub installs into ./skills under your current working directory (or falls back to the configured CoderClaw workspace). CoderClaw picks that up as <workspace>/skills on the next session.

Security notes

Format (AgentSkills + Pi-compatible)

SKILL.md must include at least:

---
name: nano-banana-pro
description: Generate or edit images via Gemini 3 Pro Image
---

Notes:

Gating (load-time filters)

CoderClaw filters skills at load time using metadata (single-line JSON):

---
name: nano-banana-pro
description: Generate or edit images via Gemini 3 Pro Image
metadata:
  {
    "coderclaw":
      {
        "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] },
        "primaryEnv": "GEMINI_API_KEY",
      },
  }
---

Fields under metadata.coderclaw:

Note on sandboxing:

Installer example:

---
name: gemini
description: Use Gemini CLI for coding assistance and Google search lookups.
metadata:
  {
    "coderclaw":
      {
        "emoji": "♊️",
        "requires": { "bins": ["gemini"] },
        "install":
          [
            {
              "id": "brew",
              "kind": "brew",
              "formula": "gemini-cli",
              "bins": ["gemini"],
              "label": "Install Gemini CLI (brew)",
            },
          ],
      },
  }
---

Notes:

If no metadata.coderclaw is present, the skill is always eligible (unless disabled in config or blocked by skills.allowBundled for bundled skills).

Config overrides (~/.coderclaw/coderclaw.json)

Bundled/managed skills can be toggled and supplied with env values:

{
  skills: {
    entries: {
      "nano-banana-pro": {
        enabled: true,
        apiKey: "GEMINI_KEY_HERE",
        env: {
          GEMINI_API_KEY: "GEMINI_KEY_HERE",
        },
        config: {
          endpoint: "https://example.invalid",
          model: "nano-pro",
        },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

Note: if the skill name contains hyphens, quote the key (JSON5 allows quoted keys).

Config keys match the skill name by default. If a skill defines metadata.coderclaw.skillKey, use that key under skills.entries.

Rules:

Environment injection (per agent run)

When an agent run starts, CoderClaw:

  1. Reads skill metadata.
  2. Applies any skills.entries.<key>.env or skills.entries.<key>.apiKey to process.env.
  3. Builds the system prompt with eligible skills.
  4. Restores the original environment after the run ends.

This is scoped to the agent run, not a global shell environment.

Session snapshot (performance)

CoderClaw snapshots the eligible skills when a session starts and reuses that list for subsequent turns in the same session. Changes to skills or config take effect on the next new session.

Skills can also refresh mid-session when the skills watcher is enabled or when a new eligible remote node appears (see below). Think of this as a hot reload: the refreshed list is picked up on the next agent turn.

Remote macOS nodes (Linux gateway)

If the Gateway is running on Linux but a macOS node is connected with system.run allowed (Exec approvals security not set to deny), CoderClaw can treat macOS-only skills as eligible when the required binaries are present on that node. The agent should execute those skills via the nodes tool (typically nodes.run).

This relies on the node reporting its command support and on a bin probe via system.run. If the macOS node goes offline later, the skills remain visible; invocations may fail until the node reconnects.

Skills watcher (auto-refresh)

By default, CoderClaw watches skill folders and bumps the skills snapshot when SKILL.md files change. Configure this under skills.load:

{
  skills: {
    load: {
      watch: true,
      watchDebounceMs: 250,
    },
  },
}

Token impact (skills list)

When skills are eligible, CoderClaw injects a compact XML list of available skills into the system prompt (via formatSkillsForPrompt in pi-coding-agent). The cost is deterministic:

Formula (characters):

total = 195 + Σ (97 + len(name_escaped) + len(description_escaped) + len(location_escaped))

Notes:

Managed skills lifecycle

CoderClaw ships a baseline set of skills as bundled skills as part of the install (npm package or CoderClaw.app). ~/.coderclaw/skills exists for local overrides (for example, pinning/patching a skill without changing the bundled copy). Workspace skills are user-owned and override both on name conflicts.

Config reference

See Skills config for the full configuration schema.

Looking for more skills?

Browse https://clawhub.com.

This site is open source. Improve this page.