@zibby/skills 0.1.24 → 0.1.26

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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zibby/skills",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "description": "Built-in skill definitions for Zibby test automation framework",
   "type": "module",
   "main": "dist/index.js",
@@ -14,7 +14,11 @@
     "./slack": "./dist/slack.js",
     "./lark": "./dist/lark.js",
     "./memory": "./dist/memory.js",
-    "./function": "./dist/function-skill.js"
+    "./function": "./dist/function-skill.js",
+    "./integrations": "./dist/integrations.js",
+    "./report": "./dist/report.js",
+    "./llm-billing": "./dist/llm-billing.js",
+    "./sentry": "./dist/sentry.js"
   },
   "scripts": {
     "build": "node ../scripts/build.mjs",
@@ -34,10 +38,10 @@
   "homepage": "https://zibby.dev",
   "repository": {
     "type": "git",
-    "url": "https://github.com/ZibbyHQ/zibby-agent"
+    "url": "https://github.com/ZibbyHQ/skills"
   },
   "bugs": {
-    "url": "https://github.com/ZibbyHQ/zibby-agent/issues"
+    "url": "https://github.com/ZibbyHQ/skills/issues"
   },
   "files": [
     "dist/",
@@ -62,6 +66,9 @@
     "@zibby/mcp-memory": "*"
   },
   "devDependencies": {
-    "esbuild": "^0.28.0"
+    "@eslint/js": "^10.0.1",
+    "esbuild": "^0.28.0",
+    "eslint": "^10.0.2",
+    "globals": "^17.4.0"
   }
 }