How to use the Oracle CLI Best Practices agent skill

What the oracle skill makes the agent do

An agent skill is a folder with a SKILL.md file that gives an agent extra instructions for one task. This skill covers the oracle CLI: bundling a prompt with files, choosing an engine, managing sessions, and attaching files with clear patterns.

The skill tells the agent to preview what will be sent before running, to keep the file set small, and to reattach to a stored session rather than re-run a long job. It also tells the agent to treat the returned answer as advice to check against code and tests.

Install the oracle skill

You can install the skill in either of two ways. Download the ZIP from the skill's page on this site and unzip it. Then either place the folder in ~/.claude/skills/ for your user account, or in .claude/skills/ inside a project to limit it to that project.

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

• Personal: unzip into ~/.claude/skills/
• Project only: unzip into .claude/skills/ in your project folder
• Claude apps: Settings → Capabilities → Skills, then upload

Install the oracle CLI and check it runs

The skill depends on the oracle CLI, which is published as the npm package @steipete/oracle. The skill's metadata lists Node.js and npm as the way to install it. If the oracle binary is not installed, you can run it on demand through npx.

Run the help command first to confirm the tool works. The skill notes to avoid pnpx for this tool because of sqlite bindings.

• Requires the oracle binary, or npx to run it
• Requires Node.js and npm

Choose an engine and set up access

Oracle has two engines. The browser engine is the default workflow described in the skill and is used with GPT-5.2 Pro in ChatGPT. The API engine is used when you want it explicitly. If OPENAI_API_KEY is set, oracle picks the API engine automatically; otherwise it picks the browser.

The browser engine supports GPT and Gemini models only. For Claude, Grok or multi-model runs, the skill says to use the API engine. You can also run a browser session on a remote host with oracle serve and a token.

• Browser: needs access to ChatGPT in a browser
• API: needs OPENAI_API_KEY
• Remote: oracle serve on a host, then connect with a host:port and token

Attach the right files and preview before sending

Use the fewest files that still contain the answer. The --file option accepts files, directories and globs. You can repeat it, and entries can be comma-separated. Exclude patterns start with an exclamation mark.

Always preview first. A dry run sends nothing and uses no tokens. The --files-report flag shows token spend so you can judge the size before you commit. Files over 1 MB are rejected, and the tool skips common build folders such as node_modules, dist and .git by default. It honors .gitignore, does not follow symlinks, and ignores dotfiles unless you name them.

• Preview: oracle --dry-run summary with your --file set
• Token check: add --files-report
• Exclude test files with !**/*.test.* or snapshots with !**/*.snap
• Include dotfolders explicitly, for example .github/**

Write a high-signal prompt

Oracle starts with no knowledge of your project. The model cannot infer your stack, build tools or conventions, so the prompt must supply them. Each run is one-shot: the model does not remember earlier runs, so a follow-up must include the context again.

For long investigations, write a standalone prompt and keep the same file set so you can re-run it later.

• Project briefing: stack, build and test commands, platform limits
• Where things live: key folders, entry points, config files
• The exact question, what you tried, and the error text verbatim
• Constraints such as keeping the public API unchanged
• Desired output, such as a patch plan with tests or three options with tradeoffs

Reattach to long sessions instead of re-running

Browser runs with GPT-5.2 Pro often take about 10 minutes to an hour, and the CLI may detach or time out. Sessions are stored under ~/.oracle/sessions, or in the folder set by ORACLE_HOME_DIR. If a run times out, do not re-run it. List recent sessions and reattach.

Use --slug with three to five words to keep session IDs readable. The tool has a duplicate-prompt guard; use --force only when you really want a fresh run.

• List sessions from the last 72 hours with oracle status
• Reattach with oracle session <id> --render

Safety: secrets and network use

The skill runs scripts and uses the network. Every attached file is sent to a third-party model service. Do not attach .env files, key files or auth tokens. Redact aggressively and share only what the question needs. The skill is clear that sensitive code or credentials could be exposed if care is not taken.

If you use a fallback paste workflow, --render with --copy lets you copy the prompt and paste it yourself. The --copy flag is a hidden alias for --copy-markdown.

• Never attach secrets by default
• Check the --dry-run output for unexpected files before sending
• Treat answers as advice and verify them with your code and tests