Deep research
Skill dmitrykrivaltsevich/claude-skills/skills/deep-research
Orchestrates multi-phase autonomous research across all available skills. Discovers skill capabilities, manages persistent research state (questions, sources, facts, coverage), and guides the LLM through scope → sweep → deep-read → cross-reference → synthesise phases. Use when the user asks for deep research, comprehensive analysis, multi-source investigation, literature review, or any task requiring iterative search-read-analyse cycles across multiple data sources.From its SKILL.md
npx -y skills add dmitrykrivaltsevich/claude-skills --skill deep-researchAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
20.4 KB, as published. Nobody here has run it
Deep Research Skill
MANDATORY — read before doing anything else:
- NEVER delegate research to Agent() or any subagent. Execute ALL phases directly in the main conversation. Spawning an Agent bypasses these instructions and breaks the workflow.
- NEVER use built-in Fetch to download URLs. It does NOT mimic a browser and gets blocked (403). To download ANY URL, use duckduckgo's
download.py— it sets browser headers and handles anti-bot protection. Every URL you want to read MUST go throughdownload.py.- NEVER use built-in Web Search. Use duckduckgo's
search.pyinstead.${CLAUDE_SKILL_DIR}= this skill only. To run duckduckgo scripts, read the/duckduckgoSKILL.md first — it has its own${CLAUDE_SKILL_DIR}.
Contents
- Architecture
- DuckDuckGo Quick Reference
- Scripts
- Quick Start
- Research Workflow
- Convergence Rules
- State File
- State/Environment Discipline
- Working with Other Skills
- Context Management
- Reference
Architecture
This skill is an orchestrator, not a data fetcher. It provides a small data-pipe toolkit: discover.py for capability discovery, state.py for durable research state, json_query.py for JSON slice reopening, and page_query.py for markdown/text page slice reopening. The LLM does all the thinking: decomposing goals into questions, choosing which skills to invoke, evaluating coverage, deciding when to dig deeper, and synthesising findings.
The research state/environment is the source of truth. The transcript is not durable memory. Every broad sweep, shortlist, deep-read batch, and synthesis handoff should be reconstructed from external state/environment artifacts rather than from prior chat turns.
User question
↓
LLM: decompose into sub-questions
↓
discover.py → capability map (what skills/scripts are available)
↓
state.py init → create research session
↓
┌─────────────────────────────────────────┐
│ PHASE LOOP (LLM orchestrates) │
│ │
│ 1. Pick unexplored questions │
│ 2. Choose skill + script for each │
│ 3. Run scripts → capture discovery │
│ artifacts in external state/env │
│ 4. LLM: narrow to working-set files │
│ and update research state │
│ 5. LLM: check convergence │
│ 6. If not converged → generate new │
│ questions, loop back to 1 │
└─────────────────────────────────────────┘
↓
state.py export → full research state
↓
LLM: synthesise final report
DuckDuckGo Quick Reference
Before using these commands: read the /duckduckgo SKILL.md to get its ${CLAUDE_SKILL_DIR}. The variable below (DDG_DIR) is a placeholder — replace it with the actual path from the duckduckgo SKILL.md.
# Web search (text, news, or images):
uv run --no-config ${DDG_DIR}/scripts/search.py text "your query" --max-results 10
uv run --no-config ${DDG_DIR}/scripts/search.py news "your query" --timelimit w
uv run --no-config ${DDG_DIR}/scripts/search.py images "your query"
# Comprehensive news sweep (multiple topics):
uv run --no-config ${DDG_DIR}/scripts/top_news.py --groups tech science
# *** DOWNLOAD ANY URL (replaces Fetch — mimics browser, avoids 403) ***:
uv run --no-config ${DDG_DIR}/scripts/download.py "https://example.com" --format md
# Fact checking (multi-source):
uv run --no-config ${DDG_DIR}/scripts/fact_check.py "claim to verify"
# Trending topics:
uv run --no-config ${DDG_DIR}/scripts/trending.py --discover
# Multi-language search:
uv run --no-config ${DDG_DIR}/scripts/translate_search.py "en:query" "de:query"
When you find a URL you want to read — use download.py, NEVER Fetch. Fetch gets 403 errors; download.py mimics a real browser.
For duckduckgo discovery scripts, prefer native --output artifact mode over shell redirection.
State/Environment Discipline
Use two layers of external state/environment:
- Research state — the durable source of truth managed by
state.py - Round artifacts — file-backed discovery sets, working sets, and downloaded pages for the current round
Recommended round layout:
/tmp/<research-id>-<round>-discovery.json— raw search/fact-check/trend output/tmp/<research-id>-<round>-working-set.json— shortlisted sources, clusters, gaps, or support matrix/tmp/<research-id>/pages/<slug>.md— downloaded page text/tmp/<research-id>-<round>-facts.json— facts to append tostate.py
Rules:
- Broad tool output MUST land in round artifacts first, not in the transcript.
state.pystores accepted research state: questions, sources, facts, phases.- Round artifacts store messy intermediate environment state for the current pass.
- When resuming, start from
state.pyplus the latest working-set artifact, not from chat history. - After a phase boundary, carry forward only
{research_id, phase, artifact paths, small summary, next action}. - Use
json_query.pyto reopen only the slice you need from saved JSON artifacts instead of rereading the entire file. - Use
page_query.pyto reopen only the slice you need from saved markdown/text page artifacts instead of rereading the entire file.
Scripts
| Task | Script | What it does |
|---|---|---|
| Discover available skills | discover.py | Scans skills/ directory, outputs JSON capability map |
| Initialize/resume research | state.py init | Creates or resumes a research session |
| Add research questions | state.py add-questions | Appends questions (deduped) to state (use --file) |
| Update question status | state.py update-question | Marks question as unexplored/partially/covered (use --file) |
| Add sources | state.py add-sources | Records URLs/docs with skill attribution (use --file) |
| Add facts | state.py add-facts | Records claims with source IDs and confidence (use --file) |
| Advance phase | state.py update-phase | Moves to next research phase |
| Check progress | state.py status | Returns coverage summary JSON |
| Export full state | state.py export | Dumps complete research state as JSON |
| Reopen JSON slices | json_query.py | Returns only the selected slice from a saved JSON artifact |
| Reopen page slices | page_query.py | Returns only the selected heading/chunk/line slice from a page artifact |
Quick Start
# Discover what skills are available:
uv run --no-config ${CLAUDE_SKILL_DIR}/scripts/discover.py [--skills-dir PATH]
uv run --no-config ${CLAUDE_SKILL_DIR}/scripts/discover.py --output /tmp/discover.json
# Initialize a research session:
uv run --no-config ${CLAUDE_SKILL_DIR}/scripts/state.py init --research-id "my-topic" --goal "Understand X in depth"
# Add questions — use Write tool to create the JSON file, then pass --file:
# Write /tmp/questions.json with: ["What is X?", "How does Y relate to Z?"]
uv run --no-config ${CLAUDE_SKILL_DIR}/scripts/state.py add-questions --research-id "my-topic" --file /tmp/questions.json
# Update a question's status:
# Write /tmp/uq.json with: {"question": "What is X?", "status": "covered"}
uv run --no-config ${CLAUDE_SKILL_DIR}/scripts/state.py update-question --research-id "my-topic" --file /tmp/uq.json --status covered
# Record sources found:
# Write /tmp/sources.json with: [{"url": "https://...", "title": "Article", "skill": "duckduckgo"}]
uv run --no-config ${CLAUDE_SKILL_DIR}/scripts/state.py add-sources --research-id "my-topic" --file /tmp/sources.json
# Record extracted facts:
# Write /tmp/facts.json with: [{"claim": "X causes Y", "source_ids": ["s1", "s2"], "confidence": "high"}]
uv run --no-config ${CLAUDE_SKILL_DIR}/scripts/state.py add-facts --research-id "my-topic" --file /tmp/facts.json
# Advance to next phase:
uv run --no-config ${CLAUDE_SKILL_DIR}/scripts/state.py update-phase --research-id "my-topic" --phase sweep
# Check progress:
uv run --no-config ${CLAUDE_SKILL_DIR}/scripts/state.py status --research-id "my-topic"
# Export full state for synthesis:
uv run --no-config ${CLAUDE_SKILL_DIR}/scripts/state.py export --research-id "my-topic"
uv run --no-config ${CLAUDE_SKILL_DIR}/scripts/state.py export --research-id "my-topic" --output /tmp/research-state.json
# Reopen only the covered questions from a saved state artifact:
uv run --no-config ${CLAUDE_SKILL_DIR}/scripts/json_query.py --file /tmp/research-state.json --selector questions --where status=covered --fields text
# Reopen only one section from a downloaded page artifact:
uv run --no-config ${CLAUDE_SKILL_DIR}/scripts/page_query.py --file /tmp/my-topic/pages/article.md --heading "Transport"
# Custom state directory (when user says "store results in ..."):
uv run --no-config ${CLAUDE_SKILL_DIR}/scripts/state.py init --research-id "my-topic" --goal "..." --state-dir /path/to/custom/dir
Research Workflow — 5 Phases
The LLM drives each phase. Scripts provide I/O and persistence; the LLM provides reasoning.
Phase 1: Scope & Decompose
- Run
discover.pyto see what skills/scripts are available - Run
state.py initto create a research session - Decompose the user's goal into 5–15 specific, answerable sub-questions
- Run
state.py add-questionsto record them - Run
state.py update-phase --phase scope
LLM guidance: Questions should be concrete and verifiable. Bad: "Is AI good?" Good: "What are the top 3 documented risks of LLM deployment in healthcare as of 2026?" Each question should be answerable by finding specific sources.
Phase 2: Broad Sweep
Reminder: Do NOT use Agent(), Web Search, or Fetch. Run duckduckgo scripts directly via
uv run.
- For each unexplored question, choose the best skill/script to gather data
- Run the chosen skill's scripts into a discovery artifact, not into the transcript — read the skill's SKILL.md first to get correct commands
- Build a working-set artifact from that discovery artifact: shortlist, gap list, clusters, or support matrix
- Record discovered sources via
state.py add-sources, but only for the working set you actually carry forward - Extract preliminary facts from the working-set artifact via
state.py add-facts - Mark questions as
partiallyif some data found, leaveunexploredif nothing useful - Run
state.py update-phase --phase sweep
Skill routing — use the capability map from discover.py, then READ the target skill's SKILL.md:
- Web search → read
/duckduckgoSKILL.md, use itssearch.py,top_news.py. NEVER use built-in Web Search. - Page download → read
/duckduckgoSKILL.md, use itsdownload.py. NEVER use built-in Fetch. - Fact checking → read
/duckduckgoSKILL.md, use itsfact_check.py - Trending topics → read
/duckduckgoSKILL.md, use itstrending.py - Google Drive documents → read
/google-driveSKILL.md, use its scripts - Other skills as discovered
Decomposition before search: For specialized topics, decompose into precise queries BEFORE running search scripts. Enumerate vendors, products, publications, and sub-categories from existing knowledge, then search for each specifically.
Artifact-first pattern:
- Capture broad sweep output to
/tmp/<research-id>-qN-discovery.jsonvia the source skill's native--outputflag when available - Build
/tmp/<research-id>-qN-working-set.json - Append only shortlisted sources and accepted preliminary facts into
state.py - Discard raw discovery from working memory once the working-set artifact exists
Phase 3: Deep Read
- For each
partiallycovered question, fetch full content of promising sources from the latest working-set artifact - Read
/duckduckgoSKILL.md, use itsdownload.pyto get full text into/tmp/<research-id>/pages/(or/google-drivedownload.pyfor Drive files) - Use
page_query.pyon the saved page files to reopen only the needed heading, chunk, or line range - Extract detailed facts with source attribution into a facts artifact
- Run
state.py add-factsfor each batch of findings - Discover new questions from what was read — run
state.py add-questions - Update question statuses based on new evidence
- Run
state.py update-phase --phase deep-read
LLM guidance: Read critically. Note contradictions between sources. When sources disagree, record both claims with confidence levels: high (multiple quality sources agree), medium (single source or partial evidence), low (unverified, social media, single blog).
Phase 4: Cross-Reference
- Run
state.py exportto see all accumulated facts - Reopen only the smallest relevant working-set, facts, or page artifacts needed for the current contradiction/gap using
json_query.pyorpage_query.py - Look for contradictions, gaps, and patterns across sources
- For contradictions: search for additional sources to resolve them
- For gaps: generate targeted new questions, go back to sweep/deep-read
- Update fact confidence levels based on cross-source agreement
- Run
state.py update-phase --phase cross-reference
LLM guidance: This is where analytical quality matters most. Cluster facts by theme. Identify which claims have multi-source backing vs. single-source. Flag facts where the only sources are opinion pieces or social media.
Phase 5: Synthesise
- Run
state.py exportfor the final state - Run
state.py statusto confirm coverage - Synthesise findings into a structured report with:
- Executive summary
- Key findings with inline numbered citations
[1],[2]etc. in the body text - Confidence assessment per finding
- Open questions / areas needing more research
- Numbered Sources section — each source gets a number matching the inline citations, with full title, author (if known), URL, and access date
- Every claim, statistic, or factual statement in the report MUST have at least one inline citation
[N]pointing to the Sources section. Do not leave any claim unsourced. - Run
state.py update-phase --phase synthesise
Convergence Rules
The LLM decides when to stop. These are guidelines, not hard limits:
| Signal | Meaning |
|---|---|
All questions covered | Research goal fully addressed |
| 3 consecutive rounds with <2 new facts | Diminishing returns — synthesise |
≥80% questions covered or partially | Good enough — ask user if they want deeper |
| Contradictions resolved or explicitly flagged | Cross-reference phase complete |
Never stop prematurely if there are still unexplored questions with available data sources. The goal is thoroughness within the user's topic, not speed.
State File
- Default location:
~/.cache/deep-research/<research-id>.json - Override: When the user says "store intermediate results in /path/to/dir", pass
--state-dir /path/to/dirto allstate.pycommands - Resume: Re-running
state.py initwith the same research-id returns the existing state without overwriting. All subsequent commands append without data loss. - Research ID: Use a slug derived from the research goal (e.g.
quantum-computing-trends-2026). Keep it short and filesystem-safe.
The state file stores accepted research state. It does NOT replace round-level discovery or working-set artifacts.
Working with Other Skills
This skill does NOT fetch data itself. It orchestrates other skills. Execute searches directly — NEVER delegate to Agent().
PATH WARNING: Each skill has its OWN
${CLAUDE_SKILL_DIR}. You MUST read the target skill's SKILL.md before running its scripts — that will give you the correct${CLAUDE_SKILL_DIR}for that skill. NEVER construct paths to other skills' scripts using this skill's${CLAUDE_SKILL_DIR}.
How to invoke another skill's scripts:
- Read the skill's SKILL.md (e.g. read
/duckduckgoSKILL.md) - The SKILL.md will show commands using
${CLAUDE_SKILL_DIR}— that variable resolves to the correct path for THAT skill - Copy the command patterns from that SKILL.md and run them
Workflow:
- Discovery:
discover.pytells you WHAT skills exist and what they can do - Invocation: Read the target skill's SKILL.md to get the correct script commands
- Attribution: When recording sources via
state.py add-sources, set theskillfield
Example routing decisions (read the skill's SKILL.md first for exact commands):
- "Find recent news about X" → read
/duckduckgoSKILL.md → use itssearch.py news - "Get comprehensive coverage" → read
/duckduckgoSKILL.md → use itstop_news.py - "Download full article" → read
/duckduckgoSKILL.md → use itsdownload.py - "Find our internal doc about X" → read
/google-driveSKILL.md → use itssearch.py - "Verify this claim" → read
/duckduckgoSKILL.md → use itsfact_check.py - "Get trending angles" → read
/duckduckgoSKILL.md → use itstrending.py
Context Management
For large research tasks, the context window can fill up. The LLM should:
- Capture early: Broad sweep output goes to discovery artifacts immediately. Do NOT let raw search results sit in the transcript.
- Offload to state/environment:
state.pyis the durable research memory; round artifacts hold the messy local environment for the current pass. - Rebuild from artifacts: When starting a new phase, export
state.pyand reopen only the latest working-set artifacts you need. - Split rounds: Do 3–5 questions per round, persist sources/facts, then move to the next batch. This keeps each round manageable.
- Progressive depth: Start with broad sweeps, then deep-read only the most promising sources. Don't try to download every article.
- Carry compact handoffs only: The next step should usually receive only research id, phase, artifact paths, and a short summary.
json_query.py is the default narrow-reopen tool for JSON artifacts. page_query.py is the default narrow-reopen tool for downloaded markdown/text pages. Prefer them over loading full exported state files or full downloaded pages when you only need a slice.
Large Data — MUST Use --file
When adding questions, sources, or facts, always use your Write tool to create a temp JSON file, then pass --file /path/to/file.json. NEVER use heredoc (<< 'EOF') or cat > in the terminal — these garble output and cause retries. NEVER pass large JSON as inline CLI arguments — shell quoting mangles them.
Pattern (repeat for every state update):
- Use Write tool to create
/tmp/<name>.jsonwith the JSON content - Run
uv run --no-config ... --file /tmp/<name>.json
Affected commands:
add-questions --file /tmp/questions.json— JSON array of question stringsadd-sources --file /tmp/sources.json— JSON array of source objectsadd-facts --file /tmp/facts.json— JSON array of fact objectsupdate-question --file /tmp/uq.json— JSON object{"question": "...", "status": "..."}
# Step 1: Write tool → /tmp/questions.json with content:
# ["What are the key factors?", "How does Y compare to Z?"]
# Step 2: run the script:
uv run --no-config ${CLAUDE_SKILL_DIR}/scripts/state.py add-questions --research-id "my-topic" --file /tmp/questions.json
# Step 1: Write tool → /tmp/facts.json with content:
# [{"claim": "fact 1", "source_ids": ["s1"], "confidence": "high"}]
# Step 2: run the script:
uv run --no-config ${CLAUDE_SKILL_DIR}/scripts/state.py add-facts --research-id "my-topic" --file /tmp/facts.json
Inline --questions/--facts/--sources are only safe for 1–2 very short items. For any batch from a research round, use --file.
Reference
See references/phases.md for detailed phase-by-phase prompt patterns and examples.