Skip to content

nanocoai/nanoclaw / .claude/skills/add-discord

add-discord

Verified

Add Discord bot channel integration via Chat SDK.

Add Discord Channel

Adds Discord bot support via the Chat SDK bridge. NanoClaw doesn't ship channels in trunk — this skill copies the Discord adapter in from the channels branch.

The mechanical steps under Apply carry nc: directive fences: an agent reads the prose and applies them, and a parser can apply them deterministically from the same document. Every directive is idempotent, so the whole skill is safe to re-run; anything a parser can't apply falls back to the prose beside it.

Apply

1. Copy the adapter and its tests

Fetch the channels branch and copy the Discord adapter, its registration test and its gateway test into src/channels/ (overwrite — the branch is canonical):

src/channels/discord.ts
src/channels/discord-registration.test.ts
src/channels/discord-gateway.test.ts

2. Register the adapter

Append the self-registration import to the channel barrel (skipped if the line is already present). This one line is the skill's only reach-in into core:

import './discord.js';

3. Configure the adapter patch

Adapter 4.41.1 drops every server message that @mentions anyone. It serializes the Discord gateway packet after discord.js has patched it in place into a circular object, so the forward throws and the message never arrives. The committed pnpm patch backports the fix from adapter 4.42.0. Register it before installing the package. pnpm reapplies it after every install and fails if the pinned package drifts away from the patch:

patches/@chat-adapter__discord@4.41.1.patch

Re-runs only: the step below skips an adapter that is already installed, so this pnpm add moves it to 4.41.1 with the patch. A fresh install gets the patch from the step below (pnpm rejects a patch for a package that isn't installed yet):

pnpm pkg set 'pnpm.patchedDependencies[@chat-adapter/discord@4.41.1]=patches/@chat-adapter__discord@4.41.1.patch'
if node -e 'const p = require("./package.json"); process.exit(p.dependencies?.["@chat-adapter/discord"] || p.devDependencies?.["@chat-adapter/discord"] ? 0 : 1)'; then pnpm add @chat-adapter/discord@4.41.1; fi

Adapter 4.42.0 and later carry the fix. Installs keep this registration, so the bump past 4.41.1 must replace this step with an effect:refresh step that removes it before the install, or refreshes fail with ERR_PNPM_UNUSED_PATCH.

4. Install the adapter package

Pinned to an exact version — the supply-chain policy rejects ranges and latest:

@chat-adapter/discord@4.41.1

5. Build and validate

Build first: it guards the typed createChatSdkBridge(...) core call and proves the dependency is installed. Then run the two tests.

pnpm run build
pnpm exec vitest run src/channels/discord-registration.test.ts src/channels/discord-gateway.test.ts

discord-registration.test.ts imports the real channel barrel and asserts the registry contains discord. It goes red if the import line is deleted or drifts, if the barrel fails to evaluate, or if @chat-adapter/discord isn't installed (the import throws) — so it also covers the dependency from step 4. End-to-end delivery against a real server is verified manually once the service runs.

discord-gateway.test.ts feeds the installed adapter a server message that @mentions the bot, with the in-place change discord.js makes to it, and asserts the message reaches the webhook as sent. It goes red when the adapter lacks the step 3 patch.

Credentials

Discord app setup is human and interactive — no parser can click through the Discord Developer Portal. The adapter is installed and registered, but it can't receive a message until the bot exists, has Message Content Intent, and shares a server with you. Tell the user:

Create the Discord bot:
1. Go to https://discord.com/developers/applications → New Application. Name it (e.g. "NanoClaw Assistant").
2. Bot tab → Add Bot if needed → Reset Token, then copy the Bot Token (it's shown only once).
3. Bot tab → Privileged Gateway Intents → enable Message Content Intent.
4. OAuth2 → URL Generator → Scopes: bot; Bot Permissions: Send Messages, Read Message History, Add Reactions, Attach Files, Use Slash Commands.
5. Open the generated URL and invite the bot to a server you're also in (a personal server is fine) — the bot can only DM you once you share a server.

Paste the Bot Token (it's shown only once). You don't paste the Application ID or the Public Key by hand — the bot's own application record carries both, so a single call derives them from the token:

Paste the Bot Token — Bot tab. Click `Reset Token` if you need a new one.

Read the application's own record. GET /oauth2/applications/@me returns the Application ID (id), the Public Key (verify_key), and your own account as the app's owner (owner.id) — so the App ID, the Public Key, and your Discord user ID all come from this one call instead of being copied by hand. A bad token fails here, before the restart, rather than silently later:

curl -sf https://discord.com/api/v10/oauth2/applications/@me -H "Authorization: Bot {{bot_token}}"

Store the token and the two derived credentials — the adapter reads them from .env and fails to start without DISCORD_PUBLIC_KEY and DISCORD_APPLICATION_ID (set-if-absent, so a value you've already filled in is never overwritten):

DISCORD_BOT_TOKEN={{bot_token}}
DISCORD_APPLICATION_ID={{application_id}}
DISCORD_PUBLIC_KEY={{public_key}}

Restart

Restart the service so it loads the Discord adapter and the credentials you just stored, and wait for its CLI socket before resolving:

bash setup/lib/restart.sh

Invite the bot to a shared server

The bot can only DM you once it shares a server with you. If you didn't already invite it via the OAuth2 URL Generator while setting up the app, do it now: add the bot to a server you're also in (a personal server is fine). Tell the user:

Open the invite link — https://discord.com/oauth2/authorize?client_id={{application_id}}&scope=bot&permissions=2147584064 — and add the bot to a server you're also in (a personal server works fine); the bot can only DM you once you share a server. If you already invited it while setting up the app, you can skip this.

Resolve your DM channel

The agent talks to you in your direct-message channel with the bot. Your Discord user ID was already derived as the application's owner (owner_handle), so all that's left is to open the DM and read back its channel id.

Open the DM with POST /users/@me/channels and take the channel id it returns as the conversation address discord:@me:<channelId> (if Discord refuses, the bot doesn't share a server with you yet — invite it, then retry):

curl -s -X POST https://discord.com/api/v10/users/@me/channels -H "Authorization: Bot {{bot_token}}" -H "Content-Type: application/json" -d '{"recipient_id":"{{owner_handle}}"}' | jq -er '.id // error("no channel id") | "discord:@me:" + .'

owner_handle and platform_id are what the owner-wiring step needs. The greeting goes out over the DM channel, which works as soon as the bot shares a server with you.

Next Steps

If you're in the middle of /setup, return to the setup flow now. Otherwise wire this channel with /init-first-agent (or /manage-channels).

Channel Info

  • type: discord
  • terminology: Discord has "servers" (also called "guilds") containing "channels." Text channels start with #. The bot can also receive direct messages.
  • platform-id-format: discord:@me:{dmChannelId} for the owner DM (e.g. discord:@me:1399...), discord:{guildId}:{channelId} for server channels — both IDs required for channels.
  • how-to-find-id: Enable Developer Mode in Discord (Settings > App Settings > Advanced > Developer Mode). Then right-click a server and select "Copy Server ID" for the guild ID, and right-click the text channel and select "Copy Channel ID." The platform ID format used in registration is discord:{guildId}:{channelId} — both IDs are required.
  • supports-threads: yes
  • typical-use: Interactive chat — server channels or direct messages
  • default-isolation: Same agent group for your personal server. Separate agent group for servers with different communities or where different members have different information boundaries.

Troubleshooting

The Bot Token paste is rejected. The token must be at least 50 characters of letters, digits, dots, underscores, and hyphens — a real Bot Token has two . separators. It lives under Bot → Reset Token in the Developer Portal and is shown only once; reset to get a fresh one. The short numeric Application ID and the OAuth2 Client Secret are different values and won't pass.

applications/@me returns 401. The token was reset since you copied it, or a stray space/newline came along with the paste. Reset the token in the Bot tab and re-run the check — it fails here on purpose, before the restart, while the credential is still cheap to fix.

The bot is online but never sees your messages. Two usual causes: Message Content Intent is off (Bot tab → Privileged Gateway Intents), so message bodies arrive empty and nothing triggers; or the bot doesn't share a server with you — in which case POST /users/@me/channels also refuses. Open the invite URL and add the bot to a server you're in, then retry.

pnpm add, install or remove fails with ERR_PNPM_UNUSED_PATCH for @chat-adapter/discord@4.41.1. The adapter was moved off 4.41.1, the version the patch is for. Move it back with pnpm add @chat-adapter/discord@4.41.1, or re-run /add-discord. Don't drop the patch to keep a newer adapter: it needs a newer chat than the 4.41.1 that core pins, so the build fails with TS2322. To remove Discord, follow REMOVE.md, which deletes the patch registration first.

Adapter looks installed but Discord never connects. Run pnpm exec vitest run src/channels/discord-registration.test.ts — red means the barrel import or the @chat-adapter/discord install drifted, so re-run the Apply steps. If it's green, the service probably hasn't restarted since the credentials were stored: bash setup/lib/restart.sh, then check logs/nanoclaw.error.log for missing DISCORD_PUBLIC_KEY / DISCORD_APPLICATION_ID complaints.

slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall