Examples

---
name: setup
description: Run initial NanoClaw setup. Use when user wants to install dependencies, authenticate WhatsApp, register their main channel, or start the background services.
---

# NanoClaw Setup

**Principle:** 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.

**UX Note:** Use `AskUserQuestion` for all user-facing questions.

## 1. Bootstrap (Node.js + Dependencies)

Run `bash setup.sh` and parse the status block.

- If NODE_OK=false → Node.js is missing or too old. Use `AskUserQuestion: Would you like me to install Node.js 22?`
  - macOS: `brew install node@22` or install nvm
  - Linux: `curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -`
...

### 3a. Choose runtime

- PLATFORM=linux → Docker (only option)
- PLATFORM=macos + APPLE_CONTAINER=installed → 
  AskUserQuestion: Docker (default) or Apple Container?
- PLATFORM=macos + APPLE_CONTAINER=not_found → Docker (default)

**If BUILD_OK=false:** Read `logs/setup.log` tail for the build error.
- Cache issue: `docker builder prune -f` and retry
- Dockerfile syntax: diagnose from log and fix, then retry

**If TEST_OK=false but BUILD_OK=true:** The image built but won't run.
- Check logs — common cause is runtime not fully started
- Wait a moment and retry the test

.claude/skills/add-telegram/
├── SKILL.md
├── manifest.yaml
├── add/
│   └── src/channels/
│       ├── telegram.ts        # Complete implementation
│       └── telegram.test.ts   # 46 unit tests
├── modify/
│   └── src/
│       ├── index.ts           # Multi-channel support
│       ├── index.ts.intent.md
│       ├── config.ts          # Telegram config
│       └── config.ts.intent.md
└── tests/
    └── telegram.test.ts       # Integration tests

skill: telegram
version: 1.0.0
description: "Telegram Bot API integration via Grammy"
core_version: 0.1.0
adds:
  - src/channels/telegram.ts
  - src/channels/telegram.test.ts
modifies:
  - src/index.ts
  - src/config.ts
  - src/routing.test.ts
structured:
  npm_dependencies:
    grammy: "^1.39.3"
  env_additions:
    - TELEGRAM_BOT_TOKEN
    - TELEGRAM_ONLY
conflicts: []
depends: []
test: "npx vitest run src/channels/telegram.test.ts"

# Intent: src/index.ts modifications

## What changed
Refactored from single WhatsApp channel to multi-channel architecture 
using the `Channel` interface.

## Key sections

### Imports (top of file)
- Added: `TelegramChannel` from `./channels/telegram.js`
- Added: `TELEGRAM_BOT_TOKEN`, `TELEGRAM_ONLY` from `./config.js`
- Added: `findChannel` from `./router.js`
- Added: `Channel` type from `./types.js`

### Module-level state
- Added: `const channels: Channel[] = []` — array of all active channels
- Kept: `let whatsapp: WhatsAppChannel` — still needed for 
  `syncGroupMetadata` reference

### processGroupMessages()
- Added: `findChannel(channels, chatJid)` lookup at the start
- Changed: `whatsapp.setTyping()` → `channel.setTyping?.()` 
  (optional chaining)
- Changed: `whatsapp.sendMessage()` → `channel.sendMessage()` in 
  output callback

## Invariants
- All existing message processing logic (triggers, cursors, idle timers) 
  is preserved
- The `runAgent` function is completely unchanged
- State management (loadState/saveState) is unchanged
- Recovery logic is unchanged

## Must-keep
- The `escapeXml` and `formatMessages` re-exports
- The `_setRegisteredGroups` test helper
- All error handling and cursor rollback logic

---
name: customize
description: Add new capabilities or modify NanoClaw behavior. Use when user wants to add channels, change triggers, add integrations, or make any other customizations.
---

# NanoClaw Customization

## Workflow

1. **Understand the request** - Ask clarifying questions
2. **Plan the changes** - Identify files to modify
3. **Implement** - Make changes directly to the code
4. **Test guidance** - Tell user how to verify

## Common Customization Patterns

### Adding a New Input Channel

Questions to ask:
- Which channel? (Telegram, Slack, Discord, email, SMS, etc.)
- Same trigger word or different?
- Same memory hierarchy or separate?

Implementation pattern:
1. Create `src/channels/{name}.ts` implementing the `Channel` interface
2. Add the channel instance to `main()` in `src/index.ts`
3. Messages are stored via the `onMessage` callback

.claude/skills/add-slack/
├── SKILL.md
├── SLACK_SETUP.md        # Step-by-step setup guide
├── manifest.yaml
├── add/
└── modify/

### Create Slack App (if needed)

If the user doesn't have a Slack app, share [SLACK_SETUP.md](SLACK_SETUP.md) 
which has step-by-step instructions with screenshots guidance, troubleshooting, 
and a token reference table.

Quick summary of what's needed:
1. Create a Slack app at api.slack.com/apps
2. Enable Socket Mode and generate an App-Level Token
3. Subscribe to bot events: `message.channels`, `message.groups`, `message.im`
4. Add OAuth scopes: `chat:write`, `channels:history`, etc.
5. Install to workspace and copy the Bot Token

## Known Limitations

- **Threads are flattened** — Threaded replies are delivered to the agent 
  as regular channel messages. The agent sees them but has no awareness 
  they originated in a thread. Responses always go to the channel, not 
  back into the thread.
  
- **No typing indicator** — Slack's Bot API does not expose a typing 
  indicator endpoint. The `setTyping()` method is a no-op.
  
- **Message splitting is naive** — Long messages are split at a fixed 
  4000-character boundary, which may break mid-word or mid-sentence.
  
- **No file/image handling** — The bot only processes text content. File 
  uploads, images, and rich message blocks are not forwarded to the agent.