Discord Bot Architect

1---
2name: discord-bot-architect
3description: "Specialized skill for building production-ready Discord bots. Covers Discord.js (JavaScript) and Pycord (Python), gateway intents, slash commands, interactive components, rate limiting, and sharding."
4source: vibeship-spawner-skills (Apache 2.0)
5---
6 
7# Discord Bot Architect
8 
9## Patterns
10 
11### Discord.js v14 Foundation
12 
13Modern Discord bot setup with Discord.js v14 and slash commands
14 
15**When to use**: ['Building Discord bots with JavaScript/TypeScript', 'Need full gateway connection with events', 'Building bots with complex interactions']
16 
17```javascript
18```javascript
19// src/index.js
20const { Client, Collection, GatewayIntentBits, Events } = require('discord.js');
21const fs = require('node:fs');
22const path = require('node:path');
23require('dotenv').config();
24 
25// Create client with minimal required intents
26const client = new Client({
27  intents: [
28    GatewayIntentBits.Guilds,
29    // Add only what you need:
30    // GatewayIntentBits.GuildMessages,
31    // GatewayIntentBits.MessageContent,  // PRIVILEGED - avoid if possible
32  ]
33});
34 
35// Load commands
36client.commands = new Collection();
37const commandsPath = path.join(__dirname, 'commands');
38const commandFiles = fs.readdirSync(commandsPath).filter(f => f.endsWith('.js'));
39 
40for (const file of commandFiles) {
41  const filePath = path.join(commandsPath, file);
42  const command = require(filePath);
43  if ('data' in command && 'execute' in command) {
44    client.commands.set(command.data.name, command);
45  }
46}
47 
48// Load events
49const eventsPath = path.join(__dirname, 'events');
50const eventFiles = fs.readdirSync(eventsPath).filter(f => f.endsWith('.js'));
51 
52for (const file of eventFiles) {
53  const filePath = path.join(eventsPath, file);
54  const event = require(filePath);
55  if (event.once) {
56    client.once(event.name, (...args) => event.execute(...args));
57  } else {
58    client.on(event.name, (...args) => event.execute(...args));
59  }
60}
61 
62client.login(process.env.DISCORD_TOKEN);
63```
64 
65```javascript
66// src/commands/ping.js
67const { SlashCommandBuilder } = require('discord.js');
68 
69module.exports = {
70  data: new SlashCommandBuilder()
71    .setName('ping')
72    .setDescription('Replies with Pong!'),
73 
74  async execute(interaction) {
75    const sent = await interaction.reply({
76      content: 'Pinging...',
77      fetchReply: true
78    });
79 
80    const latency = sent.createdTimestamp - interaction.createdTimestamp;
81    await interaction.editReply(`Pong! Latency: ${latency}ms`);
82  }
83};
84```
85 
86```javascript
87// src/events/interactionCreate.js
88const { Events } = require('discord.js');
89 
90module.exports = {
91  name: Event
92```
93 
94### Pycord Bot Foundation
95 
96Discord bot with Pycord (Python) and application commands
97 
98**When to use**: ['Building Discord bots with Python', 'Prefer async/await patterns', 'Need good slash command support']
99 
100```python
101```python
102# main.py
103import os
104import discord
105from discord.ext import commands
106from dotenv import load_dotenv
107 
108load_dotenv()
109 
110# Configure intents - only enable what you need
111intents = discord.Intents.default()
112# intents.message_content = True  # PRIVILEGED - avoid if possible
113# intents.members = True          # PRIVILEGED
114 
115bot = commands.Bot(
116    command_prefix="!",  # Legacy, prefer slash commands
117    intents=intents
118)
119 
120@bot.event
121async def on_ready():
122    print(f"Logged in as {bot.user}")
123    # Sync commands (do this carefully - see sharp edges)
124    # await bot.sync_commands()
125 
126# Slash command
127@bot.slash_command(name="ping", description="Check bot latency")
128async def ping(ctx: discord.ApplicationContext):
129    latency = round(bot.latency * 1000)
130    await ctx.respond(f"Pong! Latency: {latency}ms")
131 
132# Slash command with options
133@bot.slash_command(name="greet", description="Greet a user")
134async def greet(
135    ctx: discord.ApplicationContext,
136    user: discord.Option(discord.Member, "User to greet"),
137    message: discord.Option(str, "Custom message", required=False)
138):
139    msg = message or "Hello!"
140    await ctx.respond(f"{user.mention}, {msg}")
141 
142# Load cogs
143for filename in os.listdir("./cogs"):
144    if filename.endswith(".py"):
145        bot.load_extension(f"cogs.{filename[:-3]}")
146 
147bot.run(os.environ["DISCORD_TOKEN"])
148```
149 
150```python
151# cogs/general.py
152import discord
153from discord.ext import commands
154 
155class General(commands.Cog):
156    def __init__(self, bot):
157        self.bot = bot
158 
159    @commands.slash_command(name="info", description="Bot information")
160    async def info(self, ctx: discord.ApplicationContext):
161        embed = discord.Embed(
162            title="Bot Info",
163            description="A helpful Discord bot",
164            color=discord.Color.blue()
165        )
166        embed.add_field(name="Servers", value=len(self.bot.guilds))
167        embed.add_field(name="Latency", value=f"{round(self.bot.latency * 1000)}ms")
168        await ctx.respond(embed=embed)
169 
170    @commands.Cog.
171```
172 
173### Interactive Components Pattern
174 
175Using buttons, select menus, and modals for rich UX
176 
177**When to use**: ['Need interactive user interfaces', 'Collecting user input beyond slash command options', 'Building menus, confirmations, or forms']
178 
179```python
180```javascript
181// Discord.js - Buttons and Select Menus
182const {
183  SlashCommandBuilder,
184  ActionRowBuilder,
185  ButtonBuilder,
186  ButtonStyle,
187  StringSelectMenuBuilder,
188  ModalBuilder,
189  TextInputBuilder,
190  TextInputStyle
191} = require('discord.js');
192 
193module.exports = {
194  data: new SlashCommandBuilder()
195    .setName('menu')
196    .setDescription('Shows an interactive menu'),
197 
198  async execute(interaction) {
199    // Button row
200    const buttonRow = new ActionRowBuilder()
201      .addComponents(
202        new ButtonBuilder()
203          .setCustomId('confirm')
204          .setLabel('Confirm')
205          .setStyle(ButtonStyle.Primary),
206        new ButtonBuilder()
207          .setCustomId('cancel')
208          .setLabel('Cancel')
209          .setStyle(ButtonStyle.Danger),
210        new ButtonBuilder()
211          .setLabel('Documentation')
212          .setURL('https://discord.js.org')
213          .setStyle(ButtonStyle.Link)  // Link buttons don't emit events
214      );
215 
216    // Select menu row (one per row, takes all 5 slots)
217    const selectRow = new ActionRowBuilder()
218      .addComponents(
219        new StringSelectMenuBuilder()
220          .setCustomId('select-role')
221          .setPlaceholder('Select a role')
222          .setMinValues(1)
223          .setMaxValues(3)
224          .addOptions([
225            { label: 'Developer', value: 'dev', emoji: '💻' },
226            { label: 'Designer', value: 'design', emoji: '🎨' },
227            { label: 'Community', value: 'community', emoji: '🎉' }
228          ])
229      );
230 
231    await interaction.reply({
232      content: 'Choose an option:',
233      components: [buttonRow, selectRow]
234    });
235 
236    // Collect responses
237    const collector = interaction.channel.createMessageComponentCollector({
238      filter: i => i.user.id === interaction.user.id,
239      time: 60_000  // 60 seconds timeout
240    });
241 
242    collector.on('collect', async i => {
243      if (i.customId === 'confirm') {
244        await i.update({ content: 'Confirmed!', components: [] });
245        collector.stop();
246      } else if (i.custo
247```
248 
249## Anti-Patterns
250 
251### ❌ Message Content for Commands
252 
253**Why bad**: Message Content Intent is privileged and deprecated for bot commands.
254Slash commands are the intended approach.
255 
256### ❌ Syncing Commands on Every Start
257 
258**Why bad**: Command registration is rate limited. Global commands take up to 1 hour
259to propagate. Syncing on every start wastes API calls and can hit limits.
260 
261### ❌ Blocking the Event Loop
262 
263**Why bad**: Discord gateway requires regular heartbeats. Blocking operations
264cause missed heartbeats and disconnections.
265 
266## ⚠️ Sharp Edges
267 
268| Issue | Severity | Solution |
269|-------|----------|----------|
270| Issue | critical | ## Acknowledge immediately, process later |
271| Issue | critical | ## Step 1: Enable in Developer Portal |
272| Issue | high | ## Use a separate deploy script (not on startup) |
273| Issue | critical | ## Never hardcode tokens |
274| Issue | high | ## Generate correct invite URL |
275| Issue | medium | ## Development: Use guild commands |
276| Issue | medium | ## Never block the event loop |
277| Issue | medium | ## Show modal immediately |
278