From 45bfd012b9cba38f071881416ba1713eaabaea73 Mon Sep 17 00:00:00 2001 From: kalil0321 Date: Wed, 28 Oct 2026 23:07:00 +0100 Subject: [PATCH] Document the agent skill and the script_path guarantee --- README.md | 2 +- website/content/docs/cli/coding-agents.mdx | 43 +++++++++++++++++++++ website/content/docs/cli/meta.json | 2 +- website/content/docs/cli/scripted-usage.mdx | 5 ++- website/content/docs/installation.mdx | 1 + 5 files changed, 49 insertions(+), 4 deletions(-) create mode 100644 website/content/docs/cli/coding-agents.mdx diff --git a/README.md b/README.md index 40adc2f4..56ee03e7 100644 --- a/README.md +++ b/README.md @@ -169,7 +169,7 @@ Pass `--no-interactive` (and/or `--json`) to skip prompts. With `--json`, stdout | `url` | `string` \| `null` | | | `mode` | `string` \| `null` | `"auto"`, `"chrome-mcp"`, or `"agent-browser"`. | | `har_path` | `string` \| `null` | Captured HAR. | -| `script_path` | `string` \| `null` | Generated client. | +| `script_path` | `string` \| `null` | Generated client; exists whenever `status` is `"ok"`. | | `usage` | `object` | `{input_tokens, output_tokens, total_cost}`. | | `error` | `string` \| `null` | When `status == "error"`. | diff --git a/website/content/docs/cli/coding-agents.mdx b/website/content/docs/cli/coding-agents.mdx new file mode 100644 index 00000000..40cdc77d --- /dev/null +++ b/website/content/docs/cli/coding-agents.mdx @@ -0,0 +1,43 @@ +--- +title: Coding agents +description: Let Claude Code, Codex, Cursor, OpenCode and other agents drive the CLI through the agent skill. +--- + +Reverse API Engineer ships an [agent skill](https://github.com/kalil0321/reverse-api-engineer/tree/main/skills/reverse-api-engineer) +that tells coding agents how to drive the CLI. Install it in your project: + +```bash +npx skills add kalil0321/reverse-api-engineer +``` + +Then ask your agent for what you need, for example "get me a typed client for +the job search on this careers page". The skill only supplies instructions: the +agent still runs `reverse-api-engineer`, so the CLI must be installed (see +[Installation](/docs/installation)). + +## What the agent does + +1. **Checks the install** with `reverse-api-engineer --version`. +2. **Reuses an earlier capture** when `list` and `show --json` find one with a + client, instead of browsing again. +3. **Runs a preflight** with `agent --dry-run --json`, including the Chrome + auto-connect check for `chrome-mcp`. +4. **Captures in the background** with `agent --json-stream`, then waits for + the final `result` event. +5. **Verifies the client** by running it before handing it over. +6. **Iterates on the same capture** with `engineer ` when the run kept + a HAR (`auto`, `agent-browser` and manual runs). +7. **Hands it over** by copying the client into your project and summarizing + what it wraps, how it authenticates and what it did not test. + +## Your Chrome or a separate browser + +For public data the skill adds `--headless`, so your own Chrome is never +touched. When a site needs your login, it uses `chrome-mcp` in your Chrome: +tell the agent it may, keep Chrome open with auto-connect enabled at +`chrome://inspect/#remote-debugging`, and accept the connection prompt Chrome +shows when the run starts. If nobody accepts it, the run times out without a +client. + +See [Scripted usage](/docs/cli/scripted-usage) for the JSON contract the skill +relies on. diff --git a/website/content/docs/cli/meta.json b/website/content/docs/cli/meta.json index 41e4b4cb..d44a4163 100644 --- a/website/content/docs/cli/meta.json +++ b/website/content/docs/cli/meta.json @@ -1,4 +1,4 @@ { "title": "CLI reference", - "pages": ["commands", "scripted-usage"] + "pages": ["commands", "scripted-usage", "coding-agents"] } diff --git a/website/content/docs/cli/scripted-usage.mdx b/website/content/docs/cli/scripted-usage.mdx index 12a6f9a3..d59cef64 100644 --- a/website/content/docs/cli/scripted-usage.mdx +++ b/website/content/docs/cli/scripted-usage.mdx @@ -6,7 +6,8 @@ description: Drive the CLI from another agent or a wrapper script with --no-inte The CLI can be driven by another agent, a CI job, or a wrapper script. Use `agent --json` or `engineer --json` for a single machine-readable result, `list --json` and `show --json` for history inspection, and `run --json` to -execute generated scripts without contaminating stdout. +execute generated scripts without contaminating stdout. For coding agents, the +[agent skill](/docs/cli/coding-agents) wraps this contract. When `--json` is set: @@ -105,7 +106,7 @@ reverse-api-engineer run --file api_client.py \ | `url` | `string \| null` | Optional starting URL. | | `mode` | `string \| null` | Provider (`"auto"`, `"chrome-mcp"`, `"agent-browser"`). | | `har_path` | `string \| null` | Absolute path to the captured HAR (`recording.har`). | -| `script_path` | `string \| null` | Absolute path to the generated client when reverse engineering ran. | +| `script_path` | `string \| null` | Absolute path to the generated client. It exists whenever `status` is `"ok"`; a run that ends without writing it reports `engine_failure`. | | `usage` | `object` | Normalized token plus cost usage (`input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_write_tokens`, `total_cost_usd`) plus raw SDK usage under `raw`. | | `error` | `string \| null` | Human-readable error message when `status == "error"`. | | `error_kind` | `string \| null` | Machine-readable error category such as `misuse`, `network`, or `engine_failure`. | diff --git a/website/content/docs/installation.mdx b/website/content/docs/installation.mdx index 41948188..4579c22e 100644 --- a/website/content/docs/installation.mdx +++ b/website/content/docs/installation.mdx @@ -78,4 +78,5 @@ working on. +