Guide · Agent skill

How to use the Oracle Second-Model Review agent skill

Updated 2026-11-02 · written with AI from the project's own documentation and checked against our catalogue data

The Oracle skill teaches an AI agent to use the Oracle command-line tool, which packages your question and selected project files into one request and sends it to another AI model for a second opinion on debugging, refactoring or design. This guide is for developers who want that second review and can accept a slow, browser-based workflow or pay for API runs. By the end you will know how to install the skill, choose a tight file set, preview what gets sent, and reattach to long-running sessions.

Oracle Second-Model Reviewsteipete/agent-scripts · MIT Download the skill

Quick start

1Install the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
2Check Node.js and ChatGPT sign-in. Confirm npx is available and that you are signed in to ChatGPT in the browser if you plan to use the default browser engine.
3Ask for a review with a clear task. Describe the bug, refactor or design question in plain language, with the relevant area of the code and any error text.
4Preview the file set. Run a dry run to see what would be sent, and use the files report to spot token-heavy files before running.
5Run in browser mode. Let the agent run Oracle with --engine browser and gpt-5.5-pro. Expect a long wait.
6Reattach if the run times out. Use oracle status and oracle session with the session ID rather than re-running the prompt.
7Verify the answer. Check the advice against the codebase and tests, since the skill states that outputs are advisory.

What the Oracle skill makes the agent do

Oracle bundles your prompt and selected files into a single one-shot request, so another model can answer with real context from your repository. The request can go through browser automation (the default workflow uses GPT-5.5 Pro in ChatGPT) or through a provider API.

The skill tells the agent to treat every answer as advisory and to verify it against the codebase and tests before relying on it.

Use it for a second opinion on a tricky bug, a refactor or a design decision.
Expect the agent to choose a file set, preview the bundle, and then run Oracle.

Install the Oracle skill

Download the ZIP from this page and unzip it. Place the resulting oracle folder in one of these locations:

For a personal install, put it in ~/.claude/skills/. For a single project, put it in that project's .claude/skills/ folder.

In the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

Personal: ~/.claude/skills/oracle
Project: .claude/skills/oracle inside your repository

Check the requirements before you start

The skill runs the Oracle CLI through npx, so Node.js with npx must be installed. The default browser engine needs a ChatGPT account that you are signed in to in the browser.

Required: Node.js with npx (the skill runs @steipete/oracle via npx).
Required for the default browser engine: a ChatGPT account signed in through the browser.
Optional: OPENAI_API_KEY or other provider keys for API runs. These cost money.
Optional: 1Password CLI (op) and a tmux session, only if you use the password-manager key injection described in the source.
Optional: a local Oracle checkout built with pnpm, for debugging Oracle itself.

Trigger the skill with a natural request

You do not need special syntax. Ask the agent in plain language for a second model's review, and name the task and the files that matter. The agent should then pick a tight file set, preview it, and run Oracle in browser mode.

A useful request states the goal, the relevant area of the code, and any error text. Example requests:

Get a second opinion from GPT-5.5 Pro on why the login retry logic in src/auth fails intermittently. Include the error text.
Ask another model to review the refactor plan for the billing module, keeping the public API unchanged.
Preview which files would be sent for a design review of the sync engine before running anything.

Run Oracle yourself: preview, then run

The source recommends previewing first. A dry run shows what would be sent without spending tokens, and a files report helps spot large files before you pay for a run.

Show help once per session with --help.
Preview the bundle with --dry-run summary; add --files-report to see token-heavy files.
Run the main browser path with --engine browser and --model gpt-5.5-pro.

npx -y @steipete/oracle --dry-run summary -p "<task>" --file "src/**" --file "!**/*.test.*"
npx -y @steipete/oracle --dry-run summary --files-report -p "<task>" --file "src/**"
npx -y @steipete/oracle --engine browser --model gpt-5.5-pro -p "<task>" --file "src/**"

Choose the file set carefully

The --file flag accepts files, directories and globs. Use include patterns for what the model needs and ! patterns to exclude noise such as tests and snapshots. Keep the set to the fewest files that still contain the truth.

Oracle has default behaviour you should know about. It skips common build and dependency folders, honours .gitignore, does not follow symlinks, and filters dotfiles unless you opt in. Files over 1 MB are rejected by default.

Default-ignored directories: node_modules, dist, coverage, .git, .turbo, .next, build, tmp.
Dotfiles need an explicit pattern, for example --file ".github/**".
The 1 MB per-file cap can be raised with ORACLE_MAX_FILE_SIZE_BYTES or maxFileSizeBytes in ~/.oracle/config.json.
The source sets a target of keeping total input under about 196k tokens.

npx -y @steipete/oracle --dry-run summary -p "<task>" --file "src/**" --file "!src/**/*.test.ts" --file "!**/*.snap"

Handle long runs and reattach instead of re-running

Browser runs are slow by design. The source says a run can take roughly 10 minutes to an hour and is saved as a session. If the CLI times out or detaches, do not start the run again, because a duplicate prompt guard exists and a fresh run costs time or money. Reattach to the stored session instead.

Browser runs save durable files, including transcript.md, under ~/.oracle/sessions/<id>/artifacts/.

List recent sessions: oracle status --hours 72
Reattach to one: oracle session <id> --render
Use --slug "<3-5 words>" to keep session IDs readable.
Use --force only when you truly want a fresh run.

oracle status --hours 72
oracle session <id> --render

Write a prompt the second model can use

Oracle starts with no knowledge of your project, so the prompt must supply it. Include a short project briefing, where things live, the exact question with the verbatim error, your constraints, and the output you want.

Project briefing: stack, build and test commands, platform constraints.
Where things live: key directories, entrypoints, config files.
Question: what you tried and the exact error text.
Constraints: for example, do not change X or keep the public API.
Desired output: a patch plan with tests, risky assumptions, or three options with tradeoffs.

What people use it for

Getting a second model's view on a bug that resists repeated fixes, using the relevant source files and the exact error.
Reviewing a planned refactor for risks before changing code, with constraints such as keeping the public API.
Comparing answers from several models in one advisory panel using API runs with --allow-partial.
Asking for design tradeoffs on a module, with the project briefing included in the prompt.

Frequently asked questions

How do I install the Oracle agent skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for a personal install, or into a project's .claude/skills/ folder. In the Claude apps you can instead upload it under Settings → Capabilities → Skills.

What do I need to run the Oracle skill?

You need Node.js with npx, because the skill runs @steipete/oracle through npx. For the default browser engine you also need a ChatGPT account signed in through your browser. API keys are optional and cost money.

Is the Oracle skill free?

The skill is licensed under MIT. The browser workflow uses your ChatGPT account, and API runs incur provider usage costs, so the source asks for explicit consent before any API run.

Is my code safe when I use this skill?

Selected files are sent to third-party model providers, so do not use it on projects with secrets or sensitive code that must stay on your machine. Avoid including secrets in the file set and check the exclude patterns before running.

Why does my Oracle browser run take so long?

The browser path is a human-in-the-loop workflow and can take about 10 minutes to an hour. If it times out, reattach to the stored session with oracle session <id> rather than re-running the prompt.

How does Oracle compare with asking a model directly?

Oracle packages your prompt with selected repository files into one request, so the model sees real project context instead of only what you paste. It is slower than a quick chat, and the skill says outputs must still be verified against the codebase and tests.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

The Oracle skill suits developers who want a second model to review a hard bug, refactor or design using real repository files, and who can wait for slow browser runs or pay for API calls. Pick something else if you need fast answers, cannot send your code to third-party providers, or expect the second model's output to be correct without checking it.

Download the skill