.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.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:
1
Fetch the registry branch
git fetch origin channels2
Copy the files in
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.)3
Wire the barrel
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.4
Install the dependency
The skill pins
@chat-adapter/telegram to an exact version — never a range or latest; the supply-chain policy rejects both.5
Build and run the registration test
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.- 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 (copyoverwrites,appendskips-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.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 from your coding harness in your NanoClaw checkout. The 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.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).
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