.claude/skills/ that Claude Code executes in your checkout. When you run /add-telegram or /manage-mounts, Claude reads the skill’s instructions and performs them — copying files, appending an import, installing a dependency, running a test. There is no plugin engine, no manifest.yaml, and no skill state file. The skill is the markdown.
This URL previously documented a different model: skills as
skill/* git branches that you merged into your fork and removed with git revert. That model was designed for v1 and never shipped in v2 — skills are not distributed as skill/* branches you merge, and no skill installs by merging a branch. If a skill’s install instructions say git merge, it isn’t built for v2. This page describes how skills actually work as of v2.1.4.How a code-carrying skill installs
Channel and provider adapters live on two long-lived registry branches (channels and providers) that upstream keeps in sync with main. The install skill fetches files from the branch and copies them in — it never merges the branch. Using /add-telegram as the canonical example:
Copy the files in
git show origin/channels:src/channels/telegram.ts > src/channels/telegram.ts — repeated for the adapter’s helpers, its tests, and its setup step. The tests travel with the code on the branch.Wire the barrel and the setup step
Append
import './telegram.js'; to src/channels/index.ts so the adapter self-registers at startup, and add the pair-telegram entry to the STEPS map in setup/index.ts. These one-line appends are the only edits to existing code.Install the dependency
pnpm install @chat-adapter/telegram — the skill installs the pinned adapter version.- Additive fetch, never a merge. Merging a registry branch into a customized install is exactly the conflict fight this model exists to avoid. The skill copies in only the files it needs.
- Idempotent. Each skill starts with a pre-flight check and every step is safe to re-run. Re-running a half-applied install completes it instead of breaking it.
- Reversible via REMOVE.md. Skills that leave anything behind ship a
REMOVE.mdalongside theSKILL.mdthat reverses every change — delete the copied files, remove the barrel import, uninstall the package, rebuild. Nogit revertinvolved.
The four categories of host skills
These are the skills you invoke as slash commands in Claude Code from your NanoClaw checkout. The skills catalog lists all of them; here’s what each category does, with one worked example apiece.| Category | Example | What installing looks like |
|---|---|---|
| Channel installs | /add-telegram | The flow above: copy the adapter from the channels branch, append the barrel import, pin the dependency, run the registration test. See Channels overview. |
| Provider installs | /add-codex | Same pattern against the providers branch, but multi-point: a provider spans the host tree and the container’s agent-runner tree, so the skill copies into both and runs a registration test per tree. See Providers. |
| Tool installs | /add-gmail-tool | Wires an MCP server into selected agent groups with vault-managed credentials: the container only ever sees onecli-managed placeholder stubs, and the OneCLI gateway injects real OAuth tokens in flight. See Tools. |
| Operational skills | /manage-mounts | Pure instruction workflows — no code copied, nothing fetched. The SKILL.md walks Claude through a task, like editing the mount allowlist through the setup CLI and restarting the service. |
Upstream’s CONTRIBUTING.md folds these into a slightly different taxonomy (channel/provider, utility, operational, container), but the install mechanics are what matter: registry-branch fetch for channels and providers, self-contained files for tools, instructions only for operational skills.
Container skills: the fifth thing
Everything above runs on the host, in your checkout. Container skills (container/skills/) are different: they’re mounted read-only at /app/skills into every agent container at spawn, and the agent inside the container loads them at runtime. You never invoke them yourself — they teach the agent how to browse the web (agent-browser), format Slack messages (slack-formatting), or even change its own NanoClaw install on request (self-customize — see Self-modification).
Which container skills a group gets is controlled by the skills column in its container config — "all" or a pinned list. See Container config.
Contributing a skill upstream
You don’t push tochannels or providers directly. You PR your adapter against main — a self-registering module, one appended barrel import, a registration test, a SKILL.md with the fetch-and-copy steps, and a REMOVE.md that reverses every change — and maintainers land the code on the registry branch from your work. Full flow in Contributing.
Updating skills
Run/update-skills (or let /update-nanoclaw trigger it after a core update) to re-fetch installed adapters from their registry branches — see Upgrading.
Next steps
Skills catalog
Every skill that ships with NanoClaw, by category
Tools
Add MCP tools and capabilities to your agents
Providers
Swap the agent runtime: Codex, OpenCode, Ollama
Write your own skill
Authoring guidelines: mostly adds, a test per integration point, a REMOVE.md