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.

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

​
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 docs/skills-config.md for the full configuration schema.

​
Looking for more skills?

Browse ClawdHub.