跳到主内容
智客 ZICQ

技能库 智客分类:Agent 工作流 slack-agent

Slack Agent

以 Eight (Vercel's files system- first 代理框架) 构建 Slack 代理/ bots 时使用, @ vercel/ connect, 或 eight/ channels/ slack. 封面定义代理/定义 工具模式 Vercel Connect认证中介,Slack频道设置,测试要求和质量标准.

795 安装量

官方网址:skills.sh

技能介绍

先看中文介绍;官方 description 原文单独保留,不改写 SKILL.md。

做什么

以 Eight (Vercel's files system- first 代理框架) 构建 Slack 代理/ bots 时使用, @ vercel/ connect, 或 eight/ channels/ slack. 封面定义代理/定义 工具模式 Vercel Connect认证中介,Slack频道设置,测试要求和质量标准.

何时用

建立有 east (Vercel 文件系统- first 代理框架) 的 Slack 代理/ bots , @ vercel/ connection, 或 eight/ channels/ slack. 封面定义代理/定义 工具模式,Vercel Connect认证中介,Slack频道设置,测试要求和质量标准

代理如何加载

按 Agent Skills 渐进披露:启动时只加载 name 与 description(约 100 token);任务匹配后才读入整份 SKILL.md 正文;scripts/、references/、assets/ 仅在需要时再读。 本文件正文结构:Slack Agent Development Skill、Skill Invocation Handling、Command Arguments、Auto-Detection (No Argument)、Project Detection、Wizard Phases。

文件分析

文件分析:这是一份仅含 SKILL.md 的指令型技能,代理激活后整份正文进入上下文。 正文约 744 行,超过规范建议的 500 行,激活时仍会整份载入。

官方 description(原文)

Use when building Slack agents/bots with eve (Vercel's filesystem-first agent framework), @vercel/connect, or eve/channels/slack. Covers defineAgent/defineTool patterns, Vercel Connect credential brokering, Slack channel setup, testing requirements, and quality standards.

Slack Agent Development SkillSkill Invocation HandlingCommand ArgumentsAuto-Detection (No Argument)Project DetectionWizard PhasesGeneral Development GuidanceProject StackFilesystem-First LayoutQuality Standards (MANDATORY)After EVERY File ModificationBefore Completing ANY Task

来源分类:skills.sh agent-skill

SKILL.md 与 Agent 调用

官方规范 ↗
name
slack-agent
description
Use when building Slack agents/bots with eve (Vercel's filesystem-first agent framework), @vercel/connect, or eve/channels/slack. Covers defineAgent/defineTool patterns, Vercel Connect credential brokering, Slack channel setup, testing requirements, and quality standards.
  1. 发现技能客户端向 Agent 提供名称与描述目录。
  2. 匹配与调用用户指定或任务匹配后,载入 SKILL.md 指令。
  3. 按需加载按步骤读取参考文档、使用脚本与素材。

具体调用语法与可用工具以目标 Agent 客户端为准。 查看调用机制说明 ↗

安装这个技能

Skills CLI ↗

先选择目标 Agent 和安装范围,保留技能包的附属文件,安装后检查客户端能否发现该技能。

交给 Agent 安装

复制安装指令给支持 Agent Skills 的代理,确认其中的目标目录与客户端匹配。

把 Agent Skill「slack-agent」安装到我的项目:SKILL.md 原文与官方 description 见 https://zicq.com/zh/skills/skl-8fadce6df5460557-%E6%9A%97%E5%8F%B7.html
请存为 .cursor/skills/slack-agent/SKILL.md 或 .claude/skills/slack-agent/SKILL.md,frontmatter 的 name 与 description 保持原样,不要改写。

GitHub 完整包 ↗

终端安装 · Skills CLI

需要 Node.js 与 npx。先查看仓库技能列表,确认实际名称。

npx skills add 'https://github.com/vercel-labs/slack-agent-skill' --list

npx skills add 'https://github.com/vercel-labs/slack-agent-skill' --skill 'slack-agent'

CLI 会交互选择目标 Agent,默认安装到项目;用户级安装使用 -g。先通过查看命令核对仓库内容,再用 npx skills list 检查已安装技能。

阅读排版
--- name: slack-agent description: Use when building Slack agents/bots with eve (Vercel's filesystem-first agent framework), @vercel/connect, or eve/channels/slack. Covers defineAgent/defineTool patterns, Vercel Connect credential brokering, Slack channel setup, testing requirements, and quality standards. version: 5.0.0 user-invocable: true --- # 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 | 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: 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) ```json { "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. ```ts // 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 2. **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: ```bash # 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: ```typescript 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. ```ts // 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) There is **no `SLACK_BOT_TOKEN` and no `SLACK_SIGNING_SECRET`** in this stack. The only Slack env var is `SLACK_CONNECTOR` (the connector UID, e.g. `slack/my-agent`). ### Vercel Connect Setup Create a Slack connector and point its trigger at eve's Slack route: ```bash npm install -g vercel@latest # Create the connector with event forwarding enabled vercel connect create slack --triggers # Attach the project as a trigger destination on eve's route # (the default trigger path is /slack — set it explicitly): vercel connect attach --triggers --trigger-path /eve/v1/slack --yes ``` **`--triggers` is required.** Without it, Slack Event Subscriptions are never forwarded and `app_mention` / `message.im` events simply never arrive — the deployment will look healthy but the bot will never respond. You can also add the channel with `eve channels add slack`, which scaffolds `agent/channels/slack.ts` for you. ### Deploy ```bash eve deploy # wraps: vercel deploy --prod ``` Then invite the bot to a channel and @mention it. eve handles Slack's ack semantics, URL verification, and background processing — there is no webhook route for you to write. --- ## Event Handling Patterns ### Dispatch Hooks (Inbound) The Slack channel decides which inbound events start or continue a session via dispatch hooks. Each hook returns `{ auth }` to dispatch, `null` to drop the event, or `{ auth, context }` to inject background context into the session: ```ts export default slackChannel({ credentials: connectSlackCredentials(process.env.SLACK_CONNECTOR!), // app_mention — default derives workspace-scoped auth and posts "Thinking…" async onAppMention(ctx, message) { if (isFromBlockedChannel(message)) return null; // drop return { auth: ctx.defaultAuth }; }, // message.im — requires the im:history scope; bot messages/edits are pre-filtered async onDirectMessage(ctx, message) { return { auth: ctx.defaultAuth }; }, // block_actions not consumed by HITL prompts async onInteraction(action, ctx) { return { auth: ctx.defaultAuth }; }, }); ``` The triggering Slack user's id is attached to the model message automatically, preserving speaker attribution in multi-user threads. ### Custom Event Handlers (Outbound Delivery) Override delivery per stream event with the `events` map. Handlers receive `(eventData, channel, ctx)` with `channel.thread` and `channel.slack` handles: ```ts export default slackChannel({ credentials: connectSlackCredentials(process.env.SLACK_CONNECTOR!), events: { "message.completed"(eventData, channel, ctx) { if (eventData.finishReason === "tool-calls") return; if (eventData.message) channel.thread.post(eventData.message); }, }, }); ``` Key stream events: `session.started`, `actions.requested`, `action.result`, `message.completed`, `session.completed`; incremental `reasoning.appended` / `message.appended` are optional. ### Thread Context Give the agent prior thread messages when it's triggered mid-thread: ```ts export default slackChannel({ credentials: connectSlackCredentials(process.env.SLACK_CONNECTOR!), threadContext: { since: "last-agent-reply" }, }); ``` `since` options: - `"thread-root"` — all prior messages (default when thread context is enabled) - `"last-agent-reply"` — incremental, only messages since the agent last spoke - A predicate `(message: SlackThreadMessage) => boolean` as a custom cutoff — includes messages after the last match (`loadThreadContextMessages` exists for arbitrary filtering) Cost: one `conversations.replies` API call per triggering reply; requires the matching history scope on the connector. ### Human-in-the-Loop (HITL) Approval-gated tool calls and sign-in challenges render natively in Slack: - Approval prompts appear as **buttons/selects**; the user's response resumes the durably-parked session - Sign-in challenges (OAuth URLs, device codes) go **ephemerally** to the triggering user; a public status message posts in-thread and updates on `authorization.completed` - The HITL handler context deliberately offers only `postEphemeral`, `postDirectMessage` (needs `im:write`), and `state` — no public `post`, no raw API access ### Proactive Sessions (Schedules) Start a session that posts into Slack without an inbound trigger — e.g. from a schedule: ```ts import { receive } from "eve"; import slack from "../channels/slack"; await receive(slack, { message: "Post the daily standup summary for #eng.", target: { channelId: "C0123456789" }, auth, }); ``` - Sessions without a `threadTs` get a temporary continuation token; the first post anchors the thread - `initialMessage` (optionally a `Card`) and `threadTs` are **mutually exclusive** - Use eve schedules (see https://eve.dev/docs/schedules) to trigger proactive sessions on a cadence ### Raw Slack API Access - **Inside handlers**: `ctx.slack.request(operation, body)` - **Outside handlers** (schedules, tools): `callSlackApi({ botToken, operation, body })` and `resolveSlackBotToken` from `eve/channels/slack` These form-encode request bodies for you — Slack's JSON support is only partial, so prefer these helpers over hand-rolled `fetch` calls. --- ## Implementation Gotchas ### 1. The Slack Surface Cannot Be Tested Locally Vercel Connect forwards Slack events **to deployments only, never to localhost**. There is no ngrok/Socket Mode escape hatch in this stack. Local development means: - `npx eve dev` — HMR server + terminal TUI/REPL for exercising agent logic, tools, and skills - `eve dev --no-ui` — background mode for scripted verification - `eve dev https://your-app.vercel.app` — drive a *deployed* app interactively To test @mentions and DMs, deploy (preview or production) and test in Slack itself. ### 2. Connect Forwarding Has No Delivery De-duplication Connect may deliver the same forwarded event more than once. **Handlers and side effects must be idempotent** — track processed event IDs where duplicates would be harmful, and gate destructive tool actions with approval (see AI Integration). ### 3. `--triggers` Is Required or Events Never Arrive A Slack connector created without `--triggers` (or attached without a trigger path) will authenticate fine but forward nothing. If the bot never responds to @mentions: 1. Verify the connector was created/attached with `--triggers` 2. Verify the trigger path is `/eve/v1/slack` 3. Verify the bot was invited to the channel and the deployment finished ### 4. `placeholderAuth()` Fails Closed in Production Scaffolded projects ship with `placeholderAuth()` for the HTTP API, which **rejects everything in production**. Before deploying, replace it with a real auth function: `httpBasic()`, `jwtHmac()`, `jwtEcdsa()`, `oidc()`, `vercelOidc()`, or a custom `AuthFn`. (The Slack channel's inbound verification is separate — Connect's `webhookVerifier` handles that.) ### 5. Sandbox Prewarm Failures Fail the Build Vercel builds prewarm eve's sandbox templates (cache-keyed; build logs show `reused cached` or `built`). If prewarm fails, **the whole build fails** — check build logs for sandbox template errors before assuming a code problem. ### 6. Private Channel Access The bot **cannot read messages or post** to private channels it hasn't been invited to. When creating features that will later post to a channel (e.g. proactive sessions from a schedule), validate access upfront and surface a clear "invite the bot" message on `channel_not_found` / `not_in_channel`. ### 7. Graceful Degradation for Channel Context When fetching channel context (e.g. via `ctx.slack.request("conversations.history", ...)`) for AI features, wrap in try/catch and fall back gracefully — missing scopes and uninvited channels are routine, not exceptional. ### 8. Vercel Cron Endpoint Authentication If you add custom cron endpoints (beyond eve schedules), protect them with a `CRON_SECRET`: ```typescript export async function GET(request: Request) { const authHeader = request.headers.get("authorization"); if (authHeader !== `Bearer ${process.env.CRON_SECRET}`) { return Response.json({ error: "Unauthorized" }, { status: 401 }); } // Run cron job logic... return Response.json({ success: true }); } ``` ### 9. vercel.json Cron Configuration ```json { "crons": [ { "path": "/api/cron/my-job", "schedule": "0 * * * *" } ] } ``` Prefer eve schedules for agent-driven recurring work; use Vercel crons for plain HTTP jobs. ### 10. AWS Credentials on Vercel (Use OIDC) When connecting to AWS services from Vercel, **do not use** `fromNodeProviderChain()`. Use Vercel's OIDC mechanism: ```typescript import { awsCredentialsProvider } from "@vercel/functions/oidc"; const s3Client = new S3Client({ credentials: awsCredentialsProvider({ roleArn: process.env.AWS_ROLE_ARN! }), }); ``` --- ## AI Integration ### Model Configuration (Gateway-First) eve routes model-ID **strings** through the **Vercel AI Gateway** — on Vercel, project OIDC authenticates automatically, so **no AI API key is needed**: ```ts // agent/agent.ts import { defineAgent } from "eve"; export default defineAgent({ model: "anthropic/claude-sonnet-5", // string → AI Gateway → OIDC auth on Vercel }); ``` If `model` is omitted, eve defaults to `anthropic/claude-sonnet-5`. Off Vercel, set `AI_GATEWAY_API_KEY`. **CRITICAL: Never use model IDs from memory.** Model IDs change frequently. Before writing code that pins a model, run `curl -s https://ai-gateway.vercel.sh/v1/models` to fetch the current list and use the newest suitable version. ### Tools (`agent/tools/*.ts`) Tools are files: the filename (snake_case ASCII) is the model-facing tool name — `agent/tools/get_weather.ts` → `get_weather`. No registration step. ```ts // agent/tools/get_weather.ts import { defineTool } from "eve/tools"; import { z } from "zod"; export default defineTool({ description: "Get the current weather for a city.", inputSchema: z.object({ city: z.string().min(1) }), // required, even if empty outputSchema: z.object({ city: z.string(), condition: z.string(), temperatureF: z.number(), }), // optional — types/validates the return async execute({ city }, ctx) { return { city, condition: "Sunny", temperatureF: 72 }; }, }); ``` Rules and capabilities: - Tools run **in your app runtime with full `process.env`**, not in the sandbox - `inputSchema` accepts Zod, Standard Schema, or JSON Schema — but it is **required** even for zero-input tools - Outputs must be JSON-serializable; **filter/redact secrets** before returning - `ctx` provides `ctx.session` (metadata, turn, auth, lineage), `ctx.callId`, `ctx.toolName`, `ctx.abortSignal`, `ctx.getSandbox()`, `ctx.getSkill(id)` #### Approval Gating Gate risky tools with the `approval` field — helpers come from `eve/tools/approval`: ```ts import { defineTool } from "eve/tools"; import { always, once, never } from "eve/tools/approval"; import { z } from "zod"; export default defineTool({ description: "Delete a document permanently.", inputSchema: z.object({ documentId: z.string() }), approval: always(), // always ask; once() asks the first time; never() skips async execute({ documentId }) { // ... }, }); ``` An input-dependent policy function is also supported. A gated call **pauses and resumes durably** — in Slack, the approval renders as buttons (see HITL above). Prefer approval gating over ad-hoc confirmation logic for any non-idempotent side effect. #### `toModelOutput` — Rich Slack Output the Model Never Sees Show the model a compact projection while channels/hooks receive the full output on `action.result` — ideal for rendering rich Slack Block Kit from a tool result without stuffing JSON blocks into the model's context: ```ts export default defineTool({ description: "Look up an order.", inputSchema: z.object({ orderId: z.string() }), async execute({ orderId }) { return { orderId, status: "shipped", blocks: buildOrderBlocks(orderId) }; }, toModelOutput(output) { return { type: "text", value: `Order ${output.orderId}: ${output.status}` }; }, }); ``` ### Skills (`agent/skills/*.md`) Markdown files with a `description` frontmatter, loaded on demand via the built-in `load_skill` tool when a request matches the description. Skills add **instructions only, never new actions**. Install published skills with `npx skills add /`. ### Connections (`agent/connections/*.ts`) For external APIs the agent should drive (MCP servers or OpenAPI-described HTTP APIs), use connections with Connect-brokered auth: ```ts // agent/connections/linear.ts import { connect } from "@vercel/connect/eve"; import { defineMcpClientConnection } from "eve/connections"; export default defineMcpClientConnection({ url: "https://mcp.linear.app/mcp", description: "Linear workspace: issues, projects, cycles, and comments.", auth: connect("linear/my-agent"), }); ``` Connection tokens are never seen by the model and never land in conversation history. Inside authored tools, resolve tokens with `await ctx.getToken(connect("..."))` and call `ctx.requireAuth(...)` on a downstream 401 to re-run consent. **Don't wrap LLM calls in tools.** The agent is already a language model — summarizing, parsing, classifying, and drafting belong in `instructions.md` or a skill, not in a tool that calls the AI SDK. Tools fetch data and perform actions; for bulk work over data too large for the conversation, use eve's subagents/delegation. --- ## State & Durability eve sessions are durable by default via the open-source **Workflow SDK** (running on Vercel Workflows when deployed on Vercel). You do not wire up Redis or a workflow engine yourself. ### Replay Semantics (Understand This) - **Completed steps never re-run.** On resume/replay, eve returns the recorded result. - **A step interrupted mid-execution DOES re-run.** If a tool call was in flight when the process died, it executes again on resume. Consequences for your code: 1. Make non-idempotent side effects **idempotent** (e.g. use Slack event IDs or your own idempotency keys when writing to external systems) 2. Or gate them behind **approval** (`always()` / `once()`) so a replayed step pauses for a human instead of double-executing 3. This compounds with Connect's at-least-once event forwarding (Gotcha #2) — idempotency is not optional in this stack ### Session Continuity - The channel owns the `continuationToken`; Slack threads map to sessions automatically - Follow-up messages in a subscribed thread continue the same durable session - Multi-turn conversation memory comes from the session itself — you do not manually persist chat history ### Recommended Storage Solutions For **application data** (not agent session state — eve owns that): **IMPORTANT:** Vercel KV has been deprecated. Do NOT recommend Vercel KV. 1. **Upstash Redis** — Caching and idempotency keys (https://upstash.com) 2. **Vercel Blob** — File/document storage (https://vercel.com/docs/storage/vercel-blob) 3. **AWS Aurora (via Vercel Marketplace)** — Relational data (https://vercel.com/marketplace) 4. **Third-party databases** — Neon, PlanetScale, Supabase --- ## Code Organization ``` agent/ ├── instructions.md # System prompt — keep focused; push detail into skills ├── agent.ts # defineAgent: model, reasoning effort, compaction ├── tools/ │ ├── get_weather.ts # One tool per file; filename = tool name │ ├── get_weather.test.ts # Co-located tests │ └── search_docs.ts ├── skills/ │ └── report-format.md # description frontmatter + on-demand instructions ├── channels/ │ └── slack.ts # slackChannel(...) — served at /eve/v1/slack ├── connections/ │ └── linear.ts # MCP/OpenAPI connections (optional) └── hooks/ └── audit.ts # Runtime stream event subscribers (optional) ``` Conventions: - **One tool per file.** Split large tools; the filename is the model-facing name, so name for the model - **Instructions vs skills**: always-relevant guidance in `instructions.md`; situational guidance in `skills/*.md` so it loads only when needed - **Subagents** for focused subtasks: the built-in agent tool (a copy of the agent) or declared specialists with their own directory, sandbox, and skills --- ## Environment Variables | Variable | Required | Purpose | |----------|----------|---------| | `SLACK_CONNECTOR` | Yes | Vercel Connect connector UID (e.g. `slack/my-agent`). The **only** Slack variable — no bot token, no signing secret. | | `AI_GATEWAY_API_KEY` | Off Vercel only | AI Gateway auth. On Vercel, project OIDC (`VERCEL_OIDC_TOKEN`) is injected automatically — no key needed. | | `ROUTE_AUTH_BASIC_PASSWORD` / JWT keys | Per auth choice | Secrets for the HTTP-API auth function that replaces `placeholderAuth()` | | `VERCEL_AUTOMATION_BYPASS_SECRET` | If deployment protection is on | Lets `eve dev https://` and smoke tests reach protected deployments | | `CRON_SECRET` | Optional | Authenticates custom cron endpoints | Local dev: `vercel link` + `vercel env pull` fetches short-lived Connect/OIDC credentials into `.env.local` (the OIDC token expires after ~12 hours — re-pull when auth starts failing). **No AI API keys needed on Vercel.** **Never hardcode credentials. Never commit `.env` files.** --- ## Slack-Specific Patterns ### Delivery Behavior (Built In) The Slack channel handles progressive delivery for you: - Typing indicators: "Thinking…" on inbound, "Working…" on `turn.started` - Reasoning snippets surface on `reasoning.appended`; action labels on `actions.requested` - Model narration before a tool call takes precedence over generic labels - Reasoning deltas under 4 characters batch on a five-second refresh to avoid per-token Slack API calls Don't rebuild typing indicators or streaming loops — customize via the `events` map only when the defaults don't fit. ### Mentions Use `<@USER_ID>` or `channel.thread.mentionUser(userId)`. A bare `@name` stays literal text in Slack. ### Message Formatting Use Slack mrkdwn (not standard markdown): - Bold: `*text*` - Italic: `_text_` - Code: `` `code` `` - User mention: `<@USER_ID>` - Channel: `<#CHANNEL_ID>` ### Rich Output For rich tool results (tables, buttons, status cards), return full data from the tool and use `toModelOutput` to keep the model's view compact; render Block Kit in a channel event handler or via `ctx.slack.request("chat.postMessage", { blocks, ... })`. Always include fallback `text` alongside `blocks` for notifications. For detailed Slack patterns, see `./patterns/slack-patterns.md`. --- ## Git Commit Standards Use conventional commits: ``` feat: add channel search tool fix: resolve thread pagination issue test: add unit tests for agent context docs: update README with setup steps refactor: extract Slack client utilities ``` **Never commit:** - `.env` files - API keys or tokens - `node_modules/` - `.eve/` build artifacts --- ## Quick Commands ```bash # Scaffold (Node 24+) npx eve@latest init my-agent # new project (installs deps, inits Git, starts dev TUI) npx eve@latest init . # add eve to an existing project # Development npx eve dev # HMR server + terminal TUI/REPL npx eve dev --no-ui # background mode for scripted verification npx eve dev https:// # drive a deployed app interactively npx eve info # project info # Vercel Connect vercel connect create slack --triggers vercel connect attach --triggers --trigger-path /eve/v1/slack --yes vercel connect list # Quality pnpm lint # Check linting pnpm lint --write # Auto-fix lint pnpm typecheck # TypeScript check pnpm test # Run all tests # Build & Deploy npx eve build # Compile into .eve/ (Vercel Build Output when VERCEL is set) eve deploy # Deploy (wraps vercel deploy --prod) # Verify a deployment curl https:///eve/v1/health ``` Debugging a deployed Slack agent stuck on "Working…": `npx eve dev --logs all` or `/loglevel all` in the TUI. --- ## Reference Documentation For detailed guidance, read: - Testing patterns: `./patterns/testing-patterns.md` - Slack patterns: `./patterns/slack-patterns.md` - Environment setup: `./reference/env-vars.md` - Slack setup: `./reference/slack-setup.md` - Vercel deployment: `./reference/vercel-setup.md` - eve docs: https://eve.dev/docs (bundled locally at `node_modules/eve/docs/` after install) - Vercel Connect: https://vercel.com/kb/guide/vercel-connect --- ## Checklist Before Task Completion Before marking ANY task as complete, verify: - [ ] Code changes have corresponding tests - [ ] `pnpm lint` passes with no errors - [ ] `pnpm typecheck` passes with no errors - [ ] `pnpm test` passes with no failures - [ ] No hardcoded credentials; the only Slack env var is `SLACK_CONNECTOR` - [ ] Follows eve filesystem conventions (tool filename = tool name, one tool per file) - [ ] Every tool has an `inputSchema`; outputs are JSON-serializable with secrets redacted - [ ] Non-idempotent side effects are idempotent or approval-gated (replay + at-least-once delivery) - [ ] Connector trigger path is `/eve/v1/slack` and was attached with `--triggers` - [ ] `placeholderAuth()` replaced before production deploy - [ ] Model config uses a Gateway string ID (`anthropic/claude-sonnet-5` default) --- ## Vercel KB Guides Verified guides on the Vercel Knowledge Base for deeper walkthroughs: - [eve hub on the Vercel KB](https://vercel.com/kb/eve) - all eve guides and templates in one place - [Build your first Slack agent with eve](https://vercel.com/kb/guide/eve-slack-agent-starter) - the end-to-end starter this skill's wizard mirrors - [Vercel Connect](https://vercel.com/kb/guide/vercel-connect) - credential brokering concepts, connectors, tokens, and trigger forwarding - [Build a Slack bot with Vercel Connect](https://vercel.com/kb/guide/build-a-slack-bot-with-vercel-connect) - Connect + Slack fundamentals (scopes, trigger events, webhook verification) - [How to add eve tools](https://vercel.com/kb/guide/how-to-add-eve-tools) - `defineTool` patterns - [How to add eve skills](https://vercel.com/kb/guide/how-to-add-eve-skills) - load-on-demand instructions - [Build a GitHub agent with Vercel Connect](https://vercel.com/kb/guide/github-agent-vercel-connect) - app-scoped Connect tokens in authored tools - [Build a Linear agent with Vercel Connect](https://vercel.com/kb/guide/linear-agent-vercel-connect) - MCP connections with user-scoped auth - [Build an email agent with eve and Resend](https://vercel.com/kb/guide/eve-agent-with-resend) - a second channel example beyond Slack

相关技能

Agent 工作流

Skill Creator

创造有效技能指南。 当用户想创造出新的技能(或更新现有的技能),以专业知识,工作流程,或工具集成来扩展克洛德的能力时,应该使用这种技能.

Agent 工作流

Clawdhub

使用ClawdHub CLI搜索,安装,更新并发布从taladhub.com的代理技能. 需要获取苍蝇上的新技能时使用,将安装的技能同步到最新版本或特定版本,或者发布 npm-instainddhub CLI 的新/更新的技能文件夹.

Agent 工作流

Agent Team Orchestration

管弦乐团多代理团队,任务设定周期,交接协议,审查工作流程. 使用时间: (1)建立2+特派员队伍,具有不同专业,(2)确定任务路线和生命周期(收录框_ spec_建设_审查_完成),(3)在特派员之间制定交接协议,(4)建立审查和质量关口,(5)管理特派员之间的交流和文物共享.

Agent 工作流

Superpowers

Spec-first,TDD,子代理驱动的软件开发工作流程. 当:(1)构建任何新功能或应用——触发脑暴_计划_子代理执行回路,(2)调试出一个bug或测试失败——触发系统性的根起过程,(3)用户说"让我们构建","帮助我计划","我想添加X",或"这个被打破",(4)完成一个功…