gpt-researcher — Claude Code skill: what it does, how to install
Assists developers in extending, debugging, and integrating GPT Researcher pipelines, retrievers, and MCP data sources.
Apache-2.0 1 installs ★ 30,819 updated 2026-10-10
npx skills add assafelovic/gpt-researcher --skill gpt-researcher -a claude-codeWhat gpt-researcher does
Provides internal architectural context for GPT Researcher, an autonomous agent that collects web or local data using a planner-executor-publisher setup. It directs the coding assistant through core classes such as GPTResearcher, sub-query planning in ResearchConductor, and report generation via ReportGenerator.
The skill details an 8-step pattern for implementing new features, rules for registering search engines in gpt_researcher/retrievers/, and streaming events over WebSocket connections. It also explains configuring MCP tools via mcp_configs with deep or fast strategies.
Every research call relies on async execution. Configuration keys are normalized to lowercase on access, so calling uppercase attribute names causes runtime failures.
What it helps with
- implement a custom retriever class in the research pipeline
- attach external data sources using MCP server configurations
- follow the 8-step workflow to introduce features across backend and frontend
- stream execution status updates and logs through WebSocket handlers
Example prompts for the agent
- Show how to register a new retriever in gpt_researcher/actions/retriever.py
- Configure an MCP GitHub server connection for deep research mode
- Help implement the 8-step pattern for adding a provider to gpt-researcher
How to install gpt-researcher
1Skills CLI (Vercel)
npx skills add assafelovic/gpt-researcher --skill gpt-researcher -a claude-code2Manually: put the files in place
~/.claude/skills/claude/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/claude/
1Skills CLI (Vercel)
npx skills add assafelovic/gpt-researcher --skill gpt-researcher -a codex2Manually: put the files in place
.agents/skills/claude/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add assafelovic/gpt-researcher --skill gpt-researcher -a cursor2Manually: put the files in place
.cursor/skills/claude/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install assafelovic/gpt-researcher claude2Manually: put the files in place
.github/skills/claude/SKILL.md1Skills CLI (Vercel)
npx skills add assafelovic/gpt-researcher --skill gpt-researcher -a gemini-cli2Platform CLI
gemini skills install https://github.com/assafelovic/gpt-researcher --path .claudeManually: put the files in place
.devin/skills/claude/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add assafelovic/gpt-researcher --skill gpt-researcher -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about gpt-researcher
How to install gpt-researcher in Claude Code?
Run npx skills add assafelovic/gpt-researcher --skill claude -a claude-code. The skill will be placed at ~/.claude/skills/claude/SKILL.md.
What is the gpt-researcher skill used for?
It provides your coding assistant with deep knowledge of the GPT Researcher repository, including class maps, configuration rules, and retriever conventions.
How does configuration priority work in GPT Researcher?
Values resolve starting with environment variables, falling back to JSON configuration files, and finally default variables. Attributes must be accessed in lowercase.
Source text
SKILL.md · Apache-2.0
---
name: gpt-researcher
description: GPT Researcher is an autonomous deep research agent that conducts web and local research, producing detailed reports with citations. Use this skill when helping developers understand, extend, debug, or integrate with GPT Researcher - including adding features, understanding the architecture, working with the API, customizing research workflows, adding new retrievers, integrating MCP data sources, or troubleshooting research pipelines.
---
# GPT Researcher Development Skill
GPT Researcher is an LLM-based autonomous agent using a planner-executor-publisher pattern with parallelized agent work for speed and reliability.
## Quick Start
### Basic Python Usage
```python
from gpt_researcher import GPTResearcher
import asyncio
async def main():
researcher = GPTResearcher(
query="What are the latest AI developments?",
report_type="research_report", # or detailed_report, deep, outline_report
report_source="web", # or local, hybrid
)
await researcher.conduct_research()
report = await researcher.write_report()
print(report)
asyncio.run(main())
```
### Run Servers
```bash
# Backend
python -m uvicorn backend.server.server:app --reload --port 8000
# Frontend
cd frontend/nextjs && npm install && npm run dev
```
---
## Key File Locations
| Need | Primary File | Key Classes |
|------|--------------|-------------|
| Main orchestrator | `gpt_researcher/agent.py` | `GPTResearcher` |
| Research logic | `gpt_researcher/skills/researcher.py` | `ResearchConductor` |
| Report writing | `gpt_researcher/skills/writer.py` | `ReportGenerator` |
| All prompts | `gpt_researcher/prompts.py` | `PromptFamily` |
| Configuration | `gpt_researcher/config/config.py` | `Config` |
| Config defaults | `gpt_researcher/config/variables/default.py` | `DEFAULT_CONFIG` |
| API server | `backend/server/app.py` | FastAPI `app` |
| Search engines | `gpt_researcher/retrievers/` | Various retrievers |
---
## Architecture Overview
```
User Query → GPTResearcher.__init__()
│
▼
choose_agent() → (agent_type, role_prompt)
│
▼
ResearchConductor.conduct_research()
├── plan_research() → sub_queries
├── For each sub_query:
│ └── _process_sub_query() → context
└── Aggregate contexts
│
▼
[Optional] ImageGenerator.plan_and_generate_images()
│
▼
ReportGenerator.write_report() → Markdown report
```
**For detailed architecture diagrams**: See [references/architecture.md](references/architecture.md)
---
## Core Patterns
### Adding a New Feature (8-Step Pattern)
1. **Config** → Add to `gpt_researcher/config/variables/default.py`
2. **Provider** → Create in `gpt_researcher/llm_provider/my_feature/`
3. **Skill** → Create in `gpt_researcher/skills/my_feature.py`
4. **Agent** → Integrate in `gpt_researcher/agent.py`
5. **Prompts** → Update `gpt_researcher/prompts.py`
6. **WebSocket** → Events via `stream_output()`
7. **Frontend** → Handle events in `useWebSocket.ts`
8. **Docs** → Create `docs/docs/gpt-researcher/gptr/my_feature.md`
**For complete feature addition guide with Image Generation case study**: See [references/adding-features.md](references/adding-features.md)
### Adding a New Retriever
```python
# 1. Create: gpt_researcher/retrievers/my_retriever/my_retriever.py
class MyRetriever:
def __init__(self, query: str, headers: dict = None):
self.query = query
async def search(self, max_results: int = 10) -> list[dict]:
# Return: [{"title": str, "href": str, "body": str}]
pass
# 2. Register in gpt_researcher/actions/retriever.py
case "my_retriever":
from gpt_researcher.retrievers.my_retriever import MyRetriever
return MyRetriever
# 3. Export in gpt_researcher/retrievers/__init__.py
```
**For complete retriever documentation**: See [references/retrievers.md](references/retrievers.md)
---
## Configuration
Config keys are **lowercased** when accessed:
```python
# In default.py: "SMART_LLM": "gpt-4o"
# Access as: self.cfg.smart_llm # lowercase!
```
Priority: Environment Variables → JSON Config File → Default Values
**For complete configuration reference**: See [references/config-reference.md](references/config-reference.md)
---
## Common Integration Points
### WebSocket Streaming
```python
class WebSocketHandler:
async def send_json(self, data):
print(f"[{data['type']}] {data.get('output', '')}")
researcher = GPTResearcher(query="...", websocket=WebSocketHandler())
```
### MCP Data Sources
```python
researcher = GPTResearcher(
query="Open source AI projects",
mcp_configs=[{
"name": "github",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {"GITHUB_TOKEN": os.getenv("GITHUB_TOKEN")}
}],
mcp_strategy="deep", # or "fast", "disabled"
)
```
**For MCP integration details**: See [references/mcp.md](references/mcp.md)
### Deep Research Mode
```python
researcher = GPTResearcher(
query="Comprehensive analysis of quantum computing",
report_type="deep", # Triggers recursive tree-like exploration
)
```
**For deep research configuration**: See [references/deep-research.md](references/deep-research.md)
---
## Error Handling
Always use graceful degradation in skills:
```python
async def execute(self, ...):
if not self.is_enabled():
return [] # Don't crash
try:
result = await self.provider.execute(...)
return result
except Exception as e:
await stream_output("logs", "error", f"⚠️ {e}", self.websocket)
return [] # Graceful degradation
```
---
## Critical Gotchas
| ❌ Mistake | ✅ Correct |
|-----------|-----------|
| `config.MY_VAR` | `config.my_var` (lowercased) |
| Editing pip-installed package | `pip install -e .` |
| Forgetting async/await | All research methods are async |
| `websocket.send_json()` on None | Check `if websocket:` first |
| Not registering retriever | Add to `retriever.py` match statement |
---
## Reference Documentation
| Topic | File |
|-------|------|
| System architecture & diagrams | [references/architecture.md](references/architecture.md) |
| Core components & signatures | [references/components.md](references/components.md) |
| Research flow & data flow | [references/flows.md](references/flows.md) |
| Prompt system | [references/prompts.md](references/prompts.md) |
| Retriever system | [references/retrievers.md](references/retrievers.md) |
| MCP integration | [references/mcp.md](references/mcp.md) |
| Deep research mode | [references/deep-research.md](references/deep-research.md) |
| Multi-agent system | [references/multi-agents.md](references/multi-agents.md) |
| Adding features guide | [references/adding-features.md](references/adding-features.md) |
| Advanced patterns | [references/advanced-patterns.md](references/advanced-patterns.md) |
| REST & WebSocket API | [references/api-reference.md](references/api-reference.md) |
| Configuration variables | [references/config-reference.md](references/config-reference.md) |
© assafelovic · Apache-2.0 · assafelovic/gpt-researcher