Skills system

NanoClaw’s skills system lets you add integrations and features by merging git branches into your fork. This keeps the base codebase minimal while enabling powerful customization — all using standard git operations.

Philosophy: Skills over features

From the NanoClaw README:

Skills over features. Instead of adding features (e.g. support for Telegram) to the codebase, contributors submit claude code skills like /add-telegram that transform your fork. You end up with clean code that does exactly what you need.

This approach means:

The base NanoClaw codebase stays small (~39.8k tokens)
Each installation is customized to your exact needs
No configuration sprawl or unused features
The code remains understandable and modifiable

How skills work

Skills are distributed as git branches on the upstream repository. Applying a skill is a git merge. Updating core is a git merge. Everything is standard git.

Repository structure

The upstream repo (qwibitai/nanoclaw) maintains skill branches for features that extend core functionality:

Branch	Description
`main`	Core NanoClaw — no channel or skill code
`skill/ollama-tool`	Ollama MCP server for local models
`skill/compact`	`/compact` session command
`skill/apple-container`	Apple Container runtime (macOS)
…	And more

Each skill branch contains all the code changes for that skill: new files, modified source files, updated package.json dependencies, .env.example additions — everything.

Channel fork architecture

Channels (WhatsApp, Telegram, Discord, Slack, Gmail) live in separate fork repositories, not as skill branches on upstream. Each channel fork is a complete NanoClaw installation with the channel code already merged in.

Fork repo	Channel	Library
`qwibitai/nanoclaw-whatsapp`	WhatsApp	@whiskeysockets/baileys
`qwibitai/nanoclaw-telegram`	Telegram	grammy
`qwibitai/nanoclaw-discord`	Discord	discord.js
`qwibitai/nanoclaw-slack`	Slack	@slack/bolt (Socket Mode)
`qwibitai/nanoclaw-gmail`	Gmail	googleapis

Channels self-register at startup using the channel registry (src/channels/registry.ts). Each channel module calls registerChannel() with a factory function — the host process discovers available channels dynamically via getRegisteredChannelNames(). Channel-specific skills also live on the channel fork, not upstream:

Skill	Channel fork	What it does
`/add-voice-transcription`	nanoclaw-whatsapp	Whisper API voice transcription
`/use-local-whisper`	nanoclaw-whatsapp	Local whisper.cpp transcription
`/add-image-vision`	nanoclaw-whatsapp	Image attachment processing
`/add-reactions`	nanoclaw-whatsapp	Emoji reaction support
`/add-pdf-reader`	nanoclaw-whatsapp	PDF text extraction
`/add-telegram-swarm`	nanoclaw-telegram	Agent swarm for Telegram

The channel fork architecture keeps the upstream main branch minimal. Core NanoClaw has no channel code at all — you add exactly the channels you need by merging from the appropriate fork.

Four categories of skills

Feature skills (branch-based, installed on demand):

/add-discord, /add-telegram, /add-slack, /add-gmail, etc.
Each has a SKILL.md with setup instructions and a corresponding skill/* branch with code
Discovered through Claude Code’s plugin marketplace

Utility skills (self-contained tools with code files):

Ship code files alongside the SKILL.md (e.g., scripts in a scripts/ subfolder)
No branch merge needed — the code is self-contained in the skill directory
Example: /claw (Python CLI in scripts/claw)
Live in .claude/skills/<name>/ on main

Operational skills (on main, always available):

/setup, /debug, /update-nanoclaw, /customize, /update-skills, /get-qodo-rules, /qodo-pr-resolver, /x-integration
Instruction-only SKILL.md files — no code changes, just workflows
Live in .claude/skills/ on main

Container skills (synced into every container):

/agent-browser, /capabilities, /slack-formatting, /status
Live in container/skills/ and are synced to each group’s .claude/skills/ directory
Available to the agent running inside the container
Some are restricted to the main channel (e.g., /capabilities and /status check for the /workspace/project mount)

Applying a skill

Via Claude Code (recommended)

Run the skill command in Claude Code. For example, /add-discord triggers Claude to:

Merge the channel or skill

For a channel fork:

git remote add discord https://github.com/qwibitai/nanoclaw-discord.git
git fetch discord main
git merge discord/main

For an upstream skill branch:

git fetch upstream skill/ollama-tool
git merge upstream/skill/ollama-tool

Interactive setup

Walks you through creating the bot, getting tokens, configuring environment variables, and registering chats.

Verify

Runs build and tests to confirm everything works.

Manually

Channel (from fork repo)
Skill (from upstream branch)

git remote add discord https://github.com/qwibitai/nanoclaw-discord.git
git fetch discord main
git merge discord/main

git fetch upstream skill/ollama-tool
git merge upstream/skill/ollama-tool

Applying multiple channels

git merge discord/main
git merge telegram/main
git merge upstream/skill/ollama-tool

Git handles the composition. If multiple merges modify the same lines, it’s a real conflict — Claude resolves it automatically.

Skill discovery

Skills are available through Claude Code’s plugin marketplace. NanoClaw’s .claude/settings.json registers the official marketplace:

{
  "extraKnownMarketplaces": {
    "nanoclaw-skills": {
      "source": {
        "source": "github",
        "repo": "qwibitai/nanoclaw-skills"
      }
    }
  }
}

During /setup, the marketplace plugin is installed automatically:

claude plugin install nanoclaw-skills@nanoclaw-skills --scope project

Skills are hot-loaded after installation — no restart needed. This means /setup can install the marketplace plugin, then immediately run any feature skill, all in one session.

Skill dependencies

Some skills depend on others. For example, skill/telegram-swarm requires skill/telegram. Dependent skill branches are branched from their parent, not from main. This means skill/telegram-swarm includes all of Telegram’s changes plus its own additions. When you merge skill/telegram-swarm, you get both — no need to merge Telegram separately. Dependencies are implicit in git history — no separate dependency file is needed.

Available integration skills

Channels (from fork repos)

Channel	Command	Fork repo	Library
WhatsApp	`/add-whatsapp`	`nanoclaw-whatsapp`	@whiskeysockets/baileys
Telegram	`/add-telegram`	`nanoclaw-telegram`	grammy
Discord	`/add-discord`	`nanoclaw-discord`	discord.js
Slack	`/add-slack`	`nanoclaw-slack`	@slack/bolt (Socket Mode)
Gmail	`/add-gmail`	`nanoclaw-gmail`	googleapis

Upstream skills (from skill branches)

/add-compact — Manual context compaction skill
/add-ollama-tool — Ollama MCP server for local models
/add-parallel — Parallel AI MCP servers for web research
/convert-to-apple-container — Switch from Docker to Apple Container on macOS
/use-native-credential-proxy — Replace OneCLI gateway with built-in .env-based credential proxy

Channel-specific skills (from channel fork branches)

/add-voice-transcription — Voice message transcription (on nanoclaw-whatsapp)
/add-image-vision — Image attachment processing (on nanoclaw-whatsapp)
/add-reactions — Emoji reaction support (on nanoclaw-whatsapp)
/add-pdf-reader — PDF text extraction (on nanoclaw-whatsapp)
/add-telegram-swarm — Agent swarm support (on nanoclaw-telegram)

Updating

Updating core

git fetch upstream main
git merge upstream/main
git push origin main

Skill and channel changes are already in your git history, so git merge upstream/main just works. No skill replay step needed.

Updating channels

Channel forks track upstream, so pulling from a channel fork also brings in the latest core changes:

git fetch discord main
git merge discord/main

Checking for skill updates

Run /update-skills or let /update-nanoclaw check after a core update. For each previously-merged skill branch or channel fork that has new commits, Claude offers to merge the updates.

This requires no state files — it uses git history to determine which skills were previously merged and whether they have new commits.

Removing a skill

# Find the merge commit
git log --merges --oneline | grep discord

# Revert it
git revert -m 1 <merge-commit>

This creates a new commit that undoes the skill’s changes. If you’ve modified the skill’s code since merging, the revert might conflict — Claude resolves it.

If you later want to re-apply a reverted skill, you must revert the revert first (git treats reverted changes as “already applied and undone”). Claude handles this automatically.

Community marketplaces

Anyone can maintain their own fork with skill branches and their own marketplace repo. This enables a community-driven skill ecosystem. A community contributor:

Maintains a fork with skill/* branches
Creates a marketplace repo with a .claude-plugin/marketplace.json
Opens a PR to add their marketplace to NanoClaw’s .claude/settings.json

Users can also add marketplaces manually:

/plugin marketplace add alice/nanoclaw-skills

CI: Keeping skill branches current

A GitHub Action runs on every push to main:

Lists all skill/* branches
Merges main into each skill branch (merge-forward, not rebase)
Runs build and tests on the merged result
Pushes the updated skill branch if tests pass
Opens a GitHub issue for any skill that fails

Merge-forward (not rebase) preserves history for users who already merged the skill. No force-push needed.

Contributing a skill

As a contributor

Fork qwibitai/nanoclaw
Branch from main and make your code changes
Open a regular PR

That’s it. The maintainers create a skill/<name> branch from your PR and add the SKILL.md to the marketplace.

As a maintainer

When a skill PR is approved:

Create a skill/<name> branch from the PR’s commits
Add the skill’s SKILL.md to the marketplace repo (qwibitai/nanoclaw-skills)
The contributor is added to CONTRIBUTORS.md

Skills vs configuration files

NanoClaw deliberately avoids configuration files. From the README:

Customization = code changes. No configuration sprawl. Want different behavior? Modify the code. The codebase is small enough that it’s safe to make changes.

Skills extend this philosophy: instead of a config file with integrations: [telegram, discord, slack], you merge skill branches that modify the source code directly. You end up with code that does exactly what you need, nothing more.

Best practices

Apply skills one at a time. Test each integration before adding the next one. This makes troubleshooting easier.

Keep your fork up to date. Run /update-nanoclaw periodically to pull upstream changes, then optionally run /update-skills to pick up skill improvements.

Commit before applying a skill. Since skills are git merges, having a clean working tree makes it easy to revert if needed.

Skills modify your source code via git merge. Always ensure your working tree is clean before applying a new skill.

Next steps

Add Telegram

Add Telegram support to your installation

Add Discord

Add Discord support to your installation

Add Slack

Add Slack support to your installation

Add Gmail

Add Gmail integration to your installation

Get Started

Core Concepts

Features

Integrations

Advanced

Changelog

Philosophy: Skills over features

How skills work

Repository structure

Channel fork architecture

Four categories of skills

Applying a skill

Via Claude Code (recommended)

Manually

Applying multiple channels

Skill discovery

Skill dependencies

Available integration skills

Channels (from fork repos)

Upstream skills (from skill branches)

Channel-specific skills (from channel fork branches)

Updating

Updating core

Updating channels

Checking for skill updates

Removing a skill

Community marketplaces

CI: Keeping skill branches current

Contributing a skill

As a contributor

As a maintainer

Skills vs configuration files

Best practices

Next steps

Add Telegram

Add Discord

Add Slack

Add Gmail

Get Started

Core Concepts

Features

Integrations

Advanced

Changelog

​Philosophy: Skills over features

​How skills work

​Repository structure

​Channel fork architecture

​Four categories of skills

​Applying a skill

​Via Claude Code (recommended)

​Manually

​Applying multiple channels

​Skill discovery

​Skill dependencies

​Available integration skills

​Channels (from fork repos)

​Upstream skills (from skill branches)

​Channel-specific skills (from channel fork branches)

​Updating

​Updating core

​Updating channels

​Checking for skill updates

​Removing a skill

​Community marketplaces

​CI: Keeping skill branches current

​Contributing a skill

​As a contributor

​As a maintainer

​Skills vs configuration files

​Best practices

​Next steps

Add Telegram

Add Discord

Add Slack

Add Gmail

Philosophy: Skills over features

How skills work

Repository structure

Channel fork architecture

Four categories of skills

Applying a skill

Via Claude Code (recommended)

Manually

Applying multiple channels

Skill discovery

Skill dependencies

Available integration skills

Channels (from fork repos)

Upstream skills (from skill branches)

Channel-specific skills (from channel fork branches)

Updating

Updating core

Updating channels

Checking for skill updates

Removing a skill

Community marketplaces

CI: Keeping skill branches current

Contributing a skill

As a contributor

As a maintainer

Skills vs configuration files

Best practices

Next steps