|
|
---
|
|
|
summary: "Skills: managed vs workspace, gating rules, and config/env wiring"
|
|
|
read_when:
|
|
|
- Adding or modifying skills
|
|
|
- Changing skill gating or load rules
|
|
|
---
|
|
|
# Skills (Clawdbot)
|
|
|
|
|
|
Clawdbot uses **[AgentSkills](https://agentskills.io)-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](/plugin) for plugin discovery/config and [Tools](/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](/tools/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:
|
|
|
|
|
|
```markdown
|
|
|
---
|
|
|
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):
|
|
|
|
|
|
```markdown
|
|
|
---
|
|
|
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:
|
|
|
|
|
|
```markdown
|
|
|
---
|
|
|
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:
|
|
|
|
|
|
```json5
|
|
|
{
|
|
|
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 (`&`, `<`, 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](/tools/skills-config) for the full configuration schema.
|
|
|
|
|
|
## Looking for more skills?
|
|
|
|
|
|
Browse [ClawdHub](/tools/clawdhub).
|
|
|
|
|
|
---
|