Discord Purge Bot

Operate a Discord message cleanup workflow with an official bot token and Discord HTTP API. Use when asked to purge guild channel history, delete messages by...

Security Scan

The skill's code and runtime instructions require a Discord bot token and Node.js, but the registry metadata does not declare those credentials or binaries — an incoherence you should resolve before installing.

Purpose & Capability

The skill is a Discord purge tool and legitimately needs a bot token and Node.js to run. However, the registry metadata lists no required env vars, no primary credential, and no required binaries — despite SKILL.md and the code (resolveToken and node scripts) requiring DISCORD_BOT_TOKEN or --token and invocation via node. This mismatch is material and unexplained.

Instruction Scope

SKILL.md and the scripts constrain behavior to Discord HTTP API calls, preview/run workflows, confirm codes, and writing JSON audit artifacts. The runtime instructions do not instruct wide data collection or external exfiltration and only reference proxy env vars for HTTP routing. This is consistent with the stated purpose, but the documentation expects you to pass a bot token and run Node commands (e.g., node scripts/purge-runner.mjs).

Install Mechanism

There is no install spec (instruction-only plus included scripts), which is lower risk than downloading arbitrary binaries. The code will run as Node.js scripts; no remote downloads or obscure installers are present. Still, the package includes executable scripts that will be written to disk when installed locally — ensure you run them in a controlled environment.

Credentials

The code expects a sensitive credential (DISCORD_BOT_TOKEN or --token) and may read HTTP_PROXY/HTTPS_PROXY/NO_PROXY env vars for networking. The metadata does not declare the bot token as a required credential or list Node as a required binary. Requiring a bot token is proportionate to the task, but the omission in metadata is a security/administrative concern that could cause accidental misuse (e.g., providing a user token).

Persistence & Privilege

The skill does not request permanent 'always' inclusion, does not modify other skills, and only writes state/result JSON to paths you specify via CLI flags. It can run autonomously by default (platform default), but that is not combined with any other high-privilege or opaque behavior here.

What to consider before installing

This skill appears to implement the claimed purge functionality, but the registry metadata is inconsistent with the code and docs. Before installing or running it: (1) Treat your Discord bot token as sensitive — supply only a bot token (never a user account token). The scripts require DISCORD_BOT_TOKEN or --token even though the skill metadata doesn't declare it. (2) Ensure Node.js is installed and that the environment running these scripts is trusted; the metadata doesn't list 'node' as a required binary. (3) Review the included scripts yourself (they call only discord.com API endpoints and write JSON state files) and test in a non-production/test guild or channel. (4) Verify the bot has only the minimal permissions needed (VIEW_CHANNEL, READ_MESSAGE_HISTORY, MANAGE_MESSAGES, MANAGE_CHANNELS if using nuke) and enable auditing/monitoring. (5) Prefer running the preview flow first and require the confirmation code before destructive runs. If the registry owner cannot explain why credentials/binaries are omitted from metadata, treat the omission as a red flag and do not provide your production bot token.

Run controlled cleanup in Discord guild channels with safety gates and audit-friendly outputs.

Safety Contract

• Use only a bot token (DISCORD_BOT_TOKEN or --token).
• Refuse user-account token flows and self-bot behavior.
• Run purge-preview.mjs first for every destructive request.
• Require explicit confirmation code before running deletion.
• Abort if channel is not a guild channel.
• Keep logs and JSON summaries for each run.

Workflow

1. Collect scope: channel-id, optional author-id, contains, regex, after, before.
2. Read references/discord-limits.md before deletion runs.
3. Run preview to estimate impact and get confirm code.
4. Run deletion with confirm code.
5. Share summary: scanned, matched, deleted, failed, old-vs-recent split.

Commands

Preview

node scripts/purge-preview.mjs \
  --channel-id 123456789012345678 \
  --author-id 987654321098765432 \
  --contains "error" \
  --after "2026-03-01T00:00:00Z" \
  --max-scan 5000 \
  --out ./tmp/purge-preview.json

Run Purge

node scripts/purge-runner.mjs \
  --channel-id 123456789012345678 \
  --author-id 987654321098765432 \
  --contains "error" \
  --after "2026-03-01T00:00:00Z" \
  --confirm "PURGE-XXXXXXXX" \
  --state-file ./tmp/purge-state.json \
  --out ./tmp/purge-result.json

Dry Run

node scripts/purge-runner.mjs --channel-id 123456789012345678 --confirm "PURGE-XXXXXXXX" --dry-run

Clone or Nuke Channel

node scripts/purge-nuke.mjs --channel-id 123456789012345678 --confirm "NUKE-XXXXXXXX" --out ./tmp/nuke.json
node scripts/purge-nuke.mjs --channel-id 123456789012345678 --confirm "NUKE-XXXXXXXX" --delete-old --out ./tmp/nuke.json

Script Roles

• scripts/purge-preview.mjs: scan channel messages, apply filters, return counts and confirm code.
• scripts/purge-runner.mjs: execute deletion with 2-week split (bulk-delete + single delete fallback).
• scripts/purge-nuke.mjs: create replacement channel; optionally delete original channel.
• scripts/scan-filter.mjs: reusable scan and filtering logic.
• scripts/discord-api.mjs: Discord API wrapper with rate-limit retries.
• scripts/job-code.mjs: deterministic confirm code helpers.

Operator Rules

• Keep max-scan bounded for broad channels.
• Use --state-file on long jobs.
• Prefer content/user/time filters over whole-channel wipes.
• Use nuke mode only when preserving channel history is unnecessary.
• Treat pinned messages as protected unless --include-pinned is set.

Troubleshooting

• 401/403: verify bot token and channel permissions.
• Empty preview with expected history: check READ_MESSAGE_HISTORY.
• Heavy 429: reduce parallelism and keep retry handling enabled.
• bulk-delete failures: expect messages older than 14 days, runner falls back to single deletes.
• Cannot reach Discord behind a proxy: export HTTP_PROXY/HTTPS_PROXY (uppercase recommended) and run with NODE_USE_ENV_PROXY=1, or use a recent Node that supports setGlobalProxyFromEnv().
• If your proxy tool exposes both HTTP and SOCKS ports, point HTTP_PROXY/HTTPS_PROXY at the HTTP port; ALL_PROXY=socks5://... alone is not enough for this skill.

Proxy Example

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export NODE_USE_ENV_PROXY=1

node scripts/purge-preview.mjs --channel-id 123456789012345678 --max-scan 200