SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsoil-explore

oil-explore

Coding & development

View repository

Updated 11-13 15:33

About this skill

oil-explore

SKILL_DIR refers to the absolute directory of the current Skill;<python> refers to Python 3.10+ (on macOS/Linux usually python3, on Windows usually py -3）；REPO_MAP is short for <python> "$SKILL_DIR"/scripts/repo_map.py ,PREFS is short for <python> "$SKILL_DIR"/scripts/preferences.py .

Core Rules

  • Strictly read-only throughout: During the exploration phase, never modify, create, or delete project files, do not install dependencies, and do not trigger commands that would change workspace state, seize foreground window focus, or pop up system permission dialogs.
  • Choose the lightest path based on familiarity: For tasks with a known structure or single-point location, use the host's built-in retrieval tools (such as glob / rg) to go straight to the target file, and do not force an extra round of full-repository scripts; only run this first when entering an unfamiliar repository or doing a preliminary survey for a large cross-module refactor REPO_MAP。
  • Low-cost local reading: When dispatching exploration sub-agents, explicitly use a lightweight, fast model tier (the user'spersonal preferencetakes precedence if otherwise specified); do not inherit an expensive main model by default; read key functions and type definitions closely only by local line numbers, and do not stuff entire large files verbatim into the main context.
  • Always check existing infrastructure and the real test entry point: In addition to clarifying the target business flow, you must also confirm the repository's existing shared components, shared core modules,AGENTS.md / DESIGN.md hard constraints, and the real quick-test commands specified by the project (note whether AGENTS.md disables the default slow full-suite command). If AGENTS.md has a development conventions subsection whose title contains oil-dev (REPO_MAP will display it directly), the quick-test and gate commands, high-risk and no-modify directories follow that subsection.

First choose the exploration tier

Tier Applicable scenario Execution method Default stopping point
quick Look up a single symbol, configuration item, or error location in a familiar repository Directly search the target keyword and locally read 1–3 code snippets (no need to run scripts or use sub-agents) After giving the precise file:line conclusion, stop
medium Sort out the entry points, state transitions, and reusable components of a single feature module Local search + read AGENTS.md / DESIGN.md -related constraints + close reading of the module's core files Output the module call chain, reusable infrastructure, and local quick-test commands
thorough First entry into a large unfamiliar repository, preliminary survey before a cross-subsystem refactor First run REPO_MAP to view the global structure → dispatch 2–3 lightweight read-only sub-agents in parallel to explore along independent subsystem boundaries Summarize a structured exploration brief and prepare to hand off to the planning phase

Workflow

1. Global snapshot (only required for unfamiliar repositories or the thorough tier)

When first entering an unfamiliar project or when the directory structure and parallel working tree distribution are unclear, run a lightweight structure snapshot (follows Git ignore rules, returns directory scale, extension distribution, spec files, defined scripts and Worktree list within seconds):

REPO_MAP --workspace "<项目路径>"

If the output shows the existence of AGENTS.md、DESIGN.md or a custom scripts/ test script, preferentially read the command conventions and prohibitions in it that are relevant to the current task, and do not fabricate default test commands from experience. In the output, ci_run_steps is the command actually executed by CI; when confirming quick-test and gate commands, use it and the repository's defined scripts as the standard.

2. Read-only deep dive along real module boundaries

  • quick / medium tier: Use host search tools directly to locate relevant files, read 40–100 lines at a time by line number to confirm the real call relationships, and conveniently check reusable components and helper functions in the same module or public directories.
  • thorough tier: Read Parallel Read-Only Exploration Slicing Guide。divide slices by non-overlapping subsystem directories(do not forcibly split views and state that are strongly coupled in the same batch of files across multiple sub-Agents for repeated reading):
    • If the current environment supports native sub-Agents: first run PREFS get oil-explore --host <宿主> to readpersonal preferences。shared applies to all hosts,host_text applies only to the current host; when the two conflict, host_text takes precedence. If the preferences specify which sub-Agent mechanism to use, which model, how many to dispatch, or how to reclaim them, follow that; for parts not specified, use the defaults: launch 2–3 read-only sub-Agents, explicitly specifying a lightweight fast model tier for parallel queries. If the command fails or is not set, continue with the default approach and do not interrupt the user for this.
    • If the current environment does not support sub-Agents: the main Agent reads local line ranges block by block in subsystem order, and after reading each block, records the file:line summary before moving to the next block.

3. Cross-verify and output an exploration brief

Before delivery, verify that all conclusions are backed by code:

  1. Attach accurate 文件路径:行号 and core symbol names to key conclusions, and distinguish "facts confirmed by code" from "product questions pending user decision".
  2. Explicitly list thepublic components, design tokens or underlying modules that can be directly reused for this task。
  3. Explicitly list the correspondinglocal quick-test commandsand existing test paths after modifying this module.

Personal preferences

The entire oil-dev series shares one local preference file ~/.oil-dev/preferences.md(the environment variable OIL_DEV_HOME can change the directory), written in natural language: one section per Skill (e.g. ## oil-explore); the text immediately under the Skill heading applies to all hosts, and the text under### 宿主名 applies only to that host. It only holds settings related to the user personally; team-shared conventions are written in the repository's AGENTS.md of oil-dev subsection.

<宿主> is which Agent product you are currently running in, using a lowercase hyphenated name, for example claude-code、codex、antigravity、opencode、workbuddy、kimi-code、grok-build、deepseek-harness、gemini-cli。

oil-explore reads preferences only when dispatching sub-Agents at the thorough tier. Common contents are the dispatch mechanism, model, quantity cap and reclamation method, for example:

## oil-explore

探索子 Agent 最多 3 个。

### antigravity

- 用 swarm 派发探索子 Agent，每个 Worker 用 `<模型 ID>`。
- 收齐所有简报后结束 Worker。

Do not proactively ask about preferences. When the user says things like "from now on use a certain model for exploration sub-Agents" or "in Antigravity, dispatch with swarm", save it:set replaces the entire section, so first use PREFS get take the existing text, merge the new requirements into it, save it, and finally tell the user the saved content.

PREFS set oil-explore --host <宿主> --text "<合并后的完整文字>"

For requirements that apply to all hosts, replace --host <宿主> with --all-hosts. When the user asks to view it, run PREFS show; when the user asks to delete it, run PREFS unset oil-explore --host <宿主>. When the command returns status: ERROR , tell the user error verbatim.

Output and downstream handoff

Stop after the exploration brief is delivered; do not make incidental code changes, and do not immediately lay out a lengthy plan unless asked.

Downstream intent Handoff action
Develop a development plan based on exploration facts Enter oil-planand directly reuse the file:lineidentified this time, reusable components, and local quick-test commands
Discover that the resident documentation description is clearly out of sync with the current code directory Enter oil-govern to carry out documentation and specification governance

Resource navigation