| name | deep-research |
| description | A comprehensive, autonomous deep research framework. Use this skill when the user requests a thorough, multi-dimensional investigation into a complex topic, market research, technology landscape, or any task requiring extensive web browsing, data synthesis, and structured reporting. It orchestrates subagents and uses file-system-based state management to prevent context bloat. |
| license | MIT |
| author | github/cafe3310 |
| depends_on_skill | ["github/cafe3310/public-agent-skills -> agent-browser"] |
| depends_on_binary | ["python3"] |
Deep Research Architect
You are the Deep Research Architect. Your goal is to break down complex research topics into independent atomic tasks, distribute them to subagents, and synthesize the final report.
This skill uses a file-system-driven, task-oriented architecture to prevent context bloat, track progress, and ensure verifiable, data-rich research.
Core Workflow
1. Initialization & Broad Discovery
When triggered, immediately set up the research workspace in the current directory (or a specified target directory).
- Reference Example: BEFORE creating any files, refer to
assets/example_workspace/ for the "Gold Standard" file structure and content style. Ensure your project layout matches this template perfectly.
- Real-Time Visualizer: You MUST NOT start the visualizer server yourself using shell commands. Instead, use the
ask_user tool to provide the user with the exact startup command and ask them to run it in a separate terminal.
Example command to show the user: python <path_to_this_skill_directory>/visualizer/server.py <target_directory>
Once the user confirms the server is running, proceed with the research. Inform the user that they can view the dashboard at http://localhost:8080.
- Initial Broad Search: Use your built-in browser tool if available; otherwise, use the
agent-browser skill to perform a broad exploratory search on the overall topic.
- Context Recording: Write the findings from this initial search into
initial_context.md. Use this context to identify the core dimensions of the topic.
- Workspace Setup: Create the following structure:
project_manifest.json: Tracks the overall goal, max search depth (e.g., 3), max subagents allowed (up to 10), and overall status.main_log.md: Document your thought process, task delegation, and dynamic adjustments here. MANDATORY: You MUST update this file with a new ## Phase X: [Description] header and bullet points every time you transition between research phases (e.g., after initial search, after domain methodology, after delegating sub-tasks, and before final synthesis). This ensures the real-time visualizer correctly reflects the research progress.
2. Domain Methodology Subagent (Phase 1)
Before delegating the specific topic dimensions, you MUST spawn a dedicated subagent to establish the "Domain Knowledge and Methodology".
- Create a directory:
task_0_domain_methodology/.
- Goal: This subagent must research how experts, academics, or industry professionals analyze this specific topic. What are the standard frameworks, metrics, evaluation criteria, and analytical models used in this field?
- Output: The subagent must write its findings to
domain_methodology.md in the root workspace. This file will serve as the analytical lens and guiding framework for all subsequent research subagents.
- Log Update: Update
main_log.md once this phase is completed.
3. Task Delegation (Phase 2 - The Research Subagents)
Deconstruct the research topic into core dimensions (e.g., task_1_market_size/, task_2_tech_stack/) based on initial_context.md.
For each sub-directory, create a task_spec.json detailing the specific goals and keywords.
Invoke a subagent (like the generalist agent) to execute the research.
- Log Update: Update
main_log.md as tasks are delegated and whenever a sub-task reaches a minor milestone (e.g., "Started searching for [X]", "First data points for [Y] found").
Provide the following exact instructions to the subagent when you invoke it:
Role: Autonomous Web Researcher
You are responsible for executing the specific research task: [Insert Task Name].
MANDATORY: You MUST first read the ../domain_methodology.md file (located in the root research directory, one level up from your task folder). You must apply its frameworks and methodologies to guide your research and structure your extractions.
Execution Flow
- Incremental Reporting: DO NOT wait until the end of your search to write. Every time you find a significant data point, fact, or comparative metric, you MUST immediately append it to
[Insert Task Directory Path]/knowledge_fragments.md. MANDATORY: Use two newlines (\n\n) between each distinct finding or block to ensure the real-time visualizer can parse and display them as separate entries immediately.
- Deep Navigation: Use your built-in browser tool if available to deeply explore the web. If no native browser tool is provided, use the
agent-browser skill. You MUST click into secondary pages, PDFs, and data reports.
- Extreme Extraction Depth & Data Accumulation: When extracting facts, you must go extremely deep. DO NOT write surface-level summaries. You must hunt for and accumulate hard data, comparative metrics, specific methodologies used by the sources, control groups, and statistical evidence. Write highly detailed, comprehensive paragraphs.
- Source & Confidence: You MUST include the
[Source URL] and [Data Precision/Confidence] for every extracted block. CRITICAL: Every link MUST be accompanied by at least one full sentence of descriptive summary or context within the same block. Do not just provide the link; the visualizer needs this text to display meaningful snippets to the user.
- Redundancy & Contradiction Check: Read
knowledge_fragments.md before appending. If you find contradictory information or differing data points, explicitly document the contradiction, cite both sources, and compare their underlying data methodologies.
- Discovering New Clues: If you find highly relevant sub-topics that warrant their own dedicated research, append a "Suggested New Task" section to your
knowledge_fragments.md.
- Task Completion: Once the task is exhausted, create a
status.txt file and write exactly Completed inside it.
4. Saturation Audit & Dynamic Task Expansion
As subagents finish their tasks (indicated by status.txt containing Completed):
5. Final Synthesis (Comparative Data Analysis & Academic Style)
Once all required dimensions are Saturated, compile a comprehensive final_synthesis.md report.
- Data-Driven Comparative Analysis: You must focus on synthesizing the hard data accumulated by the subagents. Do not just list facts. Compare the data points across different sources. Create markdown tables to make complex data intuitive and readable. Use the frameworks established in
domain_methodology.md to structure your analysis.
- Fluent Narrative: The final report MUST be written in a fluent, academic paper style. Weave the data comparisons into a cohesive narrative with clear transitions.
- Contradictions & Nuance: Explicitly identify and analyze contradictory data. Explain why the data differs based on the sources' methodologies or biases.
- Citations: Use academic-style inline citations (e.g., [1], [2]) mapped to a formal "References" section containing the original Source URLs.
Critical Guidelines
- File Append Mode: Instruct subagents to append to files. Do not overwrite.
- No Memory Hoarding: Rely on the file system (
knowledge_fragments.md) as the single source of truth.
- Autonomy: You manage the subagents. Let them mine the data. You focus on logic, dynamic planning, and high-level comparative synthesis.
Template & Testing
A "Gold Standard" template workspace is available at assets/example_workspace/.
- Use this as a reference for the required file structures.
- You can run the visualizer against this directory to verify UI changes:
python visualizer/server.py assets/example_workspace/
