Deep Research Skill: three runtimes, one outline gate, one shell variable

Outline first, then a per-item investigation loop

Research projects tend to fail in one predictable place: the list of questions gets fixed before anyone reads the source material, and the expensive part runs anyway. This project moves that decision to the front. Given the topic `AI Agent Demo 2025`, the first command returns an outline, and the worked example ends with 17 items to investigate plus a field list attached to each one. Nothing has been searched at that point.

Phase 2, the next command, is the one that touches the network. It works through the items one at a time and hands each to a separate agent, which is why parallel workers matter here rather than a longer single prompt. Collected results are kept as JSON, and phase 3 renders that JSON into `report.md` with a table of contents.

The editable outline is the actual mechanism. Correcting the list costs one text edit. Correcting it after a full sweep costs a second sweep.

Five slash commands split editing from running

Five commands cover the whole lifecycle, and they divide along a line that matters for cost. Three of them change a document: `/research` creates the outline, `/research-add-items` widens the item list, and `/research-add-fields` widens the schema applied to every item. The other 2 do the work you pay for, `/research-deep` and `/research-report`, and both consume what those three produced.

2 of the editing commands carry an order dependency that is easy to miss. Each acts on an outline that already exists, so calling `/research-add-fields` before an outline has been generated leaves you adding field definitions with no items to attach them to.

The route to those names also changes with the runtime. On Claude Code 2.1.0 and later the slash form works directly, while older versions need the `run /skill-name` format. Codex has no slash form at all: skills are listed through `/skills` and picked from `List Skills`, or triggered by asking in plain language.

Three runtimes need three different copy commands

There is no package manager entry and no installer for Claude Code. The skill is a folder of markdown that you copy into your agent's skills directory yourself, and the copy sequence is short enough to read in one screen.

git clone https://github.com/Weizhena/deep-research-skills.git
cd deep-research-skills

cp -r skills/research-en/* ~/.claude/skills/
cp agents/web-search-agent.md ~/.claude/agents/
cp -r agents/web-search-modules ~/.claude/agents/
pip install pyyaml

The second block has 4 lines and all 4 are load bearing. The third line copies a directory of modules, so copying only the single agent markdown file leaves the agent without them. The last line is the dependency every install path marks as required.

With the files in place, the first real step is a topic, not a search:

/research AI Agent Demo 2025

You should get an outline of items and fields back rather than prose about the subject. Read it before going further, because every stage below it costs web requests.

OpenCode installs its skills into the Claude Code directory

The OpenCode path contains the most surprising line in the project. Its skill copy target is `~/.claude/skills/`, the Claude Code directory, and the comment in the install block says the copy is the same as for Claude Code. Only the agent definition moves into an OpenCode directory, and it is renamed on the way:

export OPENCODE_ENABLE_EXA=1
cp agents/web-search-opencode.md ~/.config/opencode/agents/web-search.md
cp -r agents/web-search-modules ~/.config/opencode/agents/

Nothing in the repository explains what happens to someone who runs OpenCode and has never installed Claude Code, and no second copy target is offered anywhere in the install docs. Read the path as a property of this install rather than as a reason to install a second product, then confirm your OpenCode build reads that skills directory before spending a session on the outline phase.

The Codex agent path and the copy command disagree

Codex needs the most configuration and carries the one internal contradiction worth checking before you depend on it. The install line puts the agent file into one directory:

mkdir -p ~/.codex/skills ~/.codex/agents
cp agents-codex/web-researcher.toml ~/.codex/agents/

The manual configuration then points Codex at a different relative path, `agents/web-researcher.toml`. How that path is resolved is not stated in the project's own files, so whether the manual route finds the copied file stays unconfirmed from what is published.

That gap is what the script route closes. `bash scripts/install-codex.sh` writes the configuration for you, while the manual option asks you to type it, and the keys are worth reading before you type them:

[features]
multi_agent = true
default_mode_request_user_input = true

[agents.web_researcher]
config_file = "agents/web-researcher.toml"

`multi_agent = true` allows the per-item workers, `default_mode_request_user_input = true` is the switch that turns the human-in-the-loop design into an actual prompt, and `suppress_unstable_features_warning = true` hides the warning those flags produce.

Without OPENCODE_ENABLE_EXA=1 the deep phase drops to web fetch

The failure that costs the most time is the one that still looks like it works. Without the environment variable, OpenCode exposes only `web fetch`, and the install notes state that this is weaker for the deep research phase. Nothing errors. The outline generates, the workers run, the report is written, and the collected material is quietly thinner. The requirement covers any model in OpenCode, not only the `gpt-5.4` default named in that install section.

A plain export covers the shell you typed it into. The persistence step writes the same line to `~/.bashrc` and reloads the file:

echo 'export OPENCODE_ENABLE_EXA=1' >> ~/.bashrc
source ~/.bashrc

That file is read by interactive bash shells and by nothing else. A session opened from a different shell, or started with bash bypassed, comes up without the variable and without any message that the deep phase has degraded. Checking it before a long run is cheaper than reading a thin report afterwards.

A Python dependency wrapped around markdown skill files

The payload is markdown, yet every install path ends with `pip install pyyaml`, and the project's primary language is Python. Which component parses YAML is not stated, and the repository files given here do not show the import site, so the cost of that requirement cannot be judged from the documentation.

Upgrade cost is similarly thin. The top level holds `scripts/`, `tests/` and `skills/`, but 1 script is named anywhere, `scripts/install-codex.sh`, and no command is given for running anything under `tests/`. Updating an existing installation therefore means re-cloning and re-running the copy commands by hand, with no documented way to tell which copies are already current.

Redistribution is unrestricted under the MIT licence, which allows reuse inside a closed tool and modification without further conditions. The last push was on 2026-08-23.

When the outline gate is the wrong tool

The gate pays off when the work is genuinely enumerative: seventeen products, seventeen papers, seventeen vendors, each needing the same fields and the same sources treated the same way. It is the wrong tool when the task is one question with one good source, because the outline phase then adds a file to author and an approval to wait through before anything comes back.

The Codex route makes that trade-off concrete, since the same skills can be triggered by asking in plain language instead of through a command. That path skips the outline and skips the per-item JSON that `/research-report` consumes, so it returns a paragraph instead of a re-runnable artifact. Two routes, same model, different output shape.

The other wrong-tool case is a runtime with no usable web access. The outline still generates and the deep pass still runs, so the failure surfaces as thin rows in the finished report rather than as an error message.

Editorial conclusion

Adopt this skill when the work is enumerative and you would rather correct seventeen items in a text file than read seventeen thin search results. Skip it when the sources are already known, when the question needs judgement rather than a list, or when you cannot set `OPENCODE_ENABLE_EXA=1` and keep it exported. Verify three things first: that your agent reads the directory you copied the skills into, that `pip install pyyaml` ran, and that one `/research-deep` pass returns sources rather than only fetches.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Weizhena/Deep-Research-skills on GitHub