Research Agent System

Also available in: 한국어 (Korean)

A multi-agent research system that collects data on any topic and generates comprehensive research reports with strict data integrity and citations.

Reports are written in English by default. The report language automatically follows the language of your request, or any language you explicitly specify.

---

Overview

Automates the following using AI coding agents such as Claude Code and Gemini CLI:

• Supports any topic: market research, industry analysis, policy/regulatory trends, technology trends, and more
• Collects data in multiple languages (English, local languages, etc.)
• Generates research reports with clear citations, reference years, and sources
• Ensures data accuracy through up to 3 verification iterations

Default report language is English. If your request is written in another language, or you explicitly specify an output language, the report will be generated in that language.

---

Requirements

Tool	Version	Required
Claude Code	latest	Required
Firecrawl CLI	v1.9+	Recommended (credits required)
agent-browser skill	latest	Recommended (free)
Playwright MCP	latest	Optional (free)

Works without Firecrawl using only the built-in WebSearch + WebFetch tools.

---

Installation & Setup

Method 1: Install as a Skill via npx skills add

Use this method to add the research workflow as a reusable skill to your existing Claude Code setup — no need to clone the repository.

npx skills add github:godstale/Deep-Research-Skill

Once installed, open Claude Code in any working directory and start researching:

claude .

The skill is now available in all your Claude Code sessions. Just describe your research topic and Claude will run the full Phase 1-4 workflow automatically.

Note: This installs SKILL.md only. The detailed sub-agent procedures in AGENTS.md are embedded in the skill, so it works standalone without cloning the repo.

---

Method 2: Clone the Repository (for Claude Code — full system)

Use this method if you want the complete system with all instruction files (CLAUDE.md, AGENTS.md, GEMINI.md) and want to customize or extend the workflow.

1. Clone the repository

git clone https://github.com/godstale/Deep-Research-Skill.git
cd Deep-Research-Skill

2. Set up Firecrawl (recommended)

npm install -g @mendable/firecrawl-js
firecrawl auth   # enter your API key

3. Open in Claude Code

claude .

Claude Code automatically reads CLAUDE.md and AGENTS.md to initialize the full system.

---

Usage

Open a Claude Code session and enter your research topic:

Research the Nigeria cosmetics market

Analyze the impact of EU CBAM policy on Korean exporters

나이지리아 화장품 시장 조사해줘

(Requests written in a non-English language will produce a report in that language)

Global EV battery market trends 2025 — write in Spanish

(Explicitly specified language overrides the default)

The system will automatically:

1. Create docs/[SLUG]/ and track progress in TODO.md
2. Run parallel web searches with multiple sub-agents
3. Refine and verify collected data
4. Generate the final report at docs/[SLUG]/REPORT.md

---

File Structure

.
+-- CLAUDE.md          # Claude Code instructions (primary)
+-- AGENTS.md          # Detailed per-phase workflow and sub-agent instructions
+-- GEMINI.md          # Compressed instructions for Gemini CLI
+-- README.md          # This file
+-- README.ko.md       # Korean README
+-- docs/
|   +-- [SLUG]/        # Per-topic folder (e.g. NIGERIA_COSMETICS)
|       +-- TODO.md          # Task tracking (progress status)
|       +-- LOG.txt          # Detailed execution log
|       +-- SOURCES.md       # Trusted sources list
|       +-- WEB_SEARCH_RAW.md  # Phase 1: raw web search results
|       +-- SEARCH_RESULT.md   # Phase 2: refined collected data
|       +-- REPORT.md          # Phase 3: final research report
|       +-- VERIFICATION.md    # Phase 4: verification results
|       +-- scraped/           # Temporary raw extraction files
+-- scripts/           # Utility scripts

---

Workflow

Phase 1-A: Broad Search (3 Sub-Agents in parallel)
     |
Phase 2-1: First-pass detailed data collection
     |
  [Data sufficiency check]
  Sufficient ---------> Phase 3: Report generation
  Insufficient |                      |
Phase 1-B: Trusted source discovery   Phase 4: Report verification
     |                                    |
Phase 1-C: Targeted search          [Verification result]
     |                              Pass -> Done
Phase 2-2: Second-pass collection   Fail -> Re-run Phase 1 (max 3 iterations)
     |
Phase 3 -> Phase 4

---

Tool Priority

Purpose	1st (free)	2nd (free)	Last resort (credits)
Search	WebSearch	—	firecrawl search
Page fetch	WebFetch	agent-browser / Playwright MCP	firecrawl scrape

---

Core Principles

• Never fabricate numbers, URLs, or sources — mark as unknown if unclear
• Only use data present in SEARCH_RESULT.md for the report
• Every statistic must include reference year + source: $2.3B (2023, World Bank)
• Never delete existing files when re-running a Phase — only append or update
• Always save TODO.md and LOG.txt before ending the session

---

Using with Other AI Agents

This system supports multiple AI coding agents:

Agent	Instruction File	Notes
Claude Code	CLAUDE.md	Primary support, full feature set
Gemini CLI	GEMINI.md	Compressed instructions, references AGENTS.md
Other agents	AGENTS.md	Universal detailed instructions

---

License

MIT License