@zibby/skills 0.1.24 → 0.1.26

package/docs/packages/mcp-cli.md

@@ -0,0 +1,176 @@
+---
+sidebar_position: 7
+title: "@zibby/mcp-cli"
+---
+
+# @zibby/mcp-cli
+
+A Model Context Protocol (MCP) server that exposes the Zibby CLI surface — deploy, run, debug, trigger — to any MCP-aware AI agent. Install once, drive Zibby from Claude Code / Cursor / OpenAI Codex / Gemini CLI / Continue / Cline / Aider / Goose without leaving chat.
+
+```bash
+# Not installed manually — the agent's `npx` invocation handles it.
+# See "Install" below for per-agent config.
+```
+
+## What it exposes
+
+13 MCP tools, all wrapping the underlying `@zibby/cli`:
+
+| Tool | What it does |
+|---|---|
+| `zibby_login` | Opens the user's browser for device-code OAuth. Saves session to `~/.zibby/config.json`. |
+| `zibby_logout` | Clears the saved session. |
+| `zibby_status` | Who is logged in, how many projects are cached, whether the session is still valid. |
+| `zibby_list_projects` | List the Zibby projects the user has access to. |
+| `zibby_list_templates` | List official workflow templates (browser-test-automation, code-analysis, generate-test-cases, …). |
+| `zibby_scaffold_workflow` | Scaffold `.zibby/workflows/<name>/` from an official template. |
+| `zibby_validate_workflow` | Static-check a local workflow (~30 ms, no API call). |
+| `zibby_list_workflows` | List workflows: local, remote, or both. |
+| `zibby_deploy_workflow` | Deploy a local workflow to a project. |
+| `zibby_trigger_workflow` | Trigger a deployed workflow by UUID. Returns `jobId`. |
+| `zibby_workflow_logs` | Fetch the latest N log lines from a run (one-shot — call again for newer lines). |
+| `zibby_run_workflow_local` | Run a workflow on the user's machine one-shot, for debugging. No cloud. |
+| `zibby_download_workflow` | Pull a deployed workflow back to local. Requires explicit `confirm: true` from the agent. |
+
+**Destructive operations are intentionally not exposed.** Workflow deletion, env-var mutation, schedule changes, and credential management stay in the `zibby` CLI directly. The agent has to involve the user out-of-band for those.
+
+## Install
+
+`@zibby/mcp-cli` ships as a stdio MCP server. The agent's host process spawns it via `npx -y` — no global install needed. The user just needs **Node.js ≥ 18** on their machine.
+
+### Claude Code
+
+`~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "zibby": {
+      "command": "npx",
+      "args": ["-y", "@zibby/mcp-cli"]
+    }
+  }
+}
+```
+
+### Cursor
+
+`~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "zibby": {
+      "command": "npx",
+      "args": ["-y", "@zibby/mcp-cli"]
+    }
+  }
+}
+```
+
+### OpenAI Codex CLI
+
+`~/.codex/config.toml`:
+
+```toml
+[mcp_servers.zibby]
+command = "npx"
+args = ["-y", "@zibby/mcp-cli"]
+```
+
+### Gemini CLI
+
+`~/.gemini/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "zibby": {
+      "command": "npx",
+      "args": ["-y", "@zibby/mcp-cli"]
+    }
+  }
+}
+```
+
+### Claude Desktop (macOS)
+
+`~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "zibby": {
+      "command": "npx",
+      "args": ["-y", "@zibby/mcp-cli"]
+    }
+  }
+}
+```
+
+### Windows
+
+If your agent on Windows can't find `npx`, wrap with `cmd /c`:
+
+```json
+{
+  "mcpServers": {
+    "zibby": {
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "@zibby/mcp-cli"]
+    }
+  }
+}
+```
+
+## A typical agent chat
+
+```
+User:  Deploy the browser-test template to my "playhouse" project.
+Agent: → zibby_list_projects
+       → zibby_scaffold_workflow (browser-test-automation → .zibby/workflows/playhouse-tests/)
+       → zibby_validate_workflow
+       → zibby_deploy_workflow
+       → "Deployed v1 of playhouse-tests. UUID 988…"
+
+User:  Run it against staging.zibby.dev.
+Agent: → zibby_trigger_workflow (input: { url: "https://staging.zibby.dev" })
+       → zibby_workflow_logs (lines: 200, jobId: "abc-123")
+       → "Run completed. Found 0 errors."
+```
+
+## Auth model
+
+Two-stage by design (mirrors how the `zibby` CLI works):
+
+1. **Session token** (`zibby_login`) — device-code OAuth via browser. Identifies the user.
+2. **Per-project API tokens** — fetched at login time and cached locally. The MCP server picks the right token automatically when you call a project-scoped tool like `zibby_deploy_workflow`.
+
+All credentials live in `~/.zibby/config.json` (mode `0600`). The same file `zibby login` writes — so if you've already done `zibby login` from a terminal, the MCP server picks up that session.
+
+The user's password never touches the MCP server: login is OAuth in the browser, and only the resulting session token comes back to the local file.
+
+## Security guarantees
+
+- **No shell interpolation** — every CLI invocation uses `execFile` with argv arrays.
+- **Minimum env passthrough** — only `HOME`, `USER`, `PATH`, and the project-scoped `ZIBBY_API_KEY` reach the child CLI process.
+- **API tokens never returned to the agent** — they live in `~/.zibby/config.json` only, read server-side per call.
+- **Destructive ops excluded** — see the table above.
+- **`zibby_download_workflow` requires `confirm: true`** — the schema rejects calls without it. Agents must explicitly opt in after confirming the destination path with the user.
+
+## Troubleshooting
+
+| Problem | Likely cause |
+|---|---|
+| `Not logged in` on every call | `~/.zibby/config.json` missing or corrupted. Call `zibby_login`. |
+| `No API token cached for project` | Project list out of date. Call `zibby_list_projects` to refresh. |
+| `npx -y` hangs on first install | First-time download. Subsequent invocations are cached by npm. |
+| Tool times out on long deploys | The wrapped CLI command exceeded 10 min. Re-run from a terminal to see live output. |
+
+## Versioning
+
+`@zibby/mcp-cli` pins a specific `@zibby/cli` version in its `dependencies`. Upgrading the MCP package upgrades the bundled CLI in lockstep. Users get the right CLI automatically — no need to coordinate two installs.
+
+## Source
+
+[github.com/ZibbyHQ/zibby-agent → packages/mcps/cli](https://github.com/ZibbyHQ/zibby-agent/tree/main/packages/mcps/cli)

package/docs/packages/skills.md

@@ -5,6 +5,8 @@ title: "@zibby/skills"
 
 # @zibby/skills
 
+> Looking for skill-specific docs and examples? See [Skills reference](../skills/index.md).
+
 Built-in skill definitions for Zibby's test automation framework.
 
 ```bash

package/docs/recipes/test.md

@@ -185,6 +185,6 @@ For workflows triggered remotely (rather than per-CI-run), use [`workflow trigge
 
 ## See also
 
-- [Recipes overview](./index)
+- [Recipes overview](./)
 - [Concepts: graph](../concepts/graph) — the primitives this recipe uses
 - [Cloud triggering](../cloud/triggering) — fire workflows from CI/CD

package/docs/skills/browser.md

@@ -0,0 +1,97 @@
+---
+sidebar_position: 1
+title: Browser
+---
+
+# Browser skill
+
+Playwright-driven browser automation. Click, type, navigate, snapshot, record video. Used by `zibby test` and by any workflow 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 a workflow
+
+```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

@@ -0,0 +1,93 @@
+---
+sidebar_position: 8
+title: Chat memory
+---
+
+# Chat memory skill
+
+Persistent agent memory across sessions — facts, decisions, preferences, task history. Dolt-backed by default; pluggable to mem0 for embedding-based recall.
+
+- **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 |
+| `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
+
+**Dolt (default).** Install Dolt; the skill auto-creates `.zibby/memory/` on first use.
+
+```bash
+brew install dolt
+```
+
+**mem0 (optional).** Set `ZIBBY_MEMORY_BACKEND=mem0` (or `memory.backend: 'mem0'` in `.zibby.config.mjs`) and `npm install mem0ai` in your workspace. Configure with:
+
+```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 skips Dolt session/task tables and relies on embedding search; `memory_end_session`, `task_log`, and `task_history` still write to Dolt for cross-session continuity.
+
+## Use in a workflow
+
+```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

@@ -0,0 +1,80 @@
+---
+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 a workflow
+
+```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

@@ -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.