Skip to content

Document the agent skill and the script_path guarantee #153

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kalil0321 merged 1 commit into from
Oct 29, 2026
Merged

Document the agent skill and the script_path guarantee #153

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"`. |

@cubic-dev-ai cubic-dev-ai Bot Oct 28, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: agent --json can still return status: "ok" with script_path: null, so this documents an invariant the CLI does not enforce. Make the null-path case an engine_failure before documenting this guarantee, or soften the table entry.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At README.md, line 172:

<comment>`agent --json` can still return `status: "ok"` with `script_path: null`, so this documents an invariant the CLI does not enforce. Make the null-path case an `engine_failure` before documenting this guarantee, or soften the table entry.</comment>

<file context>
@@ -169,7 +169,7 @@ Pass `--no-interactive` (and/or `--json`) to skip prompts. With `--json`, stdout
 | `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"`.                                              |
</file context>

| `usage` | `object` | `{input_tokens, output_tokens, total_cost}`. |
| `error` | `string` \| `null` | When `status == "error"`. |

Expand Down
43 changes: 43 additions & 0 deletions website/content/docs/cli/coding-agents.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <run_id>` 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.
2 changes: 1 addition & 1 deletion website/content/docs/cli/meta.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
{
"title": "CLI reference",
"pages": ["commands", "scripted-usage"]
"pages": ["commands", "scripted-usage", "coding-agents"]
}
5 changes: 3 additions & 2 deletions website/content/docs/cli/scripted-usage.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -105,7 +106,7 @@ reverse-api-engineer run <run_id> --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`. |

@greptile-apps greptile-apps Bot Oct 28, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Dry runs generate no client

The guarantee also covers agent --dry-run --json, which returns status: "ok" with script_path: null when its checks pass. This page documents that command just above the table. Wrapper authors could therefore mistake a successful setup check for proof that a client exists. This is a non-blocking documentation mismatch: limit the guarantee to completed capture or engineering runs, and qualify the matching README.md row too.

Artifacts

Evidence from the check

  • The executed Python harness invokes the real CLI against base and head, captures responses, and asserts successful checks, a null script path, and early exit; no CLI functions are mocked.

Command output from the check

  • Ran the reproduction against the base revision and captured source, commands, JSON, tracing, and passing assertions; a successful dry run already returned a null script path.

Command output from the check

  • Ran the same reproduction against the supplied head and captured the changed documentation alongside JSON and passing assertions; the new guarantee contradicts the unchanged successful dry-run behavior.

View artifacts

TREX Ran code and verified through TREX

Prompt To Fix With AI 
This is a comment left during a code review.
Path: website/content/docs/cli/scripted-usage.mdx
Line: 109

Comment:
**Dry runs generate no client**

The guarantee also covers `agent --dry-run --json`, which returns `status: "ok"` with `script_path: null` when its checks pass. This page documents that command just above the table. Wrapper authors could therefore mistake a successful setup check for proof that a client exists. This is a non-blocking documentation mismatch: limit the guarantee to completed capture or engineering runs, and qualify the matching `README.md` row too.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

@chatgpt-codex-connector chatgpt-codex-connector Bot Oct 28, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Exclude dry runs from the script existence guarantee

For agent --dry-run --json, a successful preflight returns status: "ok" with script_path: null: _build_dry_run_payload explicitly constructs that response, and the command exits without generating a client. Since this page also documents dry runs, the unconditional existence guarantee can mislead wrappers into treating a successful preflight as a generated artifact. Qualify the guarantee as applying to completed capture/engineering runs, and retain the preflight exception in both JSON tables.

Useful? React with 👍 / 👎.

| `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`. |
Expand Down
1 change: 1 addition & 0 deletions website/content/docs/installation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,4 +78,5 @@ working on.
<Cards>
<Card title="Quick start" href="/docs/quick-start" description="From `pip install` to a working client." />
<Card title="Configure your model" href="/docs/configuration/models" description="Choose the model for your selected SDK." />
<Card title="Use it from your coding agent" href="/docs/cli/coding-agents" description="Install the agent skill for Claude Code, Codex, Cursor and more." />
</Cards>
Loading