Slack Agent

Slack Agent Development Skill

This skill builds Slack agents with eve — Vercel's filesystem-first framework for durable backend agents — using Vercel Connect for Slack credentials:

• eve (eve package) — agent runtime, tools, channels, durability
• @vercel/connect — brokered short-lived Slack tokens; no bot tokens or signing secrets to manage

Skill Invocation Handling

When this skill is invoked via /slack-agent, check for arguments and route accordingly:

Command Arguments

Auto-Detection (No Argument)

If invoked without arguments, detect the project state and route appropriately:

1. No `package.json` with `eve` and no `agent/` directory → Treat as new, start Phase 1
2. Has eve project but no `agent/channels/slack.ts` → Start Phase 2 (Slack connector + channel)
3. Has Slack channel but no `SLACK_CONNECTOR` configured → Start Phase 3
4. Configured but not deployed → Start Phase 5 (the Slack surface only works on a deployment)
5. Deployed but no tests → Start Phase 6
6. Otherwise → Provide general assistance using this skill's patterns

Project Detection

Detect an eve project by either signal:

• `package.json` contains `"eve"` as a dependency
• An `agent/` directory with instructions.md and/or agent.ts exists

If neither is present, this is a new project: scaffold with npx eve@latest init (Node 24+ required).

Wizard Phases

The wizard is located in ./wizard/ with these phases:

• 1-project-setup.md - Understand purpose, generate custom implementation plan, scaffold with npx eve@latest init
• 1b-approve-plan.md - Present plan for user approval before scaffolding
• 2-create-slack-app.md - Create the Slack connector with Vercel Connect and add the Slack channel
• 3-configure-environment.md - Set up env vars (SLACK_CONNECTOR, model credentials)
• 4-test-locally.md - Test agent logic locally with the eve dev TUI (Slack surface tests happen after deploy)
• 5-deploy-production.md - Deploy with eve deploy, verify the Slack surface
• 6-setup-testing.md - Vitest configuration

IMPORTANT: For new projects, you MUST:

1. Read ./wizard/1-project-setup.md first
2. Ask the user what kind of agent they want to build
3. Generate a custom implementation plan using ./reference/agent-archetypes.md
4. Present the plan for approval (Phase 1b) BEFORE scaffolding the project
5. Only proceed to scaffold after the plan is approved

General Development Guidance

You are working on a Slack agent project built with eve. Follow these mandatory practices for all code changes.

Project Stack

• Framework: eve (filesystem-first agent framework; Node 24+)
• Slack channel: eve/channels/slack + @vercel/connect for credentials
• AI: model routed through Vercel AI Gateway by default (anthropic/claude-sonnet-5); tool schemas with zod
• Durability: Workflow SDK under the hood (Vercel Workflows when deployed on Vercel)
• Linting: Biome
• Package Manager: pnpm (or npm — npx eve@latest init installs with npm)

{
  "engines": { "node": "24.x" },
  "dependencies": {
    "eve": "latest",
    "ai": "latest",
    "zod": "^3.x",
    "@vercel/connect": "latest"
  }
}

Filesystem-First Layout

In eve, a file's location says what it does, and its path usually gives it its name. The whole agent lives under agent/:

agent/
├── instructions.md        # Always-on system prompt
├── agent.ts               # Runtime config (defineAgent): model, reasoning, compaction
├── tools/                 # Tools — filename (snake_case ASCII) = tool name the model sees
│   ├── get_weather.ts
│   └── search_docs.ts
├── skills/                # Load-on-demand instructions (*.md with description frontmatter)
│   └── incident-triage.md
├── channels/
│   └── slack.ts           # Slack channel — filename registers it at /eve/v1/slack
├── connections/           # MCP / OpenAPI connections (optional)
└── hooks/                 # Subscribe to runtime stream events (optional)

Even a two-file agent (instructions.md + agent.ts) gets file, shell, web, and delegation tools out of the box from the default harness. Full docs are bundled at node_modules/eve/docs/ once eve is installed — read them when a detail isn't covered here.

// agent/agent.ts
import { defineAgent } from "eve";

export default defineAgent({
  model: "anthropic/claude-sonnet-5", // routed via Vercel AI Gateway
});

Quality Standards (MANDATORY)

These quality requirements MUST be followed for every code change. There are no exceptions.

After EVERY File Modification

1. Run linting immediately: ``bash pnpm lint ``

• If errors exist, run pnpm lint --write for auto-fixes
• Manually fix remaining issues
• Re-run pnpm lint to verify

1. 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:

# 1. TypeScript compilation - must pass
pnpm typecheck

# 2. Linting - must pass with no errors
pnpm lint

# 3. Tests - all tests must pass
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.

• Location: Co-located *.test.ts files (e.g. agent/tools/get_weather.test.ts)
• Framework: Vitest
• Coverage: All exported functions and every tool's execute() (including error paths) 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:

• Dispatch hooks (onAppMention, onDirectMessage, onInteraction)
• Custom channel event handlers
• Tools the agent calls in response to Slack messages
• Delivery behavior (what gets posted to Slack)

You MUST add or update tests that verify the full flow. Remember: the Slack surface itself cannot be exercised locally (see Gotchas), so E2E coverage means unit/integration tests around your handlers plus a post-deploy smoke test.

Bot Setup Patterns (CRITICAL)

Slack Channel (agent/channels/slack.ts)

The Slack channel is a single file. Its filename registers the slack channel, served at `/eve/v1/slack` — this is the canonical trigger path everywhere in this skill.

// agent/channels/slack.ts
import { connectSlackCredentials } from "@vercel/connect/eve";
import { slackChannel } from "eve/channels/slack";

export default slackChannel({
  credentials: connectSlackCredentials(process.env.SLACK_CONNECTOR!),
});

connectSlackCredentials(connectorUid) returns { botToken, webhookVerifier }:

• botToken — resolved at runtime via Vercel Connect as a short-lived, app-scoped token; Connect handles rotation and multi-workspace tenancy
• webhookVerifier — confirms each forwarded event genuinely came from Connect (replaces Slack's native signature check)