Skills are NanoClaw’s approach to extending functionality. Instead of adding features to the core codebase, you create skills that teach Claude Code how to transform a user’s fork to add exactly what they need.
Philosophy
Skills over features. Instead of adding features (e.g. support for Telegram) to the codebase, contributors submit skills like /add-telegram that transform your fork. You end up with clean code that does exactly what you need.
From the NanoClaw README:
NanoClaw isn’t a monolithic framework; it’s software that fits each user’s exact needs. Instead of becoming bloatware, NanoClaw is designed to be bespoke. You make your own fork and have Claude Code modify it to match your needs.
How skills work
There are four types of skills:
- Feature skills — git branches (
skill/*) containing all code changes for an integration, plus a SKILL.md in the marketplace repo. Applying a feature skill is a git merge.
- Utility skills — self-contained tools that ship code files alongside the
SKILL.md in .claude/skills/<name>/. No branch merge needed — the code lives in the skill directory (e.g., scripts/). Example: /claw.
- Operational skills —
SKILL.md files in .claude/skills/ on main. These are instruction-only: they guide Claude Code through workflows like setup, debugging, and updates. No code changes.
- Container skills — loaded inside agent containers at runtime from
container/skills/. They teach the container agent how to use tools, format output, or perform tasks.
Creating your first skill
Choose a skill type
Feature skill — if your skill adds code changes to the codebase (new channel, integration, tool):
- Code changes live on a
skill/* branch
- SKILL.md with setup instructions goes in the marketplace repo
Utility skill — if your skill is a standalone tool with its own code files:
- Code lives alongside the SKILL.md in
.claude/skills/{name}/
- No branch merge needed — self-contained in the skill directory
- Use
${CLAUDE_SKILL_DIR} to reference files
Operational skill — if your skill is a workflow or guide (setup, debug, customize):
- Lives in
.claude/skills/{name}/SKILL.md on main
- No code changes, just instructions
Container skill — if your skill runs inside the agent container:
- Lives in
container/skills/{name}/
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"
.env.example additions. 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.
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
...
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.
Structure the skill content
Organize instructions into clear phases:## Phase 1: Pre-flight
### Check prerequisites
- What needs to exist before running?
- What to ask the user?
### Collect configuration
Use `AskUserQuestion` for user input.
## Phase 2: Implementation
### Step-by-step instructions
- What commands to run?
- What files to modify?
- What to validate?
## Phase 3: Verification
### Test the changes
- How to verify it works?
- What logs to check?
## Troubleshooting
### Common issues
- Problem: Description
- Solution: How to fix
Test the skill
For operational skills, run the skill command in Claude Code:Then run /your-skill-name and verify it works as expected.For feature skills, test merging the branch into a fresh fork:git fetch origin skill/my-integration
git merge origin/skill/my-integration
npm test
npm run build
Best practices
Writing clear instructions
Principle from /setup: When something is broken or missing, fix it. Don’t tell the user to go fix it themselves unless it genuinely requires their manual action (e.g. scanning a QR code, pasting a secret token).
- Use
AskUserQuestion for all user-facing questions
- Provide clear, step-by-step commands
- Include error recovery steps
- Show expected output and how to verify success
Always use AskUserQuestion instead of asking in prose:
AskUserQuestion: Should this channel replace existing channels or run alongside them?
- **Replace existing channels** - New channel will be the only one
- **Alongside** - Both channels active
Error handling
Provide specific troubleshooting steps:
## Troubleshooting
### Bot not responding
Check:
1. `TELEGRAM_BOT_TOKEN` is set in `.env` AND synced to `data/env/env`
2. Chat is registered in SQLite
3. For non-main chats: message includes trigger pattern
4. Service is running: `launchctl list | grep nanoclaw`
### Build and restart
```bash
npm run build
launchctl kickstart -k gui/$(id -u)/com.nanoclaw # macOS
# Linux: systemctl --user restart nanoclaw
### Verification steps
Always include a verification phase:
```markdown
## Phase 5: Verify
### Test the connection
Tell the user:
> Send a message to your registered chat:
> - For main chat: Any message works
> - For non-main: `@Andy hello` or @mention the bot
>
> The bot should respond within a few seconds.
### Check logs if needed
```bash
tail -f logs/nanoclaw.log
## Next steps
- Learn about [Skill structure](/api/skills/skill-structure) for both skill types
- See [Examples](/api/skills/examples) of real skills from the repository
- Read the [Skills system overview](/integrations/skills-system) for the full architecture
## Contributing skills
When you're ready to contribute:
1. Fork `qwibitai/nanoclaw`
2. For feature skills: branch from `main`, make your code changes, and open a PR
3. For utility skills: add your skill directory (SKILL.md + code files) to `.claude/skills/` and open a PR
4. For operational or container skills: add your `SKILL.md` to the appropriate directory and open a PR
5. Test your skill on a fresh NanoClaw installation
6. Verify it works on macOS, Linux, and Windows/WSL2 (if applicable)
7. Include comprehensive troubleshooting steps
For feature skills, the maintainers will create a `skill/<name>` branch from your PR and add the `SKILL.md` to the marketplace.
**Remember:** Don't add features. Add skills. Users run `/your-skill` on their fork and get clean code that does exactly what they need.
