agentleFS
jaypylesjaypyles/nanoclaw-discord/.claude/skills/setup/SKILL.md

setup

Skill2 starsChanged 9 months agoMITView on GitHub

Run initial NanoClaw setup. Use when user wants to install dependencies, configure Discord bot, register their main channel, or start the background services. Triggers on "setup", "install", "configure nanoclaw", or first-time setup requests.

  • Pipes a download into a shell
  • Reads credentials
  • Installs packages

192 other projects use a version of this, 6 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use add-atomic-chat-tool, add-dashboard and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • MicrosoftSkill

    add-atomic-chat-tool

    Add Atomic Chat MCP server so the container agent can call local models served by the Atomic Chat desktop app via its OpenAI-compatible API.

    Also in 8 projects that use this

  • MicrosoftSkill

    add-dashboard

    Add a monitoring dashboard to NanoClaw. Installs @nanoco/nanoclaw-dashboard and a pusher that sends periodic JSON snapshots.

    Also in 8 projects that use this

  • +10 more from microsoft

The file

Show its rules and text

We split this skill into the rules it gives an agent

26 rules. 0 are common, 15 are distinctive, and 11 are very specific to this project.

  • 0

    Common

    Most of the 169 edited versions we read keep these.

  • 15

    Distinctive

    This author's own choices. Worth a look.

  • 11

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Run all commands automatically.

    line 8
  2. Very specific:

    UX Note: When asking the user questions, prefer using the AskUserQuestion tool instead of just outputting text.

    line 10
  3. Distinctive:

    Check if Docker is installed and running:

    line 20
  4. Distinctive:

    If not installed or not running, tell the user:

    line 26
  5. Distinctive:

    Wait for user confirmation, then verify:

    line 43
  6. Very specific:

    If they give you the token, add it to .env:

    line 65
  7. Distinctive:

    Ask if they have an existing key to copy or need to create one.

    line 73
  8. Distinctive:

    Verify the build succeeded:

    line 103
  9. Very specific:

    Add the token to .env:

    line 124
  10. Very specific:

    If they choose something other than !nano, update it in these places:

    line 144
  11. Distinctive:

    Before registering your main channel, you need to understand an important security concept.

    line 153
  12. Distinctive:

    If they choose option 3, ask a follow-up:

    line 174
  13. Very specific:

    Create/update data/registered_groups.json using the channel ID (format: discord:CHANNEL_ID) and the assistant name from step 6:

    line 194
  14. Distinctive:

    Ensure the groups folder exists:

    line 206
  15. Distinctive:

    If no, create an empty allowlist to make this explicit:

    line 220
  16. Distinctive:

    If yes, ask follow-up questions:

    line 236
  17. Distinctive:

    Create the allowlist file based on their answers:

    line 264
  18. Distinctive:

    Verify it's running:

    line 373
  19. Very specific:

    Service not starting: Check logs/nanoclaw.error.log

    line 392
  20. Distinctive:

    Ensure the container runtime is running:

    line 395
  21. Very specific:

    Check container logs: cat groups/main/logs/container-*.log | tail -50

    line 398
  22. Very specific:

    Verify the trigger pattern matches (e.g., @AssistantName at start of message)

    line 401
  23. Very specific:

    Check that the channel is in data/registered_groups.json as discord:CHANNEL_ID

    line 402
  24. Distinctive:

    Ensure MESSAGE CONTENT INTENT is enabled for the bot in Discord Developer Portal

    line 403
  25. Very specific:

    Check logs/nanoclaw.log for errors

    line 404
  26. Very specific:

    Verify DISCORD_BOT_TOKEN in .env is correct (reset token in Developer Portal if needed)

    line 407

“Common” is measured: kept by at least 6 in 10 of the 169 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

NanoClaw Setup

Run all commands automatically. Only pause when user action is required (scanning QR codes).

UX Note: When asking the user questions, prefer using the AskUserQuestion tool instead of just outputting text. This integrates with Claude's built-in question/answer system for a better experience.

1. Install Dependencies

npm install

2. Install Docker

Check if Docker is installed and running:

docker --version && docker info >/dev/null 2>&1 && echo "Docker is running" || echo "Docker not running or not installed"

If not installed or not running, tell the user:

Docker is required for running agents in isolated environments.

macOS:

  1. Download Docker Desktop from https://docker.com/products/docker-desktop
  2. Install and start Docker Desktop
  3. Wait for the whale icon in the menu bar to stop animating

Linux:

curl -fsSL https://get.docker.com | sh
sudo systemctl start docker
sudo usermod -aG docker $USER   # Then log out and back in

Let me know when you've completed these steps.

Wait for user confirmation, then verify:

docker run --rm hello-world

3. Configure Claude Authentication

Ask the user:

Do you want to use your Claude subscription (Pro/Max) or an Anthropic API key?

Option 1: Claude Subscription (Recommended)

Tell the user:

Open another terminal window and run:

claude setup-token

A browser window will open for you to log in. Once authenticated, the token will be displayed in your terminal. Either:

  1. Paste it here and I'll add it to .env for you, or
  2. Add it to .env yourself as CLAUDE_CODE_OAUTH_TOKEN=<your-token>

If they give you the token, add it to .env:

echo "CLAUDE_CODE_OAUTH_TOKEN=<token>" > .env

Option 2: API Key

Ask if they have an existing key to copy or need to create one.

Copy existing:

grep "^ANTHROPIC_API_KEY=" /path/to/source/.env > .env

Create new:

echo 'ANTHROPIC_API_KEY=' > .env

Tell the user to add their key from https://console.anthropic.com/

Verify:

KEY=$(grep "^ANTHROPIC_API_KEY=" .env | cut -d= -f2)
[ -n "$KEY" ] && echo "API key configured: ${KEY:0:10}...${KEY: -4}" || echo "Missing"

4. Build Container Image

Build the NanoClaw agent container:

./container/build.sh

This creates the nanoclaw-agent:latest image with Node.js, Chromium, Claude Code CLI, and agent-browser.

Verify the build succeeded:

docker images | grep nanoclaw-agent
echo '{}' | docker run -i --entrypoint /bin/echo nanoclaw-agent:latest "Container OK" || echo "Container build failed"

5. Discord Bot Setup

USER ACTION REQUIRED

Tell the user:

NanoClaw uses Discord as its channel. You need to create a bot and add it to your server.

  1. Open https://discord.com/developers/applications
  2. Click New Application and name it (e.g., "NanoClaw")
  3. Go to Bot in the left sidebar → Add Bot
  4. Click Reset Token and copy the token (keep it secret)
  5. Under Privileged Gateway Intents, enable MESSAGE CONTENT INTENT (required for the bot to read messages)
  6. Go to OAuth2 → URL Generator, select scope bot and permissions: View Channels, Send Messages, Read Message History. Open the generated URL and add the bot to your server.

Add the token to .env:

echo 'DISCORD_BOT_TOKEN="your_bot_token_here"' >> .env

Verify:

grep DISCORD_BOT_TOKEN .env

To get a channel ID: In Discord, enable Developer Mode (User Settings → Advanced), then right-click the channel → Copy Channel ID.

6. Configure Assistant Name

Ask the user:

What trigger word do you want to use? (default: !nano)

Messages starting with @TriggerWord will be sent to Claude.

If they choose something other than !nano, update it in these places:

  1. groups/CLAUDE.md - Change "# nano" and "You are nano" to the new name
  2. groups/main/CLAUDE.md - Same changes at the top
  3. data/registered_groups.json - Use @NewName as the trigger when registering groups

Store their choice - you'll use it when creating the registered_groups.json and when telling them how to test.

7. Understand the Security Model

Before registering your main channel, you need to understand an important security concept.

Use the AskUserQuestion tool to present this:

Important: Your "main" channel is your admin control portal.

The main channel has elevated privileges:

  • Can see messages from ALL other registered groups
  • Can manage and delete tasks across all groups
  • Can write to global memory that all groups can read
  • Has read-write access to the entire NanoClaw project

Recommendation: Use a private Discord channel (or server) as your main channel so only you have admin control.

Question: Which setup will you use for your main channel?

Options:

  1. Personal chat (Message Yourself) - Recommended
  2. Private Discord channel (just me)
  3. Group with other people (I understand the security implications)

If they choose option 3, ask a follow-up:

You've chosen a channel with other people. This means everyone in that channel will have admin privileges over NanoClaw.

Are you sure you want to proceed? The other members will be able to:

  • Read messages from your other registered channels
  • Schedule and manage tasks
  • Access any directories you've mounted

Options:

  1. Yes, I understand and want to proceed
  2. No, let me use a private channel or DM instead

8. Register Main Channel

Ask the user:

Which Discord channel do you want as your main (admin) channel?

You need the Channel ID: In Discord, enable Developer Mode (User Settings → Advanced), then right-click the channel → Copy Channel ID.

Create/update data/registered_groups.json using the channel ID (format: discord:CHANNEL_ID) and the assistant name from step 6:

{
  "discord:CHANNEL_ID_HERE": {
    "name": "main",
    "folder": "main",
    "trigger": "@ASSISTANT_NAME",
    "added_at": "CURRENT_ISO_TIMESTAMP"
  }
}

Ensure the groups folder exists:

mkdir -p groups/main/logs

9. Configure External Directory Access (Mount Allowlist)

Ask the user:

Do you want the agent to be able to access any directories outside the NanoClaw project?

Examples: Git repositories, project folders, documents you want Claude to work on.

Note: This is optional. Without configuration, agents can only access their own group folders.

If no, create an empty allowlist to make this explicit:

mkdir -p ~/.config/nanoclaw
cat > ~/.config/nanoclaw/mount-allowlist.json << 'EOF'
{
  "allowedRoots": [],
  "blockedPatterns": [],
  "nonMainReadOnly": true
}
EOF
echo "Mount allowlist created - no external directories allowed"

Skip to the next step.

If yes, ask follow-up questions:

9a. Collect Directory Paths

Ask the user:

Which directories do you want to allow access to?

You can specify:

  • A parent folder like ~/projects (allows access to anything inside)
  • Specific paths like ~/repos/my-app

List them one per line, or give me a comma-separated list.

For each directory they provide, ask:

Should [directory] be read-write (agents can modify files) or read-only?

Read-write is needed for: code changes, creating files, git commits Read-only is safer for: reference docs, config examples, templates

9b. Configure Non-Main Group Access

Ask the user:

Should non-main groups (other Discord channels you add later) be restricted to read-only access even if read-write is allowed for the directory?

Recommended: Yes - this prevents other groups from modifying files even if you grant them access to a directory.

9c. Create the Allowlist

Create the allowlist file based on their answers:

mkdir -p ~/.config/nanoclaw

Then write the JSON file. Example for a user who wants ~/projects (read-write) and ~/docs (read-only) with non-main read-only:

cat > ~/.config/nanoclaw/mount-allowlist.json << 'EOF'
{
  "allowedRoots": [
    {
      "path": "~/projects",
      "allowReadWrite": true,
      "description": "Development projects"
    },
    {
      "path": "~/docs",
      "allowReadWrite": false,
      "description": "Reference documents"
    }
  ],
  "blockedPatterns": [],
  "nonMainReadOnly": true
}
EOF

Verify the file:

cat ~/.config/nanoclaw/mount-allowlist.json

Tell the user:

Mount allowlist configured. The following directories are now accessible:

  • ~/projects (read-write)
  • ~/docs (read-only)

Security notes:

  • Sensitive paths (.ssh, .gnupg, .aws, credentials) are always blocked
  • This config file is stored outside the project, so agents cannot modify it
  • Changes require restarting the NanoClaw service

To grant a group access to a directory, add it to their config in data/registered_groups.json:

"containerConfig": {
  "additionalMounts": [
    { "hostPath": "~/projects/my-app", "containerPath": "my-app", "readonly": false }
  ]
}

10. Configure launchd Service

Generate the plist file with correct paths automatically:

NODE_PATH=$(which node)
PROJECT_PATH=$(pwd)
HOME_PATH=$HOME

cat > ~/Library/LaunchAgents/com.nanoclaw.plist << EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.nanoclaw</string>
    <key>ProgramArguments</key>
    <array>
        <string>${NODE_PATH}</string>
        <string>${PROJECT_PATH}/dist/index.js</string>
    </array>
    <key>WorkingDirectory</key>
    <string>${PROJECT_PATH}</string>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/usr/local/bin:/usr/bin:/bin:${HOME_PATH}/.local/bin</string>
        <key>HOME</key>
        <string>${HOME_PATH}</string>
    </dict>
    <key>StandardOutPath</key>
    <string>${PROJECT_PATH}/logs/nanoclaw.log</string>
    <key>StandardErrorPath</key>
    <string>${PROJECT_PATH}/logs/nanoclaw.error.log</string>
</dict>
</plist>
EOF

echo "Created launchd plist with:"
echo "  Node: ${NODE_PATH}"
echo "  Project: ${PROJECT_PATH}"

Build and start the service:

npm run build
mkdir -p logs
launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist

Verify it's running:

launchctl list | grep nanoclaw

11. Test

Tell the user (using the assistant name they configured):

Send @ASSISTANT_NAME hello in your registered chat.

Check the logs:

tail -f logs/nanoclaw.log

The user should receive a response in Discord.

Troubleshooting

Service not starting: Check logs/nanoclaw.error.log

Container agent fails with "Claude Code process exited with code 1":

  • Ensure the container runtime is running:
    • Apple Container: container system start
    • Docker: docker info (start Docker Desktop on macOS, or sudo systemctl start docker on Linux)
  • Check container logs: cat groups/main/logs/container-*.log | tail -50

No response to messages:

  • Verify the trigger pattern matches (e.g., @AssistantName at start of message)
  • Check that the channel is in data/registered_groups.json as discord:CHANNEL_ID
  • Ensure MESSAGE CONTENT INTENT is enabled for the bot in Discord Developer Portal
  • Check logs/nanoclaw.log for errors

Discord bot offline:

  • Verify DISCORD_BOT_TOKEN in .env is correct (reset token in Developer Portal if needed)
  • Restart the service: launchctl kickstart -k gui/$(id -u)/com.nanoclaw

Unload service:

launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.