Examples

---
name: setup
description: Run initial NanoClaw setup. Use when user wants to install dependencies, authenticate messaging channels, 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

git diff main...upstream/skill/telegram

---
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

### 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.

### 1. Copy the script

mkdir -p scripts
cp "${CLAUDE_SKILL_DIR}/scripts/claw" scripts/claw
chmod +x scripts/claw

### 2. Symlink into PATH

mkdir -p ~/bin
ln -sf "$(pwd)/scripts/claw" ~/bin/claw

def get_groups(db: Path) -> list[dict]:
    conn = sqlite3.connect(db)
    rows = conn.execute(
        "SELECT jid, name, folder, is_main FROM registered_groups ORDER BY name"
    ).fetchall()
    conn.close()
    return [{"jid": r[0], "name": r[1], "folder": r[2], "is_main": bool(r[3])} for r in rows]

if line.strip() == "---NANOCLAW_OUTPUT_END---":
    dbg("output sentinel found, terminating container")
    done.set()
    proc.kill()