agentleFS
receptronreceptron/mulmoclaude/.claude/skills/setup-relay/SKILL.md

setup-relay

Skill388 starsChanged 7 months agoMITView on GitHub

Interactively guide MulmoBridge Relay setup — Cloudflare Workers deploy, platform secrets, and MulmoClaude connection. Respond in the user's language.

  • Reads credentials
  • Installs packages

The file

Show its rules and text

We split this skill into the rules it gives an agent

15 rules. About 0 are common, 5 are distinctive, and 10 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 10

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Check MulmoClaude is running (lsof -i :3001 -sTCP:LISTEN).

    line 11
  2. Very specific:

    Check wrangler is installed (which wrangler).

    line 12
  3. Very specific:

    Check wrangler is authenticated (wrangler whoami).

    line 16
  4. Very specific:

    workers.dev subdomain: If this is the user's first time using Workers, they need a workers.dev subdomain.

    line 21
  5. Very specific:

    Wait for the user to confirm.

    line 31
  6. Distinctive:

    Ask the user which platforms they want to set up.

    line 49
  7. Very specific:

    Verify Token: the same string used for WHATSAPP_VERIFY_TOKEN above

    line 81
  8. Distinctive:

    Add Messenger product (if not already) → Settings → Access Tokens → generate a Page Access Token for the Facebook Page you want to bridge.

    line 88
  9. Very specific:

    Verify Token: same string used for MESSENGER_VERIFY_TOKEN above

    line 98
  10. Very specific:

    Create a bot via @BotFather — /newbot — copy the token.

    line 119
  11. Distinctive:

    After creation, open the bot resource → Configuration → copy Microsoft App ID.

    line 134
  12. Very specific:

    Create a Teams app manifest (simplest path: Developer Portal → Apps → New app → set the botId to MICROSOFT_APP_ID) and install it into a …

    line 156
  13. Distinctive:

    Check the health endpoint:

    line 173
  14. Distinctive:

    Check server logs for relay connection and message delivery.

    line 189
  15. Very specific:

    Teams SingleTenant: must set both MICROSOFT_APP_TENANT_ID (secret) and MICROSOFT_APP_TYPE=SingleTenant (var in wrangler.toml) — missing …

    line 203

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “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

Setup MulmoBridge Relay

Guide the user through Relay setup following docs/message_apps/relay/. Use the language-appropriate version (README.md for English, README.ja.md for Japanese) based on the user's language.

Step 1: Prerequisites

  1. Check MulmoClaude is running (lsof -i :3001 -sTCP:LISTEN). If not, ask the user to run yarn dev first.
  2. Check wrangler is installed (which wrangler). If not:
    npm install -g wrangler
  3. Check wrangler is authenticated (wrangler whoami). If not, tell the user to run:
    ! wrangler login
    (The ! prefix runs it in the user's terminal since it requires browser interaction.)
  4. workers.dev subdomain: If this is the user's first time using Workers, they need a workers.dev subdomain. Tell them to open the Cloudflare dashboard → Compute → Workers & Pages. Opening this page for the first time automatically creates the subdomain.

Step 2: Deploy the Relay

Tell the user to run:

! cd packages/relay && wrangler deploy

Wait for the user to confirm. Ask them to paste the output URL (e.g., https://mulmobridge-relay.xxx.workers.dev).

Save the URL — you'll need it for Step 4.

Step 3: Set secrets

RELAY_TOKEN

Tell the user to run the following in their terminal (token generation + secret registration). The user should keep the generated token — it will also be needed for .env in Step 4.

# Generate token, save to clipboard/notepad, then register as secret
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
cd packages/relay && wrangler secret put RELAY_TOKEN

Platform secrets

Ask the user which platforms they want to set up. Supported webhook platforms: LINE, WhatsApp, Messenger, Google Chat, Telegram, Microsoft Teams. Only register secrets and webhook URLs for the ones they pick — /health reports configured: true/false per platform, so unused ones stay dormant with zero cost.

For each selected platform, walk through the matching block below. All wrangler secret put invocations must run from packages/relay, use the ! prefix (the user types the secret in their own terminal), and each registers exactly one secret.

LINE

  1. LINE Developers Console → channel → Messaging API tab → copy Channel secret and Channel access token (long-lived).
  2. Register:
    ! cd packages/relay && wrangler secret put LINE_CHANNEL_SECRET
    ! cd packages/relay && wrangler secret put LINE_CHANNEL_ACCESS_TOKEN
  3. In the same console screen, set Webhook URL to:
    https://<relay-url>/webhook/line
  4. Toggle Use webhook ON and verify with the console's "Verify" button.

WhatsApp (Meta Cloud API)

  1. Meta for Developers → your app → Settings → Basic → copy App Secret.
  2. In the same app → WhatsApp → API Setup → copy Access Token and Phone Number ID (the "From" field). Keep a browser tab open — you'll come back for webhook registration.
  3. Pick any string to use as your own verify token (e.g. openssl rand -hex 16). The user will paste this same string into Meta's console in a moment.
  4. Register the four secrets:
    ! cd packages/relay && wrangler secret put WHATSAPP_APP_SECRET
    ! cd packages/relay && wrangler secret put WHATSAPP_VERIFY_TOKEN
    ! cd packages/relay && wrangler secret put WHATSAPP_ACCESS_TOKEN
    ! cd packages/relay && wrangler secret put WHATSAPP_PHONE_NUMBER_ID
  5. Back in Meta console → WhatsApp → Configuration → Webhook → Edit → enter:
    • Callback URL: https://<relay-url>/webhook/whatsapp
    • Verify Token: the same string used for WHATSAPP_VERIFY_TOKEN above
    • Click Verify and save — Meta will hit the relay's GET handler and expect the verify-token echo.
  6. Under Webhook fields, subscribe to at least messages.

Messenger

  1. Meta for Developers → your app → Settings → Basic → copy App Secret (can share with WhatsApp if same app).
  2. Add Messenger product (if not already) → Settings → Access Tokens → generate a Page Access Token for the Facebook Page you want to bridge.
  3. Pick a verify-token string (same pattern as WhatsApp above).
  4. Register the three secrets:
    ! cd packages/relay && wrangler secret put MESSENGER_APP_SECRET
    ! cd packages/relay && wrangler secret put MESSENGER_VERIFY_TOKEN
    ! cd packages/relay && wrangler secret put MESSENGER_PAGE_ACCESS_TOKEN
  5. In Messenger settings → Webhooks → Add Callback URL → enter:
    • Callback URL: https://<relay-url>/webhook/messenger
    • Verify Token: same string used for MESSENGER_VERIFY_TOKEN above
  6. Subscribe the callback to the target Page under Webhooks → Add or Remove Pages. Required fields: messages, messaging_postbacks (at minimum).

Google Chat

  1. Google Cloud Console → pick/create a project → APIs & Services → enable Google Chat API.
  2. IAM & Admin → Service Accounts → create a service account (or reuse) → Keys → Add Key → Create new key → JSON → downloads a file. Keep the full JSON handy.
  3. Copy the project number (not project ID) from the console's home / Dashboard. The relay uses it as the audience claim when verifying Google's inbound JWT.
  4. Register:
    ! cd packages/relay && wrangler secret put GOOGLE_CHAT_PROJECT_NUMBER
    ! cd packages/relay && wrangler secret put GOOGLE_CHAT_SERVICE_ACCOUNT_KEY
    For GOOGLE_CHAT_SERVICE_ACCOUNT_KEY, paste the entire JSON contents at the prompt (wrangler accepts multi-line).
  5. In the Cloud Console → APIs & Services → Google Chat API → Configuration → fill:
    • App URL: https://<relay-url>/webhook/google-chat
    • Connection settings: App URL (HTTP)
    • Functionality: match what you want (1:1 DMs, spaces, etc.)

Telegram

  1. Create a bot via @BotFather — /newbot — copy the token.
  2. Pick a webhook secret (openssl rand -hex 16).
  3. Register:
    ! cd packages/relay && wrangler secret put TELEGRAM_BOT_TOKEN
    ! cd packages/relay && wrangler secret put TELEGRAM_WEBHOOK_SECRET
  4. Register the webhook via API (no GUI):
    curl "https://api.telegram.org/bot<TOKEN>/setWebhook?url=https://<relay-url>/webhook/telegram&secret_token=<SECRET>"

Microsoft Teams

  1. Azure Portal → create Azure Bot resource (pricing tier F0 for free) → choose Multi-tenant (the simplest option) or Single-tenant if the bot is company-only.
  2. After creation, open the bot resource → Configuration → copy Microsoft App ID. Click Manage next to it → Certificates & secrets → New client secret → copy the Value (shows only once).
  3. (SingleTenant only) copy the Tenant ID from the same AAD app registration page.
  4. Register secrets:
    ! cd packages/relay && wrangler secret put MICROSOFT_APP_ID
    ! cd packages/relay && wrangler secret put MICROSOFT_APP_PASSWORD
    For SingleTenant, also:
    ! cd packages/relay && wrangler secret put MICROSOFT_APP_TENANT_ID
    (Optional) AAD user object-ID allowlist:
    ! cd packages/relay && wrangler secret put TEAMS_ALLOWED_USERS
  5. Edit packages/relay/wrangler.toml and add MICROSOFT_APP_TYPE under [vars] (non-secret) — values: MultiTenant (default) or SingleTenant. Re-run wrangler deploy after editing.
  6. Back in the Azure Bot resource → Configuration → Messaging endpoint:
    https://<relay-url>/webhook/teams
    Click Apply — Azure doesn't do a verify-token handshake, but your bot won't receive messages until the endpoint is saved here.
  7. Teams channel — on the same bot resource go to Channels → Microsoft Teams → accept T&C → Apply.
  8. Create a Teams app manifest (simplest path: Developer Portal → Apps → New app → set the botId to MICROSOFT_APP_ID) and install it into a team / personal scope.

Step 4: Configure MulmoClaude

Tell the user to add the Relay connection to .env themselves. Both the URL (from Step 2) and the token (generated in Step 3) are needed:

echo "" >> .env
echo "# MulmoBridge Relay" >> .env
echo "RELAY_URL=wss://<relay-url>/ws" >> .env
echo "RELAY_TOKEN=<token-from-step-3>" >> .env

Important: The token value was generated by the user in Step 3. Do NOT generate a new token — ask the user to use the same value they registered with wrangler secret put.

Step 5: Verify

  1. Check the health endpoint:

    curl https://<relay-url>/health

    Confirm the configured platforms show true.

  2. Restart MulmoClaude:

    # Tell user to restart yarn dev
  3. Send a test message from the configured platform.
  4. Check server logs for relay connection and message delivery.

Key pitfalls to highlight

  • wrangler secret put is interactive — the user must run it themselves (use ! prefix), and must be run from packages/relay directory
  • wrangler deploy and wrangler login require browser interaction
  • workers.dev subdomain: First-time Workers users must open the Workers & Pages dashboard to auto-create their subdomain before wrangler deploy will succeed
  • The RELAY_TOKEN must be identical in both the Cloudflare secret and the .env file
  • Token management: Let the user generate and manage the token in their own terminal. Do NOT generate it in Claude's shell — this avoids the user having to copy a value back from the conversation
  • LINE webhook URL must be the Relay URL, not the old ngrok URL
  • Meta verify tokens (WhatsApp / Messenger): the same string must be in wrangler secret AND the Meta console "Verify Token" field — Meta's "Verify and save" button calls the relay's GET handler expecting that exact echo, and silently fails on mismatch with no obvious error
  • Google Chat uses the project number, not project ID — project number is numeric (found on the Cloud Console home page), project ID is the human-readable slug
  • Google Chat service-account JSON: paste the entire JSON blob (multi-line) at the wrangler prompt — do not base64-encode or try to escape it
  • Messenger webhooks require per-page subscription in addition to the app-level callback — setting only the callback URL is not enough; messages will arrive at Meta but never get forwarded to the app
  • Teams SingleTenant: must set both MICROSOFT_APP_TENANT_ID (secret) and MICROSOFT_APP_TYPE=SingleTenant (var in wrangler.toml) — missing either and /health reports teams: false
  • Teams client secret shown once: Azure's "New client secret" dialog displays the Value only on creation — if the user misses it, they have to generate a new one
  • Teams endpoint is persistent once saved: Azure doesn't verify the endpoint actively; you won't know it's wrong until a real message fails to arrive. Test with a personal-scope DM first
  • Durable Objects work on the free plan when using new_sqlite_classes in wrangler.toml (the default in this project)

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.