@xiaotianxt/skills 0.1.0

package/skills/bro-browser/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: bro-browser
+description: Control and inspect a real local Chromium-family browser through the bro MCP server and WebExtension. Use when Codex needs logged-in browser access, current tab inspection, page text or link extraction, multi-URL background extraction, click/fill/read flows, or browser console and network diagnostics. Do not use for ordinary web lookup when generic web browsing is sufficient.
+---
+
+# Bro Browser
+
+## Overview
+
+Use bro when the user wants an agent to operate the user's real local browser, especially for logged-in pages or dynamic pages that generic HTTP fetch cannot read. Treat the browser as sensitive user state.
+
+bro is the local Rust MCP server in `/Users/yupeit/dev/bro`. It exposes:
+
+- HTTP server: `http://127.0.0.1:3500`
+- MCP endpoint: `http://127.0.0.1:3500/mcp`
+- WebSocket extension bridge: `ws://127.0.0.1:3500/ws`
+- settings token path: `~/.bro/settings.json`
+- unpacked extension path: `/Users/yupeit/dev/bro/extension/dist`
+
+Use `127.0.0.1`, not `localhost`, to avoid IPv6 mismatch with local services.
+
+## Fast Path First
+
+For a known URL or a user request that can be satisfied by opening one page and reading it, start with the highest-level one-shot extraction before doing discovery:
+
+```bash
+scripts/bro-call.mjs browser.extract '{"url":"https://example.com","active":false,"cleanup":true,"maxChars":8000}'
+```
+
+Use this as the default first move for unknown page content, logged-in pages, and ordinary "look at this page" tasks. It minimizes tool calls and keeps browser state contained by opening a task-owned background tab and cleaning it up.
+
+If the user says the target page is already open or asks about the current logged-in browser page, use current-tab extraction directly:
+
+```bash
+scripts/bro-call.mjs browser.current.extract '{"maxChars":8000}'
+```
+
+Skip these fast paths only when the task needs foreground interaction, form submission, browser/tab state discovery, or a target URL is not known.
+
+## First Checks
+
+Use read-only status checks when the fast path is not applicable, when an extraction fails for connection/auth reasons, or when you need to operate on existing tabs:
+
+```bash
+curl -sS http://127.0.0.1:3500/status
+scripts/bro-call.mjs browsers_context
+scripts/bro-call.mjs tabs_context '{"all":true}'
+```
+
+Also confirm the bro settings file exists:
+
+```bash
+ls -l ~/.bro/settings.json
+```
+
+If running from outside this skill directory, use the absolute helper path:
+
+```bash
+/Users/yupeit/.codex/skills/bro-browser/scripts/bro-call.mjs browsers_context
+```
+
+If the server is not running, start it from the bro repo:
+
+```bash
+cargo run --manifest-path /Users/yupeit/dev/bro/Cargo.toml -- serve
+```
+
+If no extension is connected, load `/Users/yupeit/dev/bro/extension/dist` as an unpacked extension in a Chromium-family browser, open the extension options, set server URL to `ws://127.0.0.1:3500/ws`, and paste the token from `~/.bro/settings.json`. Do not print the token.
+
+## Tool Choice
+
+Choose the highest-level bro tool that matches the user outcome:
+
+- Extract one known URL or unknown page content: call `browser.extract` first, preferably with `active:false`, `cleanup:true`, and a task-appropriate `maxChars`.
+- Extract the current/open page: call `browser.current.extract` first. Do not spend separate calls on `browsers_context` and `tabs_context` unless the current page is ambiguous or extraction fails.
+- Extract many independent URLs: call `browser.batch.extract`.
+- Read text from many URLs when links and diagnostics are not needed: call `browser.batch.run`.
+- Interact with one page over multiple steps: use `browser.flow.start`, `browser.flow.act`, `browser.flow.observe`, then `browser.flow.finish`.
+- Inspect or operate on an existing tab: call `browsers_context`, then `tabs_context`, pin `browserId` and `tabId`, and use raw tab tools.
+- Debug a page or local app: create or pin a tab, then use `read_console_messages`, `read_network_requests`, and `get_response_body`.
+
+Use compact extraction defaults. Leave `includeLinks:false` unless URLs are part of the answer or the next crawl step. Leave `includeA11y:false` unless DOM extraction is partial/empty or you need controls and labels. Read `references/workflows.md` for concrete workflow recipes and `references/tool-map.md` for tool arguments and fallback rules.
+
+## Safety Rules
+
+- Treat tab URLs, page text, screenshots, cookies, account state, extension state, signed URLs, and tokens as sensitive.
+- Never print the bro bearer token. It is acceptable to print the settings file path.
+- Prefer background tabs with `active:false` unless foreground focus is part of the request.
+- After discovery, never operate on "whatever tab is active". Record `browserId` and `tabId`, then pass them explicitly.
+- Track every task-owned tab. Close it with `tabs_close`, `agent_done`, or `browser.flow.finish` unless the user asked to keep it open.
+- Ask before submitting forms, sending messages, uploading files, making purchases, changing account settings, or reading pages likely to contain highly sensitive data.
+- Keep bro generic. Do not add site-specific research policy to the bro bridge; put site workflows in downstream skills or task-local instructions.
+
+## Common Calls
+
+```bash
+scripts/bro-call.mjs browser.extract '{"url":"https://example.com","active":false,"cleanup":true,"maxChars":8000}'
+scripts/bro-call.mjs browser.current.extract '{"maxChars":8000}'
+scripts/bro-call.mjs browser.batch.extract '{"urls":["https://example.com/a","https://example.com/b"],"concurrency":4,"maxChars":6000}'
+scripts/bro-call.mjs browser.flow.start '{"url":"https://example.com","active":false}'
+scripts/bro-call.mjs browser.flow.observe '{"sessionId":"SESSION_ID","mode":"text"}'
+scripts/bro-call.mjs browser.flow.finish '{"sessionId":"SESSION_ID","cleanup":true}'
+```
+
+For structured output, add `--json`.
+
+## Failure Handling
+
+- Connection refused: start `bro serve` or verify the port.
+- Missing `~/.bro/settings.json`: run `bro doctor` or `bro serve` from `/Users/yupeit/dev/bro` to initialize bro local state.
+- Unauthorized MCP call: check that `~/.bro/settings.json` exists, the helper is reading that file, and the extension options use the same token.
+- No browsers connected: connect the bro extension and verify `/status`.
+- Unknown `browserId`: refresh `browsers_context`; do not silently fall back to another browser.
+- `browser.extract` or `browser.current.extract` returns an error or a clearly partial/empty result: inspect diagnostics, then fall back in this order as relevant:
+  1. Retry the same facade tool with `includeA11y:true`, `includeLinks:true` only if links matter, a larger `maxChars`, or a higher `minChars`.
+  2. Use `browsers_context` and `tabs_context` only if you need to confirm connection state, find an existing tab, or recover a task-owned tab left open by a failed extraction.
+  3. Use raw tab tools such as `get_page_text` or `extract_page` after pinning `browserId` and `tabId`.
+  4. Use a browser flow when the page requires clicks, form input, navigation, or stateful observation.

package/skills/bro-browser/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Bro Browser"
+  short_description: "Control local browser workflows with bro"
+  default_prompt: "Use $bro-browser to inspect a page, extract URLs, or run a browser flow through local bro."

package/skills/bro-browser/references/tool-map.md

@@ -0,0 +1,102 @@
+# Bro Tool Map
+
+Prefer facade tools before raw extension tools. They encode bro's cleanup, bounded concurrency, and readiness policy.
+
+## Facade Tools
+
+`browser.extract`
+
+- Use for one URL.
+- Required: `url`.
+- Useful options: `id`, `minChars`, `maxChars`, `maxLinks`, `includeA11y`, `includeLinks`, `cleanup`, `active`, `browserId`.
+- Defaults: `maxChars:8000`, `includeLinks:false`, `includeA11y:false`, `cleanup:true`, `active:false`.
+- Output includes status, text, optional links, and diagnostics.
+
+`browser.current.extract`
+
+- Use for the current/default active tab when the user says the page is already open.
+- Useful options: `id`, `minChars`, `maxChars`, `maxLinks`, `includeA11y`, `includeLinks`, `browserId`.
+- Defaults: `maxChars:8000`, `includeLinks:false`, `includeA11y:false`.
+- Prefer this over `browsers_context` + `tabs_context` + raw text reads when the current page is unambiguous.
+
+`browser.batch.extract`
+
+- Use for multiple independent URLs when links or diagnostics matter.
+- Provide either `urls` or `inputs`; do not provide both.
+- Defaults: `concurrency:6`, `maxChars:8000`, `includeLinks:false`, `cleanup:true`, `active:false`.
+- Use `inputs` with `{id,url}` when stable IDs matter.
+
+`browser.batch.run`
+
+- Use for multiple independent URLs when plain text is enough.
+- Provide either `urls` or `inputs`; do not provide both.
+- Defaults: `concurrency:6`, `timeoutMs:12000`, `cleanup:true`, `active:false`.
+
+`browser.flow.start`
+
+- Use for a single stateful page interaction.
+- Required: `url`.
+- Defaults: `active:false`, `cleanup:true`.
+- Save `sessionId`.
+
+`browser.flow.observe`
+
+- Required: `sessionId`.
+- `mode:"text"` by default; use `mode:"a11y"` for controls and labels.
+
+`browser.flow.act`
+
+- Required: `sessionId`, `steps`.
+- Step types: `goto`, `eval`, `click`, `fill`, `wait`, `read_text`.
+- Stops at first failed step and returns prior step results plus failure location.
+
+`browser.flow.finish`
+
+- Required: `sessionId`.
+- Use `cleanup:true` unless the user asked to keep the tab.
+
+## Raw Browser Tools
+
+Use raw tools when operating on an existing tab, debugging, uploading, or using page primitives unavailable through flow.
+
+- `browsers_context`: list connected browser instances and browser IDs.
+- `tabs_context`: list tabs; pass `all:true` for a full listing.
+- `tabs_create`: create a tab; default to `active:false`.
+- `tabs_close`: close a known tab ID.
+- `navigate`: navigate a known tab.
+- `get_page_text`: extract `document.body.innerText` from a known tab; pass `maxChars` when only a small slice is needed.
+- `read_page`: read the accessibility tree.
+- `find`: find an accessible element by description.
+- `click_element`: click a `refId`.
+- `fill_element`: clear and type into a `refId`.
+- `form_input`: set an input value by `refId`.
+- `javascript_tool`: evaluate page JavaScript.
+- `read_console_messages`: read console logs and errors.
+- `read_network_requests`: read network records, optionally failed only.
+- `get_response_body`: read a response body by request ID.
+- `file_upload` and `upload_image`: upload through a file input after confirmation.
+- `computer`: screenshot and low-level input when DOM primitives are insufficient. Screenshots default to compact JPEG quality; raise `quality` only when visual detail matters.
+
+For tab-targeted raw tools, pass `browserId` and `tabId` explicitly. Do not depend on the active tab.
+
+## Helper Script
+
+The bundled helper calls bro's Streamable HTTP MCP endpoint and reads the bearer token from `~/.bro/settings.json`.
+
+```bash
+scripts/bro-call.mjs <tool-name> [json-arguments]
+scripts/bro-call.mjs --list
+scripts/bro-call.mjs --status
+scripts/bro-call.mjs browser.extract '{"url":"https://example.com"}' --json
+```
+
+Use `--json` when you need `sessionId`, structured diagnostics, or exact result fields.
+
+## Error Interpretation
+
+- `No browsers connected`: the server is up but no extension authenticated over `/ws`.
+- `Browser ... not found`: refresh `browsers_context`; never silently retarget.
+- `requires tabId`: choose a tab first with `tabs_context` or create one with `tabs_create`.
+- `partial`: extraction produced some data but readiness did not meet quality thresholds; inspect diagnostics and retry with a better method.
+- Missing `~/.bro/settings.json`: bro has not initialized local state.
+- HTTP 401 or unauthorized: token mismatch between the helper, server, or extension options.

package/skills/bro-browser/references/workflows.md

@@ -0,0 +1,146 @@
+# Bro Browser Workflows
+
+Use these recipes to translate user outcomes into stable bro calls.
+
+## Read-Only Orientation
+
+Use this when the user asks about current browser state, open tabs, or whether bro is working.
+
+1. Check server status:
+
+```bash
+scripts/bro-call.mjs --status
+```
+
+2. Confirm bro local state exists:
+
+```bash
+ls -l ~/.bro/settings.json
+```
+
+If the settings file is missing, initialize bro with `bro doctor` or `bro serve`.
+
+3. Check connected browser instances:
+
+```bash
+scripts/bro-call.mjs browsers_context
+```
+
+4. List tabs only after a browser is connected:
+
+```bash
+scripts/bro-call.mjs tabs_context '{"all":true}'
+```
+
+If the output includes a `browserId`, reuse it in later calls. If you target an existing tab, record its `tabId` and pass both IDs explicitly.
+
+## Extract Known URLs
+
+Use `browser.extract` for one URL:
+
+```bash
+scripts/bro-call.mjs browser.extract '{"url":"https://example.com","maxChars":8000,"cleanup":true}'
+```
+
+Use `browser.batch.extract` for multiple URLs:
+
+```bash
+scripts/bro-call.mjs browser.batch.extract '{"inputs":[{"id":"a","url":"https://example.com/a"},{"id":"b","url":"https://example.com/b"}],"concurrency":4,"maxChars":6000,"cleanup":true}'
+```
+
+Prefer `inputs` with stable IDs when the answer must cite which URL produced each result. Add `includeLinks:true` only when URLs are part of the answer or the next crawl step. Keep `cleanup:true` unless the user needs to inspect the opened tabs.
+
+## Sequential Page Interaction
+
+Use a flow when a page needs clicks, filling, waiting, or navigation state.
+
+1. Start a background flow:
+
+```bash
+scripts/bro-call.mjs browser.flow.start '{"url":"https://example.com","active":false,"cleanup":true}' --json
+```
+
+2. Save `sessionId` from the structured result.
+
+3. Observe the page:
+
+```bash
+scripts/bro-call.mjs browser.flow.observe '{"sessionId":"SESSION_ID","mode":"text"}'
+```
+
+4. Act with ordered steps:
+
+```bash
+scripts/bro-call.mjs browser.flow.act '{"sessionId":"SESSION_ID","steps":[{"type":"click","css":"button[type=submit]"},{"type":"wait","ms":500},{"type":"read_text"}]}' --json
+```
+
+5. Finish even if a step failed:
+
+```bash
+scripts/bro-call.mjs browser.flow.finish '{"sessionId":"SESSION_ID","cleanup":true}'
+```
+
+Use `mode:"a11y"` when visible text is insufficient to identify controls. Ask for explicit confirmation before a flow submits data or changes user state.
+
+## Existing Tab Inspection
+
+Use this when the user asks about an already open tab or says to use their current logged-in browser.
+
+If the current tab is the target, do one call:
+
+```bash
+scripts/bro-call.mjs browser.current.extract '{"maxChars":8000}'
+```
+
+Only use tab discovery when the current tab is ambiguous, the user mentioned a non-current open tab, or current extraction fails.
+
+1. Call `browsers_context`.
+2. Call `tabs_context {"all":true,"browserId":"..."}`.
+3. Identify the target tab from title and URL.
+4. Read the tab with `get_page_text` or `read_page`, always passing `browserId` and `tabId`.
+
+Example:
+
+```bash
+scripts/bro-call.mjs get_page_text '{"browserId":"BROWSER_ID","tabId":123,"maxChars":12000}'
+scripts/bro-call.mjs read_page '{"browserId":"BROWSER_ID","tabId":123,"filter":"interactive","compact":true,"maxChars":20000}'
+```
+
+Do not use foreground focus as identity after this point. The user may keep using the browser while the agent works.
+
+## Debug A Local Web App
+
+Use this for localhost app testing when the user wants browser-side console, network, or DOM evidence.
+
+1. Create a background tab:
+
+```bash
+scripts/bro-call.mjs tabs_create '{"url":"http://127.0.0.1:3000","active":false}' --json
+```
+
+2. Save `browserId` and `tabId`.
+3. Read page text or accessibility tree.
+4. Inspect console and network:
+
+```bash
+scripts/bro-call.mjs read_console_messages '{"browserId":"BROWSER_ID","tabId":123,"clear":false}'
+scripts/bro-call.mjs read_network_requests '{"browserId":"BROWSER_ID","tabId":123,"filter":"failed","timeoutMs":3000}'
+```
+
+5. Close task-owned tabs:
+
+```bash
+scripts/bro-call.mjs tabs_close '{"browserId":"BROWSER_ID","tabId":123}'
+```
+
+If the task needs screenshots or visual QA, use browser-specific tooling available in the session when required by the frontend workflow; bro is best for browser state and extraction.
+
+## Cleanup
+
+For raw tabs, call `tabs_close` on every tab you created. For flow sessions, call `browser.flow.finish`. For multi-tab agent work, `agent_done` can signal the session end:
+
+```bash
+scripts/bro-call.mjs agent_done '{"browserId":"BROWSER_ID","tabIds":[123,124]}'
+```
+
+Do not close tabs that existed before the task unless the user explicitly asked for that.

package/skills/bro-browser/scripts/bro-call.mjs

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+
+const DEFAULT_PORT = 3500;
+const tokenPath = `${process.env.HOME}/.bro/settings.json`;
+
+function usage(exitCode = 2) {
+  const text = [
+    'usage: bro-call.mjs <tool-name> [json-arguments] [--json] [--port PORT]',
+    '       bro-call.mjs --list [--json] [--port PORT]',
+    '       bro-call.mjs --status [--port PORT]',
+    '',
+    'examples:',
+    '  bro-call.mjs browsers_context',
+    '  bro-call.mjs tabs_context \'{"all":true}\'',
+    '  bro-call.mjs browser.extract \'{"url":"https://example.com"}\' --json',
+  ].join('\n');
+  console.error(text);
+  process.exit(exitCode);
+}
+
+let port = DEFAULT_PORT;
+let jsonOutput = false;
+let listTools = false;
+let statusOnly = false;
+const positionals = [];
+
+for (let i = 2; i < process.argv.length; i += 1) {
+  const arg = process.argv[i];
+  if (arg === '--help' || arg === '-h') usage(0);
+  if (arg === '--json') {
+    jsonOutput = true;
+    continue;
+  }
+  if (arg === '--list') {
+    listTools = true;
+    continue;
+  }
+  if (arg === '--status') {
+    statusOnly = true;
+    continue;
+  }
+  if (arg === '--port') {
+    const next = process.argv[i + 1];
+    if (!next) usage();
+    port = Number.parseInt(next, 10);
+    i += 1;
+    continue;
+  }
+  positionals.push(arg);
+}
+
+if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+  console.error(`invalid port: ${port}`);
+  process.exit(2);
+}
+
+const endpoint = `http://127.0.0.1:${port}/mcp`;
+
+async function printStatus() {
+  const response = await fetch(`http://127.0.0.1:${port}/status`);
+  const text = await response.text();
+  if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`);
+  console.log(JSON.stringify(JSON.parse(text), null, 2));
+}
+
+function readToken() {
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(tokenPath, 'utf8'));
+  } catch (error) {
+    throw new Error(
+      `failed to read ${tokenPath}: ${error.message}. Run bro doctor or bro serve to initialize bro local state.`
+    );
+  }
+  if (!parsed.token || typeof parsed.token !== 'string') {
+    throw new Error(`missing token in ${tokenPath}`);
+  }
+  return parsed.token;
+}
+
+function parseArgs(raw) {
+  if (!raw) return {};
+  try {
+    const value = JSON.parse(raw);
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+      throw new Error('arguments must be a JSON object');
+    }
+    return value;
+  } catch (error) {
+    throw new Error(`invalid JSON arguments: ${error.message}`);
+  }
+}
+
+function parseSseOrJson(text) {
+  const payloads = [];
+  for (const line of text.split('\n')) {
+    if (!line.startsWith('data: ')) continue;
+    const payload = line.slice(6).trim();
+    if (payload) payloads.push(payload);
+  }
+  if (payloads.length > 0) return JSON.parse(payloads[payloads.length - 1]);
+  return JSON.parse(text);
+}
+
+async function rpc(token, sessionId, id, method, params) {
+  const headers = {
+    'content-type': 'application/json',
+    accept: 'application/json, text/event-stream',
+    authorization: `Bearer ${token}`,
+  };
+  if (sessionId) headers['mcp-session-id'] = sessionId;
+
+  const response = await fetch(endpoint, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify({ jsonrpc: '2.0', id, method, params }),
+  });
+  const text = await response.text();
+  if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`);
+  return {
+    sessionId: response.headers.get('mcp-session-id'),
+    body: parseSseOrJson(text),
+  };
+}
+
+function printResult(body) {
+  if (jsonOutput) {
+    console.log(JSON.stringify(body, null, 2));
+    return;
+  }
+
+  const result = body.result;
+  const structured = result?.structuredContent ?? result?.structured_content;
+  let printed = false;
+
+  if (structured !== undefined) {
+    console.log(JSON.stringify(structured, null, 2));
+    printed = true;
+  }
+
+  const content = result?.content;
+  if (Array.isArray(content)) {
+    for (const item of content) {
+      if (item?.type === 'text') console.log(item.text);
+      else console.log(JSON.stringify(item));
+      printed = true;
+    }
+  }
+
+  if (!printed) console.log(JSON.stringify(body, null, 2));
+}
+
+async function main() {
+  if (statusOnly) {
+    if (positionals.length > 0 || listTools) usage();
+    await printStatus();
+    return;
+  }
+
+  const toolName = positionals[0];
+  if (!listTools && !toolName) usage();
+  if (positionals.length > (listTools ? 0 : 2)) usage();
+
+  const token = readToken();
+  const init = await rpc(token, null, 1, 'initialize', {
+    protocolVersion: '2024-11-05',
+    capabilities: {},
+    clientInfo: { name: 'codex-bro-helper', version: '0' },
+  });
+  const sessionId = init.sessionId;
+  if (!sessionId) throw new Error('bro did not return an MCP session id');
+
+  const call = listTools
+    ? await rpc(token, sessionId, 2, 'tools/list', {})
+    : await rpc(token, sessionId, 2, 'tools/call', {
+        name: toolName,
+        arguments: parseArgs(positionals[1]),
+      });
+
+  printResult(call.body);
+  const result = call.body.result;
+  if (result?.isError === true || result?.is_error === true) process.exitCode = 1;
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exit(1);
+});