Skip to main content

​
Skills (Clawdbot)

Clawdbot 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. Clawdbot 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 Clawdbot.app)
  2. Managed/local skills: ~/.clawdbot/skills
  3. Workspace skills: <workspace>/skills
If a skill name conflicts, precedence is: <workspace>/skills (highest) → ~/.clawdbot/skills → bundled skills (lowest) Additionally, you can configure extra skill folders (lowest precedence) via skills.load.extraDirs in ~/.clawdbot/clawdbot.json.

​
Per-agent vs shared skills

In multi-agent setups, each agent has its own workspace. That means:
  • Per-agent skills live in <workspace>/skills for that agent only.
  • Shared skills live in ~/.clawdbot/skills (managed/local) and are visible to all agents on the same machine.
  • Shared folders can also be added via skills.load.extraDirs (lowest precedence) if you want a common skills pack used by multiple agents.
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 (for example, voice-call) and gate them via metadata.clawdbot.requires.config on the plugin’s config entry. See Plugins for plugin discovery/config and Tools for the tool surface those skills teach.

​
ClawdHub (install + sync)

ClawdHub is the public skills registry for Clawdbot. Use it to discover, install, update, and back up skills. Full guide: ClawdHub. Common flows:
  • Install a skill into your workspace:
    • clawdhub install <skill-slug>
  • Update all installed skills:
    • clawdhub update --all
  • Sync (scan + publish updates):
    • clawdhub sync --all
By default, clawdhub installs into ./skills under your current working directory; Clawdbot picks that up as <workspace>/skills on the next session.

​
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:
  • We follow the AgentSkills spec for layout/intent.
  • The parser used by the embedded agent supports single-line frontmatter keys only.
  • metadata should be a single-line JSON object.
  • Use {baseDir} in instructions to reference the skill folder path.
  • Optional frontmatter keys:
    • homepage — URL surfaced as “Website” in the macOS Skills UI (also supported via metadata.clawdbot.homepage).

​
Gating (load-time filters)

Clawdbot 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: {"clawdbot":{"requires":{"bins":["uv"],"env":["GEMINI_API_KEY"],"config":["browser.enabled"]},"primaryEnv":"GEMINI_API_KEY"}}
---
Fields under metadata.clawdbot:
  • always: true — always include the skill (skip other gates).
  • emoji — optional emoji used by the macOS Skills UI.
  • homepage — optional URL shown as “Website” in the macOS Skills UI.
  • os — optional list of platforms (darwin, linux, win32). If set, the skill is only eligible on those OSes.
  • requires.bins — list; each must exist on PATH.
  • requires.anyBins — list; at least one must exist on PATH.
  • requires.env — list; env var must exist or be provided in config.
  • requires.config — list of clawdbot.json paths that must be truthy.
  • primaryEnv — env var name associated with skills.entries.<name>.apiKey.
  • install — optional array of installer specs used by the macOS Skills UI (brew/node/go/uv).
Installer example: 
---
name: gemini
description: Use Gemini CLI for coding assistance and Google search lookups.
metadata: {"clawdbot":{"emoji":"♊️","requires":{"bins":["gemini"]},"install":[{"id":"brew","kind":"brew","formula":"gemini-cli","bins":["gemini"],"label":"Install Gemini CLI (brew)"}]}}
---
Notes:
  • If multiple installers are listed, the gateway picks a single preferred option (brew when available, otherwise node).
  • Node installs honor skills.install.nodeManager in clawdbot.json (default: npm; options: npm/pnpm/yarn/bun).
  • Go installs: if go is missing and brew is available, the gateway installs Go via Homebrew first and sets GOBIN to Homebrew’s bin when possible.
If no metadata.clawdbot is present, the skill is always eligible (unless disabled in config or blocked by skills.allowBundled for bundled skills).

​
Config overrides (~/.clawdbot/clawdbot.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"
        }
      },
      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.clawdbot.skillKey, use that key under skills.entries. Rules:
  • enabled: false disables the skill even if it’s bundled/installed.
  • env: injected only if the variable isn’t already set in the process.
  • apiKey: convenience for skills that declare metadata.clawdbot.primaryEnv.
  • allowBundled: optional allowlist for bundled skills only. If set, only bundled skills in the list are eligible (managed/workspace skills unaffected).

​
Environment injection (per agent run)

When an agent run starts, Clawdbot:
  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)

Clawdbot 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.

​
Token impact (skills list)

When skills are eligible, Clawdbot injects a compact XML list of available skills into the system prompt (via formatSkillsForPrompt in pi-coding-agent). The cost is deterministic:
  • Base overhead (only when ≥1 skill): 195 characters.
  • Per skill: 97 characters + the length of the XML-escaped <name>, <description>, and <location> values.
Formula (characters): 
total = 195 + Σ (97 + len(name_escaped) + len(description_escaped) + len(location_escaped))
Notes:
  • XML escaping expands & < > " ' into entities (&amp;, &lt;, etc.), increasing length.
  • Token counts vary by model tokenizer. A rough OpenAI-style estimate is ~4 chars/token, so 97 chars ≈ 24 tokens per skill plus your actual field lengths.

​
Managed skills lifecycle

Clawdbot ships a baseline set of skills as bundled skills as part of the install (npm package or Clawdbot.app). ~/.clawdbot/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 ClawdHub.