Skip to main content

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.

NanoClaw is designed to stay small and minimal. Contributions should prioritize reducing code, not adding features.

​
Philosophy

NanoClaw is not a framework that tries to support every use case. It’s software that each user customizes to fit their exact needs. Instead of adding features to the codebase, we contribute skills that teach Claude Code how to transform a NanoClaw installation.

​
What we accept

​
Source code changes

Fixes for broken functionality, crashes, or incorrect behavior.Example: Fix message cursor advancing before agent succeeds, causing messages to be lost on timeout.
Patches for security vulnerabilities or improvements to the security model.Example: Add symlink resolution to mount validation to prevent traversal attacks.
Refactoring that reduces complexity, removes dependencies, or makes the codebase easier to understand.Example: Consolidate duplicate mount validation logic into a single function.
Removing unnecessary code, dependencies, or features.Example: Remove unused configuration options.
New capabilities, integrations, or functionality expansions.Why: Features should be skills, not source code.Example: Adding Telegram support, Gmail integration, or new scheduling options.
Improvements to existing features or performance optimizations.Why: Users should customize their fork to add enhancements they need.Example: Adding caching, improving query performance, or adding retry logic.
Support for new platforms, runtimes, or environments.Why: Compatibility changes should be skills.Example: Adding Windows support, Podman support, or ARM64 optimization.

​
Contributing skills

A skill is a markdown file that teaches Claude Code how to transform or extend a NanoClaw installation. NanoClaw has four types of skills, each serving a different purpose.

​
Skill types

Feature skills — add capabilities by merging a skill/* branch. The SKILL.md contains setup instructions; the actual code lives on the branch.
skill/telegram branch
src/channels/telegram.ts
src/index.ts
package.json
.env.example
Utility skills — standalone tools that ship code files alongside the SKILL.md. No branch merge needed.
.claude/skills
claw
SKILL.md
scripts
claw
Operational skills — instruction-only SKILL.md files on main with no code changes.
.claude/skills
debug
SKILL.md
Container skills — loaded inside agent containers at runtime from container/skills/.

​
Writing a skill

1

For feature skills: make code changes on a branch

Branch from main and make your code changes directly:
git checkout -b skill/my-integration main
# Add new files, modify source, update package.json
git commit -m "Add my-integration support"
The branch should contain all the code needed for the integration — new files, modified source files, updated dependencies, .env.example additions.
2

For utility skills: create a self-contained directory

Create .claude/skills/{name}/ with a SKILL.md and supporting code files (e.g., in a scripts/ subfolder). Use ${CLAUDE_SKILL_DIR} to reference files in the skill directory. Put code in separate files, not inline in the SKILL.md.
3

For operational skills: write SKILL.md

Create a SKILL.md in .claude/skills/{name}/ on main. The skill should contain instructions Claude follows to execute a workflow.
---
name: debug
description: Troubleshoot NanoClaw issues
---

# Debug

## 1. Check service status
...
4

For container skills: add to container/skills/

Create container/skills/{name}/SKILL.md. Keep skills focused — the agent’s context window is shared across all container skills.
5

Include context and rationale

For feature skills, write a SKILL.md for the marketplace that explains setup steps and design decisions.
## Design decisions

- Use polling instead of webhooks for simplicity
- Store Telegram credentials in the `.env` file
- Reuse the existing message queue system
6

Test on a fresh clone

Before submitting, test your skill on a fresh NanoClaw fork:
git clone https://github.com/qwibitai/NanoClaw.git test-nanoclaw
cd test-nanoclaw
git merge origin/skill/my-integration
npm install && npm test && npm run build

​
Why skills instead of features?

Every user should have clean and minimal code that does exactly what they need. Skills let users selectively add features to their fork without inheriting code for features they don’t want. 
# User A wants WhatsApp only
git clone nanoclaw
claude /setup
# Clean codebase, no Telegram code

# User B wants Telegram
git clone nanoclaw
claude /setup
claude /add-telegram
# Merges skill/telegram branch — clean code with Telegram support

​
Skill guidelines

Feature skills are skill/* branches that contain all code changes for the integration — including modifications to src/, container/, package.json, etc. This is by design: the skill branch is the complete diff from main.Utility skills ship code alongside the SKILL.md but don’t modify source files — the code is self-contained in the skill directory. Operational skills are instruction-only.
Users should be able to remove a skill’s changes if they no longer want it. Include removal instructions in the skill or create a separate /remove-{feature} skill.
Skills should work together without conflicts. If your skill is incompatible with another skill, document this clearly.
Skills that add new capabilities must respect the existing security model. Don’t bypass container isolation, mount validation, or IPC authorization.

​
Request for skills (RFS)

Skills we’d like to see contributed:

​
Communication channels

Slack, Discord, Telegram, and Gmail integrations already exist! Check the integrations overview.
  • /add-signal - Add Signal integration
  • /add-matrix - Add Matrix integration
  • /add-whatsapp-cloud-api - Add WhatsApp Cloud API (for business accounts)

​
Deployment

  • /deploy-railway - Deploy NanoClaw to Railway
  • /deploy-fly - Deploy NanoClaw to Fly.io
  • /deploy-vps - Deploy NanoClaw to a VPS with systemd

​
Integrations

  • /add-calendar - Google Calendar integration
  • /add-todoist - Todoist integration
  • /add-notion - Notion integration

​
Runtime

  • /convert-to-podman - Switch from Docker to Podman
  • /add-windows-support - WSL2 support for Windows

​
Submitting a contribution

1

Fork the repository

git clone https://github.com/qwibitai/NanoClaw.git
cd NanoClaw
git checkout -b my-contribution
2

Make your changes

For operational skills:
mkdir -p .claude/skills/my-skill
# Write SKILL.md
For feature skills:
# Branch from main and make code changes
# Add new files, modify source, update package.json, etc.
npm run build
npm test
For source changes (bug fixes, simplifications):
# Edit files in src/, container/, etc.
npm run build
npm test
3

Test thoroughly

For feature skills:
# Test merging into a fresh clone
cd /tmp
git clone https://github.com/qwibitai/NanoClaw.git test-nanoclaw
cd test-nanoclaw
git remote add fork /path/to/your/fork
git fetch fork my-contribution
git merge fork/my-contribution
npm install && npm test && npm run build
For source changes:
npm test
npm run build
# Manual testing
4

Create a pull request

git add .
git commit -m "Add /my-skill for X functionality"
git push origin my-contribution
Then open a PR on GitHub with:
  • Clear description of what the contribution does
  • Why it should be accepted (follows contribution guidelines)
  • Testing notes
For feature skills, maintainers will create a skill/<name> branch from your PR and add the SKILL.md to the marketplace.

​
Code style

When contributing source code:
  • Follow existing TypeScript conventions
  • Use meaningful variable names
  • Add comments for non-obvious logic
  • Keep functions small and focused
  • Prefer explicit over implicit
NanoClaw doesn’t use a linter or formatter. Code style is enforced through review. The goal is readability and simplicity, not stylistic uniformity.

​
Getting help

If you’re working on a contribution and need help:
  1. Ask Claude Code: Describe what you’re trying to do. Claude can help write skills or refactor code.
  2. Join the Discord: Community Discord
  3. Open a draft PR: Start a discussion before the work is complete.

​
License

By contributing to NanoClaw, you agree that your contributions will be licensed under the MIT License.
Last modified on March 23, 2026