> ## Documentation Index > Fetch the complete documentation index at: https://docs.nanoclaw.dev/llms.txt > Use this file to discover all available pages before exploring further. # Skills: how NanoClaw extends itself > What a NanoClaw skill is in v2 — SKILL.md workflows that a coding harness executes in your checkout, fetching code additively from registry branches. Never a git merge. A NanoClaw skill is a **SKILL.md instruction workflow** in `.claude/skills/` that a coding harness (Claude Code, Codex, OpenCode) executes in your checkout. When you invoke `add-telegram` or `manage-mounts`, the coding harness reads the skill's instructions and performs them: copying files, appending an import, installing a dependency, running a test. There is no manifest.yaml and no skill state file. The skill *is* the markdown — the mechanical steps in trunk install skills also carry `nc:` directive fences, so the setup wizard can apply the same document a coding harness would read, and anything it can't apply mechanically falls back to the prose beside it. Two readers, one document. 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. This is how the trunk stays small: it ships channel and provider *infrastructure* but no specific adapters. Your fork only ever contains the code for the features you installed — the rest stays out of your context window and your upgrade path. ## 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: `git fetch origin channels` `git show origin/channels:src/channels/telegram.ts > src/channels/telegram.ts` — repeated for the adapter's helpers and their tests. The tests travel with the code on the branch. (The `pair-telegram` setup step ships in trunk, so it isn't copied.) Append `import './telegram.js';` to `src/channels/index.ts` so the adapter self-registers at startup. This one-line append is the skill's only reach-in into existing code — its `STEPS`-map entry for `setup/index.ts` already ships in trunk and idempotently skips on a normal install. The skill pins `@chat-adapter/telegram` to an exact version — never a range or `latest`; the supply-chain policy rejects both. `pnpm run build`, then the copied registration test — it imports the real channel barrel and asserts the registry contains `telegram`. If the import line is deleted, the barrel fails to evaluate, or the dependency is missing, this test goes red. Three properties hold across every install skill: * **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.** Every step guards itself, and the `nc:` directives are idempotent by construction (`copy` overwrites, `append` skips-if-present). Re-running a half-applied install completes it instead of breaking it. * **Reversible via REMOVE.md.** Skills that leave anything behind ship a `REMOVE.md` alongside the `SKILL.md` that reverses every change — delete the copied files, remove the barrel import, uninstall the package, rebuild. No `git revert` involved. ## The four categories of host skills These are the skills you invoke from your coding harness in your NanoClaw checkout. The [skills catalog](/reference/skills-catalog) lists all of them; here's what each category does, with one worked example apiece. The `/name` form below is Claude Code's. Codex invokes the same skill as `$add-telegram` and does not accept `/add-telegram`; OpenCode loads it through its own `skill` tool, with no typed form. The skill file is the same one in every case. A few skills still phrase their steps in Claude Code's tool vocabulary, which other harnesses follow best-effort. | 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](/channels/overview). | | **Provider installs** | `/add-codex` | Same pattern against the `providers` branch, but multi-point: a provider spans three trees — the host, the container's agent-runner, and setup — so the skill appends an import to each of the three provider barrels and runs a registration guard per tree. See [Providers](/extend/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](/extend/tools). | | **Operational skills** | `/manage-mounts` | Pure instruction workflows — no code copied, nothing fetched. The SKILL.md walks the coding harness 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`), introduce itself on a newly wired channel (`welcome`), or even change its own NanoClaw install on request (`self-customize` — see [Self-modification](/extend/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](/reference/container-config#skills). ## Contributing a skill upstream You don't push to `channels` 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](/concepts/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](/operate/upgrading). ## Next steps Every skill that ships with NanoClaw, by category Add MCP tools and capabilities to your agents Swap the agent runtime: Codex, OpenCode, Ollama Authoring guidelines: mostly adds, a test per integration point, a REMOVE.md