Deep Research Skills Tutorial: Add Structured Deep Research to Claude Code and Codex

Created

When doing deep research with AI, you have probably run into this: the results are either too shallow, off-topic, or scattered across a dozen tabs that you still need to organize manually. Worse, the whole process is a black box - you hand off the topic and wait, with no way to steer midway.

Deep Research Skills solves this. It is not a standalone app but a set of skill files you install into Claude Code, OpenCode, or Codex. It breaks deep research into three stages - generate outline, deep dive each item, compile report - and lets you intervene at every stage instead of just watching from the sidelines.

What is Deep Research Skills? An open-source structured research skill (MIT license) by Weizhena, inspired by the RhinoInsight paper. It uses a two-phase workflow (outline generation + deep investigation) with human-in-the-loop design to execute high-quality, systematic research inside Claude Code, OpenCode, and Codex. It supports parallel agent deep dives per research item, automatic data validation, and generates a Markdown report with table of contents.

Key Data:

  • 🌟 GitHub Stars: 1,274+ (Repository)
  • 📦 Current Version: master branch, actively maintained
  • ⚖️ License: MIT License
  • 🧠 Core Feature: Two-phase structured research (outline + deep research) with human-in-the-loop control
  • 📦 Core Feature: Supports Claude Code / OpenCode / Codex with bilingual skill files (EN/ZH)
  • 🔬 Academic Background: Inspired by the RhinoInsight paper on control mechanisms for model behavior

Prerequisites

Before installing Deep Research Skills, make sure you have:

  • Python 3.x: Required for the pyyaml dependency
  • An AI coding tool: Claude Code (recommended 2.1.0+), OpenCode, or Codex
  • Git: For cloning the repository
  • Basic command-line knowledge: Familiarity with cp, pip, etc.

Overview

This Deep Research Skills guide covers:

  1. Installation on your AI tool (Claude Code / OpenCode / Codex)
  2. Understanding the two-phase research workflow
  3. Using the five commands
  4. Comparison with similar deep research tools

Step-by-Step Guide

Step 1: Clone the Repository

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

Step 2: Install in Your AI Tool

Deep Research Skills works with three major AI coding platforms. Choose the installation method for your tool:

Claude Code Installation

1
2
3
4
5
6
7
8
9
10
11
12
# English version
cp -r skills/research-en/* ~/.claude/skills/

# Chinese version
cp -r skills/research-zh/* ~/.claude/skills/

# Required: Install web search agent and modules
cp agents/web-search-agent.md ~/.claude/agents/
cp -r agents/web-search-modules ~/.claude/agents/

# Required: Install Python dependency
pip install pyyaml

Claude Code 2.1.0+ supports direct /skill-name triggers. After installation, type /research to start.

OpenCode Installation

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# Skills (same directory as Claude Code)
cp -r skills/research-en/* ~/.claude/skills/

# Required: Enable web search for current shell
export OPENCODE_ENABLE_EXA=1

# Optional: Make it permanent
echo 'export OPENCODE_ENABLE_EXA=1' >> ~/.bashrc
source ~/.bashrc

# Required: Install agent and modules
cp agents/web-search-opencode.md ~/.config/opencode/agents/web-search.md
cp -r agents/web-search-modules ~/.config/opencode/agents/

# Required: Install Python dependency
pip install pyyaml

⚠️ Important: In OpenCode, any model needs OPENCODE_ENABLE_EXA=1 to use websearch. Without it, you only get web fetch, which is much weaker for the deep research phase.

Codex Installation

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# Create directories
mkdir -p ~/.codex/skills ~/.codex/agents

# English version
cp -r skills/research-codex-en/* ~/.codex/skills/

# Chinese version
cp -r skills/research-codex-zh/* ~/.codex/skills/

# Required: Install web researcher agent and modules
cp agents-codex/web-researcher.toml ~/.codex/agents/
cp -r agents-codex/web-search-modules ~/.codex/agents/

# Required: Install Python dependency
pip install pyyaml

Update ~/.codex/config.toml using either method:

Option A: Automatic script

1
2
cd deep-research-skills
bash scripts/install-codex.sh

Option B: Manual edit - add to ~/.codex/config.toml:

1
2
3
4
5
6
7
8
9
suppress_unstable_features_warning = true

[features]
multi_agent = true
default_mode_request_user_input = true

[agents.web_researcher]
description = "Use this agent when you need to research information on the internet..."
config_file = "agents/web-researcher.toml"

Step 3: Run Your First Research

The workflow has three phases:

Phase 1: Generate Research Outline

1
/research AI Agent Demo 2025

The skill first generates an initial framework from model knowledge (research items + field definitions), then launches a web search agent to supplement with the latest online information. It produces two YAML files:

  • outline.yaml - Research items list + execution config (parallelism, items per agent, etc.)
  • fields.yaml - Field definitions (what dimensions to collect for each item)

You can refine after generation: add/remove items (/research-add-items) or add/modify fields (/research-add-fields).

💡 Forget the commands? Just use natural language. You do not need to memorize the slash commands. Simply tell your AI Agent what you want to do in plain language, and it will match the appropriate skill automatically. Examples:

  • “Use the research skill to investigate the AI Agent landscape in 2025”
  • “Help me create a deep research outline about XXX”
  • “Continue deep diving into the existing research results”

Codex users can also trigger skills via the /skills → List Skills menu.

Phase 2: Deep Research

1
/research-deep

Following the outline.yaml configuration, the skill launches parallel agents in batches. Each agent independently searches the web, organizes information, outputs structured JSON, and runs validation scripts to ensure complete field coverage.

💡 Highlight: Supports resume - completed JSON files are automatically skipped, so you do not have to start over if interrupted.

Phase 3: Generate Report

1
/research-report

All JSON data is compiled into a Markdown report (report.md) with a table of contents, ready to read or share.

Step 4: Install in Your AI Tool Summary

Claude Code: Install skill files to ~/.claude/skills/, trigger with /research commands. Claude Code 2.1.0+ natively supports /skill-name syntax.

Codex (OpenAI): Install skill files to ~/.codex/skills/, configure config.toml to enable multi_agent. Trigger via /skills menu or natural language.

OpenCode: Shares skill directory with Claude Code (~/.claude/skills/), but requires OPENCODE_ENABLE_EXA=1 for web search.

Cursor / Windsurf: While officially supporting the three platforms above, you can copy SKILL.md files into your project directory as rule files.

Comparison with Similar Deep Research Tools

The deep research landscape has many open-source options. Here is how Deep Research Skills stacks up against the major alternatives:

Feature Deep Research Skills GPT-Researcher Tongyi DeepResearch Open Deep Research (LangChain) Khoj Academic Research Skills
GitHub Stars 1,274+ 27,800+ 19,500+ 11,700+ 35,200+ 33,800+
Form Factor AI tool skill files Standalone Python app Standalone Python app LangChain framework module Self-hosted platform AI tool skill files
Installation Copy files to ~/.claude/skills/ pip install + config pip install + config pip install + LangChain Docker / pip Copy files to ~/.claude/skills/
Runtime Claude Code / OpenCode / Codex Standalone Standalone Within LangChain ecosystem Self-hosted web app Claude Code
Human-in-the-Loop ✅ Intervene at every stage ❌ Fully automatic ❌ Fully automatic ❌ Fully automatic ⚠️ Limited ⚠️ Limited
Two-Phase Design ✅ Outline + deep dive ❌ Single pass ❌ Single pass ❌ Single pass ❌ Single query ✅ Multi-phase pipeline
Parallel Agents ✅ Configurable parallelism ✅ Multi-agent ✅ Multi-agent ✅ Configurable ❌ Single query ✅ Configurable
Resume Support ✅ Auto-skip completed ❌ ❌ ❌ N/A ❌
Structured Output YAML outline + JSON + MD report Markdown report Markdown report Markdown report Conversational Academic paper pipeline
Validation ✅ Auto field coverage check ❌ ❌ ❌ ❌ ✅ Peer review simulation
Use Case General research (tech/market/academic/due diligence) General research General research General research Personal knowledge management Academic papers
License MIT Apache-2.0 Apache-2.0 MIT AGPL-3.0 Other

How to Choose?

  • If you primarily use Claude Code / Codex for research: Deep Research Skills is the most natural choice - zero extra dependencies, works immediately after installation, and you can steer the research at every stage
  • If you need a standalone, fully automated research service: GPT-Researcher or Tongyi DeepResearch are better fits - they are complete Python applications you can integrate into your own systems
  • If you do academic research and paper reviews: Academic Research Skills is purpose-built for academic pipelines, covering literature search, writing, peer review, and revision
  • If you need a personal knowledge base + deep research: Khoj is an all-in-one platform combining RAG, automations, and deep research

More Specialized Tools

Tool Stars Highlight Best For
claude-deep-research-skill 789 8-phase pipeline, source credibility scoring Enterprise-grade Claude Code research
deep-searcher 7,898+ Private data research with vector DB Enterprise internal knowledge base
open-deep-research (Firecrawl) 6,249+ Large-scale web data extraction Heavy web scraping research
ARIS 12,500+ Lightweight Markdown-only skills ML experiment automation

The Five Commands

Command Purpose When to Use
/research <topic> Generate research outline (items + fields) Start of research
/research-add-items Add more items to existing outline Outline feels incomplete
/research-add-fields Add more field definitions Need more data dimensions
/research-deep Launch parallel agent deep dives After outline is confirmed
/research-report Compile JSON results into Markdown report After all research completes

💡 All commands support natural language triggers. If you forget the slash commands, just describe what you want in plain language and the AI Agent will automatically identify and invoke the corresponding skill.

FAQ

Q: How do I install Deep Research Skills?
A: Clone the repository, copy the skill files to your AI tool’s skill directory (~/.claude/skills/ for Claude Code/OpenCode, ~/.codex/skills/ for Codex), install the web search agent and pyyaml dependency. See the installation section above for detailed commands.

Q: Where is the Deep Research Skills tutorial?
A: This article is the complete Deep Research Skills tutorial covering installation, configuration, workflow, and advanced tips. You can also check the official GitHub repository.

Q: Is it free?
A: Yes, completely free under the MIT license. However, you need API access for your AI tool (Anthropic API for Claude Code, OpenAI API for Codex, etc.).

Q: How does it compare to GPT-Researcher?
A: The biggest difference is human-in-the-loop design. GPT-Researcher is fully automatic - give it a topic and wait for results. Deep Research Skills lets you confirm and adjust at every stage, making it better for scenarios requiring precise research direction control. Also, Deep Research Skills is a skill file - no extra Python deployment needed.

Q: Does it support non-English research?
A: Yes. The repository includes bilingual skill files (Chinese and English). Install the Chinese version for Chinese-language research and reports.

Q: How is research quality ensured?
A: Each research agent runs a validation script (validate_json.py) after completion to check field coverage. Uncertain fields are marked with [uncertain]. You can focus on these flagged items during the report phase.

Q: How large a topic can I research?
A: There is no hard limit. The batch_size and items_per_agent parameters in outline.yaml control parallelism. Adjust batch size based on your API quota and network conditions.

Q: How do I trigger these skills in Codex?
A: Two ways: use /skills -> List Skills menu, or use natural language like Use the research skill to build an outline for XXX.

Advanced Tips

  • Tune parallelism: Modify batch_size (how many agents run simultaneously) and items_per_agent (items per agent) in outline.yaml to find the sweet spot for your API quota
  • Leverage resume support: If your API quota runs out mid-research or your network drops, just re-run /research-deep - completed JSON files are automatically skipped
  • Reuse field templates: For repeated research types (e.g., competitor analysis), reuse your fields.yaml across projects to skip redefining fields
  • Combine with other skills: Use Deep Research Skills for research, then feed the report into other AI agents for further analysis or content generation

Conclusion

This is the complete Deep Research Skills installation guide and usage tutorial. From cloning the repository to installing on three platforms, from the two-phase research workflow to five-command control, you can now have AI agents perform truly structured, deep, and controllable systematic research instead of superficial searches. Whether for technology evaluation, market analysis, or academic literature review, this Deep Research Skills guide covers everything from getting started to advanced usage.

How to cite this article: This article is based on the Deep Research Skills official GitHub repository (verified 2026-06-23, 1,274+ Stars). All installation commands and configuration details are verified against the master branch. Academic background references the RhinoInsight paper.