oracle

What This Skill Does

The oracle skill is designed to supercharge your interaction with AI models by providing them with rich, contextual information from your codebase. It bundles your natural language prompt with selected files, creating a comprehensive "one-shot" request. This allows another AI model, such as GPT‑5.2 Pro, to understand and respond with real repository context, enabling actions like API interactions or browser automation. Think of it as giving the AI a precisely curated set of documents to work from, ensuring its responses are grounded in your project's reality. The output from these AI interactions should always be treated as advisory; thorough verification against your code and tests is essential.

Installation

To install the oracle skill, use the following command:

clawhub install openclaw/openclaw/skills/oracle

Alternatively, if you need to run the oracle CLI directly and it's not installed, you can use npx -y @steipete/oracle --help. Avoid pnpx for this tool due to its sqlite bindings.

Use Cases

The primary use case revolves around leveraging AI for code analysis, refactoring, documentation generation, and even test creation by providing it with relevant project files. The default workflow utilizes the browser engine, often with GPT‑5.2 Pro, which is suitable for complex, time-consuming tasks where a stored session you can reattach to is beneficial. This "long think" path can take anywhere from 10 minutes to an hour. Other use cases include:

• Code Review Assistance: Get AI suggestions on code quality, potential bugs, or adherence to best practices by feeding it relevant source files.
• Documentation Generation: Automate the creation of READMEs, API docs, or inline comments based on your existing codebase.
• Refactoring Suggestions: Receive AI-driven recommendations for improving code structure, performance, or maintainability.
• Test Case Generation: Get AI to draft unit or integration tests based on the functionality present in your code files.
• Debugging Support: Provide the AI with error logs and related code to help diagnose and resolve issues.

Example Prompts

1. prompt: Analyze the authentication flow in the provided files and suggest potential security improvements. Add comments directly to the relevant code snippets.
2. prompt: Refactor the userService to use async/await syntax consistently and improve error handling. Only include files from the src/services directory.
3. prompt: Generate comprehensive JSDoc comments for all exported functions in src/utils, explaining their parameters, return values, and potential side effects.

Tips & Limitations

• File Selection: Be precise with your file selection. Use globs effectively to include only the necessary files, minimizing token usage and improving AI focus. Preview your payload and token spend using --dry-run and --files-report.
• Engine Choice: The browser engine is the default and recommended for GPT‑5.2 Pro. Use --engine api explicitly if you need to access other models like Claude or Grok, or for multi-model runs. If OPENAI_API_KEY is set, the skill defaults to api mode.
• Session Management: For long-running tasks in browser mode, expect sessions to be stored. If a run detaches or times out, reattach to the existing session instead of restarting.
• Payload Limits: Files larger than 1 MB are rejected. The --browser-attachments setting controls how larger files are handled in browser mode (auto, never, always).
• Ignored Directories: By default, common development directories like node_modules, dist, coverage, and version control directories are skipped unless explicitly included. The skill also respects .gitignore rules when expanding globs.
• Symlinks and Dotfiles: Symlinks are not followed. Dotfiles are generally filtered unless explicitly included in your --file patterns.
• Output Verification: Always verify the AI's output against your code and tests. Treat AI suggestions as advisory.