Slack Agent Development Skill
This skill supports two frameworks for building Slack agents:
- Chat SDK (Recommended for new projects) —
chat + @chat-adapter/slack
- Bolt for JavaScript (For existing Bolt projects) —
@slack/bolt + @vercel/slack-bolt
Skill Invocation Handling
When this skill is invoked via /slack-agent, check for arguments and route accordingly:
Command Arguments
| Argument |
Action |
new |
Run the setup wizard from Phase 1. Read ./wizard/1-project-setup.md and guide the user through creating a new Slack agent. |
configure |
Start wizard at Phase 2 or 3 for existing projects |
deploy |
Start wizard at Phase 5 for production deployment |
test |
Start wizard at Phase 6 to set up testing |
| (no argument) |
Auto-detect based on project state (see below) |
Auto-Detection (No Argument)
If invoked without arguments, detect the project state and route appropriately:
- No
package.json with chat or @slack/bolt → Treat as new, start Phase 1
- Has project but no customized
manifest.json → Start Phase 2
- Has project but no
.env file → Start Phase 3
- Has
.env but not tested → Start Phase 4
- Tested but not deployed → Start Phase 5
- Otherwise → Provide general assistance using this skill's patterns
Framework Detection
Detect which framework the project uses:
package.json contains "chat" → Chat SDK projectpackage.json contains "@slack/bolt" → Bolt project- Neither detected → New project, recommend Chat SDK (offer Bolt as alternative)
Store the detected framework and use it to show the correct patterns throughout the wizard and development guidance.
Wizard Phases
The wizard is located in ./wizard/ with these phases:
1-project-setup.md - Understand purpose, choose framework, generate custom implementation plan1b-approve-plan.md - Present plan for user approval before scaffolding2-create-slack-app.md - Customize manifest, create app in Slack3-configure-environment.md - Set up .env with credentials4-test-locally.md - Dev server + ngrok tunnel5-deploy-production.md - Vercel deployment6-setup-testing.md - Vitest configuration
IMPORTANT: For new projects, you MUST:
- Read
./wizard/1-project-setup.md first
- Ask the user what kind of agent they want to build
- Offer framework choice (Chat SDK recommended, Bolt as alternative)
- Generate a custom implementation plan using
./reference/agent-archetypes.md
- Present the plan for approval (Phase 1b) BEFORE scaffolding the project
- Only proceed to scaffold after the plan is approved
Framework Selection Guide
| Aspect |
Chat SDK |
Bolt for JavaScript |
| Best for |
New projects |
Existing Bolt codebases |
| Packages |
chat, @chat-adapter/slack, @chat-adapter/state-redis |
@slack/bolt, @vercel/slack-bolt |
| Server |
Next.js App Router |
Nitro (H3-based) |
| Event handling |
bot.onNewMention(), bot.onSubscribedMessage() |
app.event(), app.command(), app.message() |
| Webhook route |
app/api/webhooks/[platform]/route.ts |
server/api/slack/events.post.ts |
| Message posting |
thread.post("text") / thread.post(<Card>...) |
client.chat.postMessage({ channel, text, blocks }) |
| UI components |
JSX: <Card>, <Button>, <Actions> |
Raw Block Kit JSON |
| State |
@chat-adapter/state-redis / thread.state |
Manual / Vercel Workflow |
| Config |
new Chat({ adapters: { slack } }) |
new App({ token, signingSecret, receiver }) |
General Development Guidance
You are working on a Slack agent project. Follow these mandatory practices for all code changes.
Project Stack
If using Chat SDK
- Framework: Next.js (App Router)
- Chat SDK:
chat + @chat-adapter/slack for Slack bot functionality
- State:
@chat-adapter/state-redis for state persistence (or in-memory for development)
- AI: AI SDK v6 with @ai-sdk/gateway
- Linting: Biome
- Package Manager: pnpm
{
"dependencies": {
"ai": "^6.0.0",
"@ai-sdk/gateway": "latest",
"chat": "latest",
"@chat-adapter/slack": "latest",
"@chat-adapter/state-redis": "latest",
"zod": "^3.x",
"next": "^15.x"
}
}
If using Bolt for JavaScript
- Server: Nitro (H3-based) with file-based routing
- Slack SDK:
@vercel/slack-bolt for serverless Slack apps (wraps Bolt for JavaScript)
- AI: AI SDK v6 with @ai-sdk/gateway
- Workflows: Workflow DevKit for durable execution
- Linting: Biome
- Package Manager: pnpm
{
"dependencies": {
"ai": "^6.0.0",
"@ai-sdk/gateway": "latest",
"@slack/bolt": "^4.x",
"@vercel/slack-bolt": "^1.0.2",
"zod": "^3.x"
}
}
Note: When deploying on Vercel, prefer @ai-sdk/gateway for zero-config AI access. Use direct provider SDKs (@ai-sdk/openai, @ai-sdk/anthropic, etc.) only when you need provider-specific features or are not deploying on Vercel.
Quality Standards (MANDATORY)
These quality requirements MUST be followed for every code change. There are no exceptions.
After EVERY File Modification
-
Run linting immediately:
pnpm lint
- If errors exist, run
pnpm lint --write for auto-fixes
- Manually fix remaining issues
- Re-run
pnpm lint to verify
-
Check for corresponding test file:
- If you modified
foo.ts, check if foo.test.ts exists
- If no test file exists and the file exports functions, create one
Before Completing ANY Task
You MUST run all quality checks and fix any issues before marking a task complete:
pnpm typecheck
pnpm lint
pnpm test
Do NOT complete a task if any of these fail. Fix the issues first.
Unit Tests Required
For ANY code change, you MUST write or update unit tests.
If using Chat SDK
- Location: Co-located
*.test.ts files or lib/__tests__/
- Framework: Vitest
- Coverage: All exported functions must have tests
If using Bolt for JavaScript
- Location: Co-located
*.test.ts files or server/__tests__/
- Framework: Vitest
- Coverage: All exported functions must have tests
Example test structure:
import { describe, it, expect, vi } from 'vitest';
import { myFunction } from './my-module';
describe('myFunction', () => {
it('should handle normal input', () => {
expect(myFunction('input')).toBe('expected');
});
it('should handle edge cases', () => {
expect(myFunction('')).toBe('default');
});
});
E2E Tests for User-Facing Changes
If you modify:
- Bot mention handlers / Slack message handlers
- Slash commands
- Interactive components (buttons, modals)
- Bot responses
You MUST add or update E2E tests that verify the full flow.
Bot Setup Patterns (CRITICAL)
If using Chat SDK
Use the Chat SDK to define your bot instance. This is the central entry point for all Slack bot functionality.
Bot Instance (lib/bot.ts or lib/bot.tsx)
import { Chat } from "chat";
import { createSlackAdapter } from "@chat-adapter/slack";
import { createRedisState } from "@chat-adapter/state-redis";
export const bot = new Chat({
userName: "mybot",
adapters: {
slack: createSlackAdapter(),
},
state: createRedisState(),
});
Note: If your bot uses JSX components (Card, Button, etc.), the file must use the .tsx extension.
Webhook Route (app/api/webhooks/[platform]/route.ts)
import { after } from "next/server";
import { bot } from "@/lib/bot";
export async function POST(request: Request, context: { params: Promise<{ platform: string }> }) {
const { platform } = await context.params;
const handler = bot.webhooks[platform as keyof typeof bot.webhooks];
if (!handler) return new Response("Unknown platform", { status: 404 });
return handler(request, { waitUntil: (task) => after(() => task) });
}
The Chat SDK automatically handles:
- Content-type detection (JSON vs form-urlencoded)
- URL verification challenges
- Slack's 3-second ack timeout
- Background processing via
waitUntil
- Signature verification
If using Bolt for JavaScript
Use @vercel/slack-bolt to handle all Slack events. This package automatically handles:
- Content-type detection (JSON vs form-urlencoded)
- URL verification challenges
- 3-second ack timeout (built-in
ackTimeoutMs: 3001)
- Background processing via Vercel Fluid Compute's
waitUntil
Bolt App Setup (server/bolt/app.ts)
