@zibby/skills 0.1.23 → 0.1.25

package/docs/skills/function-skill.md

@@ -0,0 +1,93 @@
+---
+sidebar_position: 10
+title: Function skill
+---
+
+# Function skill
+
+Author a custom skill as a single async function. No MCP server to write, no spawn config, no glue — just a `handler({ args })` that returns a JSON-serializable result. Zibby auto-bridges it through MCP at runtime so any Claude/Cursor/Codex node can call it.
+
+For wrapping a full external MCP server, use the same `skill()` factory with a `resolve()` instead of a `handler` — see the MCP skill example at the bottom.
+
+## API
+
+```js
+import { skill } from '@zibby/skills';
+
+export const myTool = skill('my_tool', {
+  description: 'One-line description shown to the model',
+  input: {
+    foo: 'string',
+    bar: { type: 'number', description: 'Optional knob', required: false },
+  },
+  handler: async ({ foo, bar = 0 }) => {
+    return { result: foo.repeat(bar) };
+  },
+});
+```
+
+| Field | Type | Notes |
+|---|---|---|
+| `description` | `string` | Shown to the LLM as the tool description |
+| `input` | `Record<string, string \| { type, description?, required? }>` | Shorthand schema. String values mean `{ type: <string>, required: true }` |
+| `handler` | `async (args) => any` | Return value is `JSON.stringify`'d back to the model |
+
+Calling `skill()` both creates and **registers** the skill in the global registry, so just importing the module is enough to make it available.
+
+## Use in a workflow
+
+Once registered, reference by id:
+
+```js
+import { WorkflowAgent, WorkflowGraph } from '@zibby/core';
+import './skills/my-tool.js'; // import for the side effect
+
+graph.addNode('process', {
+  agent: 'claude',
+  skills: ['my_tool'],
+  prompt: (state) => `Call my_tool with foo="hello", bar=3 and report what you got back.`,
+});
+```
+
+The tool surfaces to the model as `my_tool` (and to MCP-aware strategies as `mcp__my_tool__my_tool`).
+
+## Output example
+
+For the example above:
+
+```json
+{ "result": "hellohellohello" }
+```
+
+If `handler` throws, the error message is returned to the model as the tool result so it can recover or retry.
+
+## Wrapping an external MCP server
+
+Same factory, different shape — provide `resolve()` instead of `handler`:
+
+```js
+import { skill } from '@zibby/skills';
+
+export const linear = skill('linear', {
+  description: 'Linear issue tracker',
+  serverName: 'linear',
+  allowedTools: ['mcp__linear__*'],
+  envKeys: ['LINEAR_API_KEY'],
+  resolve() {
+    if (!process.env.LINEAR_API_KEY) return null;
+    return {
+      command: 'npx',
+      args: ['-y', '@anthropic/linear-mcp-server'],
+      env: { LINEAR_API_KEY: process.env.LINEAR_API_KEY },
+    };
+  },
+});
+```
+
+Return `null` from `resolve()` to silently disable the skill when its prerequisites aren't met (no env var, no bin, etc.) — the node still runs, the model just doesn't see those tools.
+
+## Implementation notes
+
+Function skills route through a tiny stdio MCP bridge (`@zibby/core/function-bridge.js`) that the strategy spawns. The bridge imports your skill module, runs the handler in-process, and proxies the result back via MCP — so the agent SDK sees a real MCP server even though you didn't write one.
+
+When you ship a skill in a published package, derive bin/module paths from `import.meta.url`, **not** `require.resolve('@your/pkg/...')`. esbuild emits a `dist/package.json` that makes package self-references resolve to `dist/...` instead of the package root, which silently breaks the lookup. Every Zibby-shipped skill (sentry, lark, jira) uses the `import.meta.url` pattern for this reason.

package/docs/skills/github.md

@@ -0,0 +1,91 @@
+---
+sidebar_position: 4
+title: GitHub
+---
+
+# GitHub skill
+
+Read repos, list and inspect PRs, search code and issues, read files, clone repositories, create issues.
+
+- **ID:** `github`
+- **MCP server:** `github` (tools exposed as `mcp__github__*`)
+- **Underlying server:** `npx @modelcontextprotocol/server-github@latest`
+
+## Tools provided
+
+| Tool | What it does |
+|---|---|
+| `github_list_repos` | List accessible repos (private + public). Defaults to all installation repos when no `owner` given |
+| `github_search_repos` | Substring search across accessible repo names and descriptions |
+| `github_get_user` | Authenticated user (or GitHub App installation owner) |
+| `github_list_orgs` | Organizations with accessible repos |
+| `github_clone` | `git clone` a repo locally, defaulting to `~/zibby-repos/<repo>`; accepts `destination` |
+| `github_get_file` | Read a file's content (or list a directory) at a `ref` |
+| `github_list_commits` | Recent commits on a branch, optionally filtered by `path` |
+| `github_get_commit` | Full commit details + per-file patches |
+| `github_search_issues` | GitHub search-syntax across issues and PRs |
+| `github_search_code` | Code search, optionally scoped to `repo` or `language` |
+| `github_get_pr` | PR metadata (title, branch, stats) |
+| `github_get_pr_diff` | Unified diff (capped at 15 KB) |
+| `github_list_pr_files` | Files changed in a PR with per-file patches |
+| `github_list_pr_comments` | Review + issue comments combined, sorted ascending |
+| `github_create_issue` | Create a new issue |
+
+## Setup
+
+Two options:
+
+**GitHub App (recommended).** In **Settings → Integrations**, click **Connect GitHub**, install the Zibby GitHub App on the orgs/repos you want, and authorize. Tokens auto-refresh; you don't manage them. See the [GitHub Integration page](../integrations/github.md) for the full app permissions list.
+
+**Personal access token.** Set `GITHUB_TOKEN` in your workflow's env (locally) or via **Cloud → Env vars** (cloud runs). Scope `repo` for private read+write, `public_repo` for public-only.
+
+The skill reads `envKeys: ['GITHUB_TOKEN']` and the official `@modelcontextprotocol/server-github` consumes it directly.
+
+## Use in a workflow
+
+```js
+import { WorkflowAgent, WorkflowGraph } from '@zibby/core';
+import { SKILLS } from '@zibby/skills';
+
+export class PrSummarizer extends WorkflowAgent {
+  buildGraph() {
+    const graph = new WorkflowGraph();
+    graph.addNode('summarize_pr', {
+      agent: 'claude',
+      skills: [SKILLS.GITHUB],
+      prompt: (state) => `Get PR #${state.prNumber} on ${state.owner}/${state.repo}.
+      Read the diff with github_get_pr_diff and list reviewer comments with
+      github_list_pr_comments. Produce a 4-bullet summary of what changed and any
+      open review threads.`,
+    });
+    return graph;
+  }
+}
+```
+
+## Output example
+
+`github_get_pr`:
+
+```json
+{
+  "number": 142,
+  "title": "fix(auth): refresh token on 401",
+  "state": "open",
+  "merged": false,
+  "user": "alice",
+  "branch": "fix-auth-refresh",
+  "base": "main",
+  "changedFiles": 3,
+  "additions": 47,
+  "deletions": 12,
+  "url": "https://github.com/acme/app/pull/142",
+  "labels": ["bug", "auth"]
+}
+```
+
+## Implementation notes
+
+`skill.resolve()` returns `{ command: 'npx', args: ['-y', '@modelcontextprotocol/server-github@latest'], env }` — the official upstream MCP server. The skill's `handleToolCall` implementation (with GitHub App-aware behavior for `/user` and `/user/orgs`) is used by the `assistant` agent strategy and by any caller that bypasses MCP.
+
+For GitHub App installation tokens, `/user` and `/user/orgs` are server-to-server-forbidden; the in-process handlers transparently fall back to `/installation/repositories` and derive the owner/orgs from there.

package/docs/skills/index.md

@@ -0,0 +1,42 @@
+---
+sidebar_position: 0
+title: Skills reference
+---
+
+# Skills reference
+
+Per-skill reference for everything shipped in `@zibby/skills`. For the mental model and how to attach skills to nodes, see [Concepts → Skills](../concepts/skills.md). For the package-level API (`skill()` factory, `registerSkill`, middleware), see [`@zibby/skills`](../packages/skills.md).
+
+## Built-in skills
+
+| Skill | ID | Tools | Setup |
+|---|---|---|---|
+| [Browser](./browser.md) | `browser` | Playwright (navigate, click, type, snapshot, video) | None — bundled with `@zibby/cli` |
+| [Sentry](./sentry.md) | `sentry` | `sentry_list_projects`, `sentry_list_issues`, `sentry_get_issue` | OAuth (PKCE) |
+| [Lark](./lark.md) | `lark` | `lark_send_message`, `lark_reply`, `lark_list_chats`, `lark_get_chat_history` | App ID + App Secret |
+| [GitHub](./github.md) | `github` | Repos, PRs, issues, commits, file reads, clone | GitHub App or `GITHUB_TOKEN` |
+| [Slack](./slack.md) | `slack` | Channels, post/reply, reactions, history, users | Bot token + team ID |
+| [Jira](./jira.md) | `jira` | Issues, sprints, comments, transitions | Atlassian OAuth |
+| [Memory](./memory.md) | `memory` | Test history, selectors, page model (Dolt) | `zibby init --mem` |
+| [Chat memory](./chat-memory.md) | `chat-memory` | `memory_store`, `memory_recall`, `memory_brief`, `task_log`, `task_history` | None (Dolt or mem0) |
+| [Core tools](./core-tools.md) | `core-tools` | `read_file`, `write_file`, `list_directory`, `run_command`, `open_url`, `wait` | None |
+| [Function skill](./function-skill.md) | n/a | Author-defined | Define with `skill()` |
+
+## Attaching a skill
+
+```js
+import { WorkflowAgent, WorkflowGraph } from '@zibby/core';
+import { SKILLS } from '@zibby/skills';
+
+graph.addNode('triage', {
+  agent: 'claude',
+  skills: [SKILLS.SENTRY, SKILLS.SLACK],
+  prompt: (state) => `Find unresolved Sentry issues and post a summary to #alerts.`,
+});
+```
+
+## MCP architecture in one paragraph
+
+When a node executes, the strategy reads its `skills` array. For each skill it calls `skill.resolve(...)`, which returns either a stdio spawn spec (`{ command, args, env }`) or `null` for in-process skills. The Agent SDK launches each spec as an MCP server and exposes its tools to the LLM under the prefix `mcp__<serverName>__<tool>`. The skill's `promptFragment` is appended to the system prompt so the model knows the tools exist. In-process skills (`core-tools`, `chat-memory`, function skills with a `handler`) skip the spawn and the strategy dispatches tool calls directly via `handleToolCall`.
+
+See [`@zibby/skills`](../packages/skills.md) for the full skill object shape and how to author your own.

package/docs/skills/jira.md

@@ -0,0 +1,99 @@
+---
+sidebar_position: 6
+title: Jira
+---
+
+# Jira skill
+
+Read/write Jira Cloud — search issues, manage sprints, transition tickets, manage comments. Backed by a custom Zibby MCP server (`@zibby/mcp-jira`).
+
+- **ID:** `jira`
+- **MCP server:** `jira` (tools exposed as `mcp__jira__*`)
+
+## Tools provided
+
+| Tool | What it does |
+|---|---|
+| `jira_list_projects` | List all accessible Jira projects |
+| `jira_list_statuses` | Status catalog. Pass `projectKey` for the project workflow's statuses; omit for the global catalog |
+| `jira_list_issue_types` | Issue types allowed for issue creation in a `projectKey` |
+| `jira_search` | JQL search. Auto-bounds queries with `created >= -365d` if no `ORDER BY` is given |
+| `jira_get_issue` | Full details for an `issueKey` |
+| `jira_create_issue` | Create an issue. Supports `moveToSprint` + `sprintId`/`sprintName`/`target` for atomic "create and place in sprint" |
+| `jira_list_sprints` | Sprints for a project, optionally filtered by `state` (`active`/`closed`/`future`) |
+| `jira_get_sprint_issues` | Issues in a sprint, optionally filtered by status — returns status breakdown |
+| `jira_move_issue_to_sprint` | Move an issue to a sprint by id, name, or target (`current`/`active`/`latest`) with membership verification |
+| `jira_get_comments` | Comments on an issue (newest first), ADF flattened to markdown |
+| `jira_add_comment` | Add a plain-text comment |
+| `jira_edit_issue` | PUT arbitrary fields (summary, labels, priority, story points, custom fields) |
+| `jira_transition_issue` | Move to another status by `transitionId` or `toStatus`; lists available transitions when neither is provided |
+
+## Setup
+
+Jira uses Atlassian OAuth 2.0 (3LO).
+
+1. In the Zibby dashboard, **Settings → Integrations → Connect Jira**.
+2. Authorize Zibby for your Atlassian site.
+3. In **Settings → Jira Configuration**, pick the project/space to use as the default.
+
+See the [Jira Integration page](../integrations/jira.md) for the user-facing setup. Tokens auto-refresh; reconnect from the same panel if refresh fails.
+
+Under the hood the bin reads `ATLASSIAN_ACCESS_TOKEN` + `ATLASSIAN_CLOUD_ID` (and optional `ATLASSIAN_INSTANCE_URL`), which the backend supplies through `resolveIntegrationToken('jira')`.
+
+## Use in a workflow
+
+```js
+import { WorkflowAgent, WorkflowGraph } from '@zibby/core';
+import { SKILLS } from '@zibby/skills';
+
+export class StandupBot extends WorkflowAgent {
+  buildGraph() {
+    const graph = new WorkflowGraph();
+    graph.addNode('standup', {
+      agent: 'claude',
+      skills: [SKILLS.JIRA],
+      prompt: (state) => `List active sprints for project ${state.projectKey}.
+      For the current sprint, call jira_get_sprint_issues to get a status breakdown,
+      then produce a standup-style summary grouped by assignee.`,
+    });
+    return graph;
+  }
+}
+```
+
+### Transitioning issues
+
+The prompt fragment instructs the model to call `jira_transition_issue({ issueKey, toStatus })` directly when the user gives an explicit target; only when ambiguous should it call without `transitionId`/`toStatus` to list options. Status matching is normalized (whitespace, punctuation, case), then alias-matched, then dice-coefficient fuzzy-matched at a 0.45 threshold with a 0.12 gap.
+
+### Sprint membership
+
+To move an issue to a sprint, use `jira_move_issue_to_sprint` — it picks the right sprint (id/name/target), writes `customfield_10020`, then verifies membership via JQL and a second issue read before reporting success.
+
+## Output example
+
+`jira_get_sprint_issues`:
+
+```json
+{
+  "count": 12,
+  "total": 12,
+  "statusCounts": { "To Do": 4, "In Progress": 5, "Done": 3 },
+  "issues": [
+    {
+      "key": "SCRUM-123",
+      "project": "SCRUM",
+      "summary": "Refresh token on 401",
+      "status": "In Progress",
+      "assignee": "Alice",
+      "priority": "High",
+      "type": "Story"
+    }
+  ]
+}
+```
+
+## Implementation notes
+
+`resolve()` spawns `@zibby/mcp-jira` (`node @zibby/mcp-jira/index.js`) with the OAuth bearer token and cloud id in env. If the bin can't be resolved, `resolve()` returns `null` and the strategy falls back to in-process tool dispatch via `handleToolCall` (used by the `assistant` agent strategy).
+
+`jiraFetch` clears the integration-token cache and retries once on auth-looking errors — the token endpoint can return a malformed payload mid-rotation. ADF (Atlassian Document Format) bodies are flattened to markdown in `jira_get_comments` so the model sees readable text instead of nested JSON.

package/docs/skills/lark.md

@@ -0,0 +1,85 @@
+---
+sidebar_position: 3
+title: Lark
+---
+
+# Lark skill
+
+Send messages, reply in threads, list chats, and read chat history on Lark / Feishu.
+
+- **ID:** `lark`
+- **MCP server:** `lark` (tools exposed as `mcp__lark__*`)
+
+## Tools provided
+
+| Tool | What it does |
+|---|---|
+| `lark_send_message` | Send a text message. `receive_id` accepts chat_id (`oc_*`), open_id (`ou_*`), union_id (`on_*`), or email — the receive id type is inferred from the prefix |
+| `lark_reply` | Reply to a specific `message_id` (creates a thread) |
+| `lark_list_chats` | List chats the bot is a member of |
+| `lark_get_chat_history` | Fetch recent messages in a `chat_id` (newest first), default `page_size: 20` |
+
+## Setup
+
+Lark bots authenticate with App ID + App Secret. The bot needs `im:message` and `im:chat:readonly` (or wider) permissions, and must be added to any chat it should read or post into.
+
+1. Create a custom app at [open.feishu.cn](https://open.feishu.cn/) (or Lark's open platform).
+2. Enable **Bot** capability and grant the IM permissions above.
+3. In the Zibby dashboard, **Settings → Integrations → Connect Lark**, paste your `App ID` and `App Secret`.
+4. The backend exchanges them for a `tenant_access_token` on demand and caches it (TTL ~100 min, just under Lark's 2h).
+
+For self-hosted Lark deployments, set `host` on the integration config; the default is the standard Feishu host.
+
+## Use in a workflow
+
+```js
+import { WorkflowAgent, WorkflowGraph } from '@zibby/core';
+import { SKILLS } from '@zibby/skills';
+
+export class IncidentNotifier extends WorkflowAgent {
+  buildGraph() {
+    const graph = new WorkflowGraph();
+    graph.addNode('notify', {
+      agent: 'claude',
+      skills: [SKILLS.LARK],
+      prompt: (state) => `Post a summary of incident ${state.incidentId} to the on-call
+      chat (chat_id: oc_xxxxx). If a previous thread exists in state.threadMessageId,
+      use lark_reply instead of lark_send_message.`,
+    });
+    return graph;
+  }
+}
+```
+
+## Output example
+
+`lark_send_message`:
+
+```json
+{ "ok": true, "message_id": "om_d2e6e3a1f24c9d3..." }
+```
+
+`lark_get_chat_history`:
+
+```json
+{
+  "messages": [
+    {
+      "message_id": "om_abc...",
+      "sender_id": "ou_xyz...",
+      "sender_type": "user",
+      "msg_type": "text",
+      "content": "{\"text\":\"deploy is green\"}",
+      "create_time": "1715839203000"
+    }
+  ]
+}
+```
+
+## Implementation notes
+
+Spawns `packages/skills/bin/mcp-lark.mjs`. Like Sentry, auth is fetched through the backend's `resolveIntegrationToken('lark')` endpoint and the tenant access token is cached in-process.
+
+`receive_id_type` is required by Lark and is inferred from the id prefix (`oc_` → chat_id, `ou_` → open_id, `on_` → union_id, `cli_` → app_id, anything with `@` → email). Callers pass whichever id they have.
+
+The MCP server uses `alwaysLoad: true` so tools land in the system prompt — same fix as Sentry. The `assistant` agent strategy can call the in-process `handleToolCall` for OpenAI Assistant API runs.

package/docs/skills/memory.md

@@ -0,0 +1,92 @@
+---
+sidebar_position: 7
+title: Memory (test)
+---
+
+# Memory skill
+
+Query the test memory database — prior test runs, known selectors with stability metrics, page models, navigation transitions — and save insights for future runs. Dolt-backed (git-style versioned SQL).
+
+- **ID:** `memory`
+- **MCP server:** `memory` (tools exposed as `mcp__memory__*`)
+- **Underlying server:** `@zibby/ui-memory/mcp-server`
+
+For persistent **chat** memory (not test history) see [Chat memory](./chat-memory.md).
+
+## Tools provided
+
+| Tool | What it does |
+|---|---|
+| `memory_get_test_history` | Recent test runs with pass/fail + timing. Filter by `specPath` substring |
+| `memory_get_selectors` | Known selectors for a page with stability metrics. Filter by `pageUrl` substring |
+| `memory_get_page_model` | Page structure — elements, roles, selectors. Filter by `url` substring |
+| `memory_get_navigation` | Known page-to-page transitions. Filter by `fromUrl` substring |
+| `memory_save_insight` | Save an observation. Categories: `selector_tip`, `timing`, `navigation`, `workaround`, `flaky`, `general` |
+
+## Setup
+
+Requires [Dolt](https://docs.dolthub.com/introduction/installation) and an initialized memory database in your workspace.
+
+```bash
+# macOS
+brew install dolt
+# then, in your workflow workspace:
+zibby init --mem
+```
+
+`zibby init --mem` creates `.zibby/memory/` (a Dolt repo). The memory tools only activate after at least one completed test run — until then the skill returns `null` from `resolve()` and is skipped.
+
+Override the bin location for development with `MCP_MEMORY_PATH`.
+
+See [Tests → Memory](../tests/memory.md) for the full memory lifecycle.
+
+## Use in a workflow
+
+```js
+import { WorkflowAgent, WorkflowGraph } from '@zibby/core';
+import { SKILLS } from '@zibby/skills';
+
+export class FlakyTestInvestigator extends WorkflowAgent {
+  buildGraph() {
+    const graph = new WorkflowGraph();
+    graph.addNode('investigate', {
+      agent: 'claude',
+      skills: [SKILLS.MEMORY, SKILLS.BROWSER],
+      prompt: (state) => `Before running the test:
+      1. Call memory_get_test_history with specPath="${state.specPath}" — review prior failures.
+      2. Call memory_get_selectors with pageUrl matching the target page.
+      Then run the test using the browser tools. When done, save a memory_save_insight
+      capturing any selectors that worked when an older one failed.`,
+    });
+    return graph;
+  }
+}
+```
+
+The skill's prompt fragment auto-instructs the agent to consult prior runs and call `memory_save_insight` mid-run when a fallback selector works, and at minimum once at end-of-run.
+
+## Output example
+
+`memory_get_selectors`:
+
+```json
+{
+  "selectors": [
+    {
+      "pageUrl": "/dashboard",
+      "role": "button",
+      "stableId": "e7a1",
+      "selector": "[data-testid='new-project']",
+      "successCount": 42,
+      "failureCount": 1,
+      "lastSeen": "2026-05-15T14:00:00Z"
+    }
+  ]
+}
+```
+
+## Implementation notes
+
+`resolve({ workspace })` resolves `@zibby/ui-memory/mcp-server` and spawns it with `--db-path .zibby/memory`. Before spawning it sanity-checks Dolt is on the PATH and the database has at least one `test_runs` row; if not, returns `null` (skill skipped silently) or throws a clear "install Dolt" error.
+
+The skill also exports `middleware()` that loads `createMemoryMiddleware()` from `@zibby/ui-memory` when the package is present — this runs before/after each node to inject test history into the prompt and persist new insights.

package/docs/skills/sentry.md

@@ -0,0 +1,80 @@
+---
+sidebar_position: 2
+title: Sentry
+---
+
+# Sentry skill
+
+Read-only access to a connected Sentry organization — list projects, list issues, fetch issue details.
+
+- **ID:** `sentry`
+- **MCP server:** `sentry` (tools exposed as `mcp__sentry__*`)
+
+## Tools provided
+
+| Tool | What it does |
+|---|---|
+| `sentry_list_projects` | List projects in the connected organization (slug, name, platform) |
+| `sentry_list_issues` | List issues. Supports `project`, `query` (Sentry search syntax, default `is:unresolved`), `sort` (`date`/`new`/`priority`/`freq`/`user`), `limit` |
+| `sentry_get_issue` | Detailed info for one issue by `issueId` — title, culprit, counts, first/last seen, level, status |
+
+## Setup
+
+Sentry uses OAuth 2.0 with PKCE (public client — no client secret).
+
+1. In the Zibby dashboard, go to **Settings → Integrations**.
+2. Click **Connect Sentry**.
+3. Approve the organization in the Sentry consent screen.
+4. You're redirected back; the access token + organization slug are stored encrypted on the project.
+
+The backend (`/integrations/sentry/connect` and `/integrations/sentry/callback`) handles the PKCE exchange. Tokens auto-refresh on use; if refresh fails, click **Reconnect** in the same settings panel.
+
+## Use in a workflow
+
+```js
+import { WorkflowAgent, WorkflowGraph } from '@zibby/core';
+import { SKILLS } from '@zibby/skills';
+
+export class SentryTriage extends WorkflowAgent {
+  buildGraph() {
+    const graph = new WorkflowGraph();
+    graph.addNode('triage', {
+      agent: 'claude',
+      skills: [SKILLS.SENTRY],
+      prompt: () => `Use sentry_list_issues with query "is:unresolved level:error" to find the
+      top 10 unresolved errors. Then call sentry_get_issue for the highest-frequency one
+      and summarize what's failing.`,
+    });
+    return graph;
+  }
+}
+```
+
+## Output example
+
+`sentry_list_issues`:
+
+```json
+{
+  "issues": [
+    {
+      "id": "5712345678",
+      "title": "TypeError: Cannot read properties of undefined (reading 'id')",
+      "culprit": "src/handlers/checkout.ts in handleSubmit",
+      "count": 1247,
+      "firstSeen": "2026-05-01T14:22:10Z",
+      "lastSeen": "2026-05-16T09:11:03Z",
+      "level": "error",
+      "status": "unresolved"
+    }
+  ]
+}
+```
+
+## Implementation notes
+
+Spawns `packages/skills/bin/mcp-sentry.mjs` via `node`. Auth is delegated: the bin calls the Zibby backend's `resolveIntegrationToken('sentry')` endpoint using `PROJECT_API_TOKEN` + `PROGRESS_API_URL` (passed through from the Fargate environment).
+
+`alwaysLoad: true` is set on the MCP server config so Sentry tools land in the initial system prompt instead of behind the Claude SDK's lazy `ToolSearch` (which misses MCP-served tools by keyword).
+
+The skill also implements `handleToolCall` for the `assistant` agent strategy (OpenAI Assistant API), which doesn't speak MCP — same Sentry API, dispatched in-process.

package/docs/skills/slack.md

@@ -0,0 +1,84 @@
+---
+sidebar_position: 5
+title: Slack
+---
+
+# Slack skill
+
+Read/write a Slack workspace — list channels, post messages, reply in threads, react, read history, list users.
+
+- **ID:** `slack`
+- **MCP server:** `slack` (tools exposed as `mcp__slack__*`)
+- **Underlying server:** `npx @modelcontextprotocol/server-slack@latest`
+
+## Tools provided
+
+| Tool | What it does |
+|---|---|
+| `slack_list_channels` | List public channels (id, name, topic) |
+| `slack_post_message` | Post a top-level message. Requires `channel` and `text` |
+| `slack_reply_to_thread` | Post a reply with `thread_ts` |
+| `slack_add_reaction` | Add an emoji reaction to a message |
+| `slack_get_channel_history` | Recent messages in a channel (`limit` default 20) |
+| `slack_get_thread_replies` | All replies in a thread |
+| `slack_get_users` | Workspace members (excludes bots and deleted) |
+| `slack_get_user_profile` | Detailed profile for a `user_id` |
+
+## Setup
+
+Slack uses a bot token + workspace team id.
+
+1. Create (or reuse) a Slack app at [api.slack.com/apps](https://api.slack.com/apps).
+2. Add Bot Token Scopes: `chat:write`, `channels:read`, `channels:history`, `groups:read`, `users:read`, `reactions:write` (minimum).
+3. Install the app to your workspace; copy the **Bot User OAuth Token** (`xoxb-…`) and **Team ID**.
+4. Set them on the workflow's env (locally) or via **Cloud → Env vars**:
+
+```bash
+SLACK_BOT_TOKEN=xoxb-...
+SLACK_TEAM_ID=T01234567
+```
+
+The skill declares `envKeys: ['SLACK_BOT_TOKEN', 'SLACK_TEAM_ID']` and the official `@modelcontextprotocol/server-slack` consumes them.
+
+## Use in a workflow
+
+```js
+import { WorkflowAgent, WorkflowGraph } from '@zibby/core';
+import { SKILLS } from '@zibby/skills';
+
+export class DeployAnnouncer extends WorkflowAgent {
+  buildGraph() {
+    const graph = new WorkflowGraph();
+    graph.addNode('announce', {
+      agent: 'claude',
+      skills: [SKILLS.SLACK],
+      prompt: (state) => `Post to #deploys: "v${state.version} deployed to ${state.env}".
+      If state.threadTs is set, use slack_reply_to_thread instead of slack_post_message.`,
+    });
+    return graph;
+  }
+}
+```
+
+## Output example
+
+`slack_post_message`:
+
+```json
+{ "ok": true, "ts": "1715839203.000400", "channel": "C0123ABC" }
+```
+
+`slack_list_channels`:
+
+```json
+{
+  "channels": [
+    { "id": "C0123ABC", "name": "deploys", "topic": "Release announcements" },
+    { "id": "C0456DEF", "name": "incidents", "topic": "P0/P1 coordination" }
+  ]
+}
+```
+
+## Implementation notes
+
+`resolve()` spawns the official `@modelcontextprotocol/server-slack` via `npx` and passes through `SLACK_BOT_TOKEN` + `SLACK_TEAM_ID`. The in-process `handleToolCall` (used by the `assistant` strategy) talks directly to `https://slack.com/api/<method>` with the same bot token resolved via the backend's integration token service.