@zibby/skills 0.2.22 → 0.2.24

package/docs/skills/browser.md

@@ -1,97 +0,0 @@
----
-sidebar_position: 1
-title: Browser
----
-
-# Browser skill
-
-Playwright-driven browser automation. Click, type, navigate, snapshot, record video. Used by `zibby test` and by any agent node that needs to drive a web UI.
-
-- **ID:** `browser`
-- **MCP server:** `playwright` (tools exposed as `mcp__playwright__*`)
-
-## Tools provided
-
-The Playwright MCP server exposes the full Playwright tool surface. Common tools:
-
-| Tool | What it does |
-|---|---|
-| `browser_navigate` | Open a URL in the active tab |
-| `browser_click` | Click an element by stable id or selector |
-| `browser_type` | Type text into an input |
-| `browser_press_key` | Press a key (Enter, Tab, etc.) |
-| `browser_snapshot` | Accessibility snapshot of the current page (returns stable ids) |
-| `browser_take_screenshot` | PNG screenshot saved to the session output dir |
-| `browser_wait_for` | Wait for text, time, or selector |
-| `browser_evaluate` | Run JS in the page context |
-| `browser_fill_form` | Fill multiple fields in one call |
-| `browser_select_option` | Pick a `<select>` option |
-| `browser_hover` | Hover over an element |
-| `browser_drag` | Drag from one element to another |
-| `browser_tabs` | List, switch, or close tabs |
-| `browser_close` | Close the browser |
-
-Refer to `@zibby/mcp-browser` for the full list. All tools are gated by the `mcp__playwright__*` allowlist.
-
-## Setup
-
-No setup needed beyond a working `@zibby/cli` install — the cloud runner image and the global CLI install both pull `@zibby/mcp-browser` automatically.
-
-For local dev outside the CLI, install it explicitly:
-
-```bash
-npm install @zibby/mcp-browser
-```
-
-Override the bin path with `MCP_BROWSER_PATH` if you need to point at a local checkout.
-
-## Use in an agent
-
-```js
-import { WorkflowAgent, WorkflowGraph } from '@zibby/core';
-import { SKILLS } from '@zibby/skills';
-
-export class LoginCheck extends WorkflowAgent {
-  buildGraph() {
-    const graph = new WorkflowGraph();
-    graph.addNode('login', {
-      agent: 'claude',
-      skills: [SKILLS.BROWSER],
-      prompt: (state) => `Go to ${state.appUrl}, sign in as test@example.com / hunter2,
-      then snapshot the dashboard and report whether the welcome banner is visible.`,
-    });
-    return graph;
-  }
-}
-```
-
-### Config knobs
-
-Passed via the node's skill config or env:
-
-| Knob | Where | Effect |
-|---|---|---|
-| `headless: true` | per-skill config or `ZIBBY_HEADLESS=1` | Launch headless instead of headed |
-| `sessionPath` | passed by the runner | Output dir for videos + screenshots |
-| Viewport / video | fixed | 1280x720 |
-
-## Output example
-
-`browser_snapshot` returns an accessibility tree with stable ids the agent can pass back to `browser_click`:
-
-```json
-{
-  "url": "https://app.example.com/dashboard",
-  "title": "Dashboard",
-  "snapshot": [
-    { "id": "e7a1", "role": "button", "name": "New project" },
-    { "id": "e7b2", "role": "link", "name": "Settings" }
-  ]
-}
-```
-
-## Implementation notes
-
-Resolves to `@zibby/mcp-browser/dist/bin/mcp-browser-zibby.js` via `require.resolve`. There is no fallback to `@playwright/mcp` — the upstream Microsoft binary lacks stable IDs and event recording, and silently looks for Chrome instead of Chromium, which broke cloud runs. If the bin can't be resolved, `skill.resolve()` throws with installation instructions.
-
-The MCP server is spawned with `--isolated --save-video=1280x720 --viewport-size=1280x720 --output-dir=<sessionPath>`. Videos and screenshots land under the run's session directory and are uploaded with the rest of the artifacts.

package/docs/skills/chat-memory.md

@@ -1,122 +0,0 @@
----
-sidebar_position: 8
-title: Chat memory
----
-
-# Chat memory skill
-
-Persistent agent memory across sessions — facts, decisions, preferences, task history. **mem0-backed by default** (embedding-based semantic recall, persists across cloud tasks); falls back to the self-contained Dolt backend automatically when the embedding proxy isn't available, or set `dolt` explicitly.
-
-- **ID:** `chat-memory`
-- **Runs in-process** — no MCP spawn
-
-For test-run history (selectors, page models, prior runs) see [Memory](./memory.md).
-
-## Tools provided
-
-| Tool | What it does |
-|---|---|
-| `memory_store` | Save a fact/decision/preference. Categories: `fact`, `decision`, `context`, `insight`, `preference`, `credential`, `url`, `error`, `workaround`. Tiers: `short` (24h), `mid` (default), `long` (permanent). Optional `memoryKey` for upserts. Optional `infer` (mem0 only — see [the `infer` toggle](#the-infer-toggle)) |
-| `memory_recall` | Search by `query`, `category`, `ticketKey`, or `tier`. Ranked by relevance × recency |
-| `memory_brief` | Compact briefing — recent sessions + top long/mid-tier memories. Call at conversation start |
-| `memory_end_session` | Save a session summary + key facts (semicolon-separated) for future recall |
-| `task_log` | Record a completed task (`test_run`/`generate`/`analysis`/`research`/`other`) with status |
-| `task_history` | Query past tasks by `ticketKey`, `type`, `status` |
-
-## Setup
-
-**mem0 (default).** `zibby init` configures mem0 out of the box and writes the right deps (`mem0ai@npm:@zibby/mem0ai@^3.0.5` + `better-sqlite3`) into your project. In Zibby cloud runs the embedding/LLM calls are proxied and billed through the agent run — no OpenAI key of your own needed. For local runs, point it at any OpenAI-compatible endpoint:
-
-```bash
-ZIBBY_MEM0_OPENAI_BASE_URL=https://api.openai.com/v1
-ZIBBY_MEM0_API_KEY=sk-...
-ZIBBY_MEM0_LLM_MODEL=gpt-4.1-mini
-ZIBBY_MEM0_EMBEDDER_MODEL=text-embedding-3-small
-ZIBBY_MEM0_EMBEDDING_DIMS=1536
-```
-
-mem0 mode uses embedding search for `memory_store` / `memory_recall`; `memory_end_session`, `task_log`, and `task_history` still write to Dolt for cross-session continuity. mem0's SQLite vector store lives under `.zibby/memory/mem0/` and is carried across ephemeral cloud tasks by the tenant-scoped memory tarball sync.
-
-**Graceful degradation.** If the embedding proxy is unreachable (or a local run has no `ZIBBY_MEM0_API_KEY`), memory ops automatically fall back to the Dolt backend per-op rather than failing the run — you get structured memory instead of an error.
-
-**Dolt (self-contained, no embedding dependency).** Set `ZIBBY_MEMORY_BACKEND=dolt` (or `memory.backend: 'dolt'`, or `zibby init --memory-backend dolt`) to opt out of mem0 entirely. Install Dolt; the skill auto-creates `.zibby/memory/` on first use:
-
-```bash
-brew install dolt
-```
-
-### The `infer` toggle
-
-mem0 can either store memories raw (embed-only, free) or run an LLM fact-extraction pass that distills and dedupes facts before storing (~7.7k tokens per call, costs money). This is the `infer` flag, and it **defaults to `false`** (embed-only).
-
-Resolution precedence (first match wins):
-
-1. **Per-call tool arg** — pass `infer: true` to `memory_store`
-2. **Env toggle** — `ZIBBY_MEM0_INFER=true`
-3. **Project config** — `memory.infer: true` in `.zibby.config.mjs`
-4. Default — `false` (embed-only, no LLM call)
-
-```js
-// .zibby.config.mjs
-export default {
-  memory: {
-    backend: 'mem0',
-    infer: false,        // default — store raw + embed, never call the LLM
-  },
-};
-```
-
-Turn `infer` on when you want mem0 to consolidate noisy inputs into clean facts; leave it off (the default) for free, deterministic embed-and-store.
-
-### Cloud persistence
-
-On Zibby Cloud, mem0 state **persists across Fargate tasks**. mem0's SQLite vector + history stores are rooted under the workspace's tenant-scoped `.zibby/memory/` tree, which is tarball-synced between executions — so a memory written in one run is recallable in the next, even though each run is a fresh, ephemeral container. mem0 user IDs are workspace-scoped (`workspace:<name>`, overridable via `ZIBBY_MEMORY_USER_ID`), keeping each project's memory isolated.
-
-## Use in an agent
-
-```js
-import { WorkflowAgent, WorkflowGraph } from '@zibby/core';
-import { SKILLS } from '@zibby/skills';
-
-export class ChatAgent extends WorkflowAgent {
-  buildGraph() {
-    const graph = new WorkflowGraph();
-    graph.addNode('respond', {
-      agent: 'claude',
-      skills: [SKILLS.CHAT_MEMORY, SKILLS.JIRA],
-      prompt: (state) => `At the start of this turn, call memory_brief to load
-      context. If you learn anything durable about the user's setup (e.g. their
-      default Jira project), call memory_store with category="preference", tier="long".
-      When the task is done, call memory_end_session with a 1-sentence summary.`,
-    });
-    return graph;
-  }
-}
-```
-
-The `memory_store` tool dedupes by normalized content — re-storing the same fact promotes its tier/relevance instead of inserting a duplicate. Long-tier rows decay 2%/session, mid-tier 10%, short-tier 30%, and short-tier rows older than 24h are deleted on next `memory_brief`.
-
-## Output example
-
-`memory_brief`:
-
-```json
-{
-  "recentSessions": [
-    { "session_id": "session_a1b2", "summary": "Reviewed SCRUM-123, added tests", "tickets": "SCRUM-123" }
-  ],
-  "topMemories": [
-    { "category": "preference", "tier": "long", "content": "Default Jira board: SCRUM" },
-    { "category": "fact", "tier": "mid", "content": "Auth login page is at /auth/login" }
-  ],
-  "taskStats": [
-    { "type": "test_run", "status": "passed", "cnt": 14 }
-  ]
-}
-```
-
-## Implementation notes
-
-`resolve()` returns `null` — this skill never spawns an MCP server. Tool calls are dispatched in-process via `handleToolCall(name, args, context)`, where `context.options.workspace` controls the Dolt directory.
-
-The skill also implements `buildPromptContext(context, args)`, which the strategy calls at node start. It runs `memory_brief` internally and returns a markdown-formatted "Memory Context" block that gets prepended to the system prompt — so the model sees recent sessions and durable facts on every turn without needing an explicit tool call. The same call returns `debugPreview` for transcript logging.

package/docs/skills/core-tools.md

@@ -1,80 +0,0 @@
----
-sidebar_position: 9
-title: Core tools
----
-
-# Core tools skill
-
-Baseline local capabilities — file read/write, directory listing, shell execution, URL opening, async wait. The equivalent of what Cursor or Claude Code gets natively.
-
-- **ID:** `core-tools`
-- **Runs in-process** — no MCP spawn
-
-Most Claude/Cursor/Codex nodes get these tools by default from their agent strategy — you usually don't need to opt in explicitly. Add it to the `skills` array only if you're running a node where the strategy hasn't already wired them up (e.g. some custom strategies).
-
-## Tools provided
-
-| Tool | What it does |
-|---|---|
-| `read_file` | Read a UTF-8 file. Max 256 KB; larger files return an error |
-| `write_file` | Write content to a file, creating parent directories as needed |
-| `list_directory` | List entries in a directory; directories suffixed with `/` |
-| `run_command` | `execSync` a shell command. 30s timeout, 64 KB stdout cap, captures stderr |
-| `open_url` | Open a URL in the default browser (uses `open`/`start`/`xdg-open`). Rejects non-http(s) URLs |
-| `wait` | Sleep for N seconds (1–300). Respects `context.options.signal` for cancellation |
-
-## Setup
-
-None. The skill has no env keys, no auth, no external dependencies.
-
-## Use in an agent
-
-```js
-import { WorkflowAgent, WorkflowGraph } from '@zibby/core';
-import { SKILLS } from '@zibby/skills';
-
-export class RepoInspector extends WorkflowAgent {
-  buildGraph() {
-    const graph = new WorkflowGraph();
-    graph.addNode('inspect', {
-      agent: 'claude',
-      skills: [SKILLS.CORE_TOOLS],
-      prompt: (state) => `cd into ${state.repoPath}. List the top-level directory,
-      then read package.json and report the dependency graph at one level deep.`,
-    });
-    return graph;
-  }
-}
-```
-
-All paths are resolved against `context.options.workspace` (the node's working directory) — relative paths are safe to pass.
-
-## Output example
-
-`list_directory` returns a newline-separated string:
-
-```
-package.json
-node_modules/
-src/
-README.md
-```
-
-`run_command`:
-
-```
-on main
-nothing to commit, working tree clean
-```
-
-`open_url`:
-
-```json
-{ "ok": true, "opened": "https://zibby.dev" }
-```
-
-## Implementation notes
-
-`resolve()` returns `null` — there is no MCP server. The strategy dispatches tool calls in-process via `handleToolCall(name, args, context)`. `wait` is the only async handler and polls the abort signal every 500 ms so the run can cancel mid-sleep.
-
-`run_command` shells out with `execSync` and captures stdout. Long-running commands hit the 30s timeout — for builds or test runs use the dedicated `runner` or `test-runner` skills instead.

package/docs/skills/function-skill.md

@@ -1,93 +0,0 @@
----
-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 an agent
-
-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

@@ -1,91 +0,0 @@
----
-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 agent'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 an agent
-
-```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

@@ -1,46 +0,0 @@
----
-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` |
-| GitLab | `gitlab` | Repos, MRs, issues, pipelines (self-hosted or SaaS) | `GITLAB_TOKEN` (+ base URL) |
-| [Slack](./slack.md) | `slack` | Channels, post/reply, reactions, history, users | Bot token + team ID |
-| [Jira](./jira.md) | `jira` | Issues, sprints, comments, transitions | Atlassian OAuth |
-| Linear | `linear` | `linear_list_issues`, `linear_get_issue`, `linear_add_comment`, `linear_update_state`, `linear_list_teams/states/labels` | `LINEAR_API_KEY` |
-| Plane | `plane` | Projects, work items, cycles, modules, epics, comments (official MCP) | `PLANE_API_KEY` (+ `PLANE_WORKSPACE_SLUG`, `PLANE_BASE_URL`) |
-| Notion | n/a | Not an attachable MCP skill — a [connectable integration](../integrations/notion.md). Agents publish a `report` object to Notion blocks (`reportToNotionBlocks`), e.g. the `notify-notion` template | OAuth (dashboard) / `NOTION_API_KEY` (SDK) |
-| [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

@@ -1,99 +0,0 @@
----
-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 an agent
-
-```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.