- name
SKILL.md
スキルファイルは公開元のリポジトリに置かれたままです。
コピーしたコマンドをターミナルに貼り付けてください。この SKILL.md がそのエージェントにインストールされます。
npx skills add omagents/omagents --skill deep-research -a cursor -yコピーしたコマンドをターミナルに貼り付けてください。この SKILL.md がそのエージェントにインストールされます。
npx skills add omagents/omagents --skill deep-research -a claude-code -yコピーしたコマンドをターミナルに貼り付けてください。この SKILL.md がそのエージェントにインストールされます。
npx skills add omagents/omagents --skill deep-research -a codex -yコピーしたコマンドをターミナルに貼り付けてください。この SKILL.md がそのエージェントにインストールされます。
npx skills add omagents/omagents --skill deep-research -a grok -yコピーしたメッセージを Grok Bot のチャットで送信してください。Bot がこの SKILL.md を GitHub から取得し、すべての Bot が共有するスキルに追加します。
Install this skill: https://github.com/omagents/omagents/tree/HEAD/packages/core/skills/deep-research公開元より
Conduct iterative, multi-source research and produce a high-quality Markdown report.
This skill combines the structured items × fields approach (inspired by RhinoInsight and Weizhena's Deep Research skills) with the dynamic gap-detection loop from LangChain's Open Deep Research, while staying native to OpenCode's subagent and MCP infrastructure.
Loop Engine: Research task state is managed by the shared loop_engine.py (see packages/core/skills/_shared/scripts/loop_engine.py). This provides durable state that survives context clearing, retry logic, and a unified summary across all loop-based skills.
jinja2 (install via the agents-python-tools skill)Under the hood these commands map to:
deep_research.py <subcommand> --workspace <workspace>
New subcommands: audit, package, provenance, status, polish, run-all, scan, scan-next, scan-complete, scan-evaluate, scan-finalize.
--workspace is the public deliverable directory. It contains only files intended for the user: report.md, optional summary.md, promoted topic-specific documents, and the generated README.md index. A new run is rejected before writing if its workspace would contain the internal run or loop store (including the default project-root workspace); select a separate child workspace such as research/topic. Genuine legacy workspaces at the project root remain supported.
Every new run stores its internal files under .omagents/deep-research/<run-id>/ in the project root (the directory from which the CLI is invoked). The run ID is <slug>-<digest>. For the digest input, resolve the workspace to an absolute path, take its path relative to the resolved project root when possible (otherwise use the absolute path), and encode it with POSIX separators; hash that UTF-8 string with SHA-256 and take the first eight lowercase hex characters. The slug uses NFKD normalization, removes non-ASCII characters, lowercases the result, and replaces non-alphanumeric runs with hyphens (research is the fallback), so the ID is stable across project relocation and distinct for same-named workspaces in different directories. The dispatch JSON supplies absolute findings_dir and pre_findings_dir paths; agents MUST use those paths instead of reconstructing paths from --workspace. Each search also supplies output_path, output_path_quoted, and shell (posix or powershell). Use the quoted value in shell commands and the structured resume_command argv when bypassing a shell.
plan.json, pre_research.json, optional pre_research_curated.json, findings/, and pre_findings/ are durable research inputs/evidence.state/ contains resume checkpoints. Loop queues use deep-research-<run-id> and deep-research-pre-<run-id> under the existing .omagents/loops/ store.artifacts/ contains rebuildable derived files; they are retained by default, not treated as disposable cache.logs/provenance.jsonl is the single append-only provenance log.artifacts/. To promote one, write the finished document to <workspace>/<name>.md while leaving the draft in place; the next package command indexes it automatically without rewriting its content.Existing legacy workspaces remain in their original layout and use the original unnamespaced loop keys. They are read and resumed without automatic migration or deletion.
CRITICAL: Before generating any plan, a pre-research landscape scan MUST run. This ensures research items are based on current, real-world data rather than potentially outdated model knowledge.
The pre-research phase uses the loop engine (skill key: deep-research-pre-<run-id> for new runs; deep-research-pre only for legacy workspaces) to iteratively scan the web for current entities. The current date is automatically injected into all task descriptions and search instructions to ensure the agent searches for the most recent information.
pre_research.py init --query "..." --workspace <dir> creates a broad search task. Task description includes the current date (e.g., "Current date: July 2026").output_path supplied by the orchestrator, using output_path_quoted in shell commands.pre_research.py evaluate checks if enough candidates/sources found. If not, adds targeted search tasks (also date-injected).max_pre_research_loops (default 2) is reached.pre_research.py finalize merges all pre-findings into <run-dir>/pre_research.json.pre_research.json format:
{
"query": "current top LLMs",
"scanned_at": "2025-07-10T...",
"summary": "Brief landscape overview",
"candidates": [
{"name": "DeepSeek-V4", "vendor": "DeepSeek", "note": "...", "source": "https://..."},
{"name": "Kimi K2", "vendor": "Moonshot AI", "note": "...", "source": "https://..."}
],
"sources": ["https://..."],
"loops_completed": 2
}
This internal file feeds directly into Phase 1 to generate items from real candidates. Pre-research checkpoints live at <run-dir>/state/pre_research_state.json.
/research <topic>)Generate an internal <run-dir>/plan.json with:
query: original questionitems: list of research objects (auto-populated from pre_research.json if available)fields: dimensions to collect for each item (template-aware: comparison gets version/strengths/weaknesses, technical gets architecture/API)tasks: parallel research tasks covering ALL items x fields (not just the first item)config: max loops, batch size, search tools, confidence weights, audit weights, etc.Example:
deep_research.py plan \
--query "AI agent frameworks" \
--template comparison \
--workspace agent-frameworks
If pre_research.json exists in the internal run directory, items are automatically generated from its candidates. You can also explicitly pass --pre-research <path>, including an earlier run's file for deliberate reuse.
Config overrides:
deep_research.py plan \
--query "..." \
--template comparison \
--max-loops 3 \
--batch-size 5 \
--search-tools websearch,github \
--language zh \
--workspace agent-frameworks
--workspaceis the public deliverable directory name. Use a slug of the research topic (lowercase, hyphenated, e.g. "AI Agent Frameworks" ->ai-agent-frameworks). It is created in the current working directory; plans and other internal files go to the resolved.omagents/deep-research/<run-id>/directory instead.
For a new run, the orchestrator initializes the run-specific loop engine automatically. Advanced manual workflows use the run ID from the internal run directory:
After generating the plan, initialize the loop engine with the research tasks:
loop_engine.py init deep-research-<run-id> '[
{"task_id": "task-1", "type": "web", "item_id": "item-1", "field_ids": ["field-1"], "focus": "...", "description": "Research LangGraph overview"},
{"task_id": "task-2", "type": "github", "item_id": "item-2", "field_ids": ["field-2"], "focus": "...", "description": "Research AutoGPT license"}
]'
/research-add-items, /research-add-fields)Review the generated plan. If items or fields are missing, add them:
deep_research.py add-items \
--workspace agent-frameworks \
--items-json '[{"name":"LangGraph","type":"framework","description":"LangChain agent framework"}]'
deep_research.py add-fields \
--workspace agent-frameworks \
--fields-json '[{"name":"License","category":"Legal","description":"Software license","required":false}]'
/research-deep)Managed by the loop engine. Get the next pending task, dispatch it as a subagent, and mark complete when done.
Step 1: Get next task
loop_engine.py next deep-research-<run-id>
If output is null, proceed to Phase 4 (gap detection).
Step 2: Dispatch subagent
For each task returned, launch a subagent using task(background: true). Multiple task calls in one response execute simultaneously. Each subagent:
field_data keyed by field IDs.{findings_dir}/<task_id>.json from dispatch JSON using bash (e.g. cat > <path> << 'EOF' ... EOF), not the write tool — subagent sessions run in a temporary working directory, so the write tool may trigger a confirmation dialog for paths outside it.Do not wait for all subagents to return before proceeding. Background task completions are automatically injected via the Background Job Board. When all tasks are done, proceed to Phase 4.
You are a web research specialist. Research the following item and collect the specified fields.
Current date: {current_date}
IMPORTANT: Include the current year ({current_year}) in your search queries. Do NOT rely on your training data - it may be outdated. Search for the most recent sources available.
Item: {item_name}
Description: {item_description}
Fields to collect:
{for each field: "- {field_name} ({field_category}): {field_description} [required: {required}]"}
Focus: {task_focus}
Workspace: {workspace}
Run ID: {run_id}
Findings directory: {findings_dir}
Output path: {task.output_path}
Shell-quoted output path: {task.output_path_quoted}
Shell: {shell}
Instructions:
1. Use websearch_web_search_exa to find relevant sources. Include the current year in queries.
2. For each promising source, use webfetch to read it.
3. Extract data for EACH field listed above.
4. Mark uncertain values with [uncertain].
5. If information is missing or contradictory, do additional targeted searches (up to 3 iterations).
6. For each finding, record the publication date if available.
7. Write findings to {task.output_path}. IMPORTANT: Use {task.output_path_quoted}
as the destination in a command for the supplied {shell} (for POSIX, e.g.
`cat > {task.output_path_quoted} << 'ENDOFFILE' ... ENDOFILE`) instead of the
`write` tool - subagent sessions run in a temporary directory, so the `write`
tool may trigger a confirmation dialog for paths outside it.
Use this JSON schema:
{
"type": "web",
"task_id": "{task_id}",
"item_id": "{item_id}",
"field_ids": [{field_ids}],
"focus": "{task_focus}",
"iteration": {iteration},
"findings": [
{
"source": "URL",
"title": "...",
"published_date": "YYYY-MM-DD or null",
"field_data": { "field-1": "data", "field-2": "data" },
"summary": "...",
"key_quotes": ["..."],
"relevance": "high|medium|low",
"uncertain": false
}
],
"gaps": ["..."]
}
8. Validate through the unified CLI so it resolves the same internal paths.
Use the supplied shell-quoted workspace value:
deep_research.py validate --task-id {task_id} --workspace {workspace_quoted}
GitHub and codebase subagents follow the same structure but use their respective tools.
Step 3: Mark task complete
When a subagent finishes and its findings are written and validated:
loop_engine.py complete deep-research-<run-id> <id> "Found 5 sources, coverage: high"
If the subagent fails (no findings, validation error):
loop_engine.py fail deep-research-<run-id> <id> "No web sources found for this item"
Step 4: Loop
Repeat from Step 1. When next returns null, all initial tasks are done. Proceed to Phase 4.
Step 1: Run gap analysis
deep_research.py gaps --workspace agent-frameworks
This builds an item x field coverage matrix, identifies missing or low-confidence coverage, and outputs <run-dir>/artifacts/gap_report.json with new_tasks and should_continue.
Step 2: Add gap tasks to loop engine
If should_continue is true, add each new task from the gap report:
loop_engine.py add deep-research-<run-id> '{"task_id": "task-r1-1", "type": "web", "item_id": "item-1", "field_ids": ["field-2"], "focus": "Supplemental research for LangGraph on field License", "description": "Gap fill: LangGraph License"}'
Step 3: Loop back to Phase 3
Return to Phase 3 to execute the new gap-fill tasks. The loop continues until:
next returns null (all tasks complete), ANDshould_continue is false (no more gaps or max_research_loops reached)Step 4: Check final status
loop_engine.py summary deep-research-<run-id>
When the loop is complete, proceed to Phase 5.
/research-report)deep_research.py merge --workspace agent-frameworks
deep_research.py report --workspace agent-frameworks
This produces report.md using the selected Jinja2 template (survey, comparison, or technical).
/research-polish)The template-generated report is mechanically assembled and may feel stiff. This phase uses the LLM (the agent itself) to rewrite it into coherent prose.
deep_research.py report --polish --workspace agent-frameworks
# or standalone:
deep_research.py polish --workspace agent-frameworks
This will:
--polish is used with report)<run-dir>/artifacts/report_raw.mdThe agent then:
report_raw.md and the plan contextprompts/polish_report.md for instructionsreport.md (overwrite)In the run-all pipeline, this phase pauses automatically — the agent polishes, then resumes with run-all --resume.
{
"version": 2,
"query": "AI agent frameworks",
"context": "",
"template": "comparison",
"objectives": ["..."],
"items": [
{
"id": "item-1",
"name": "LangGraph",
"type": "framework",
"description": "LangChain's agent framework"
}
],
"fields": [
{
"id": "field-1",
"name": "Overview",
"category": "General",
"description": "General description",
"required": true,
"detail_level": "moderate"
}
],
"tasks": [
{
"id": "task-1",
"type": "web",
"item_id": "item-1",
"field_ids": ["field-1"],
"focus": "...",
"status": "pending",
"iteration": 0
}
],
"config": {
"max_research_loops": 2,
"batch_size": 3,
"items_per_agent": 1,
"search_tools": ["websearch", "github", "codegraph"],
"report_sections": ["executive_summary", "comparison_table", "detailed_findings", "cross_cutting_insights", "gaps", "sources"],
"language": "auto",
"max_pre_research_loops": 2,
"min_pre_research_candidates": 5,
"min_pre_research_sources": 3,
"confidence_weights": {"source_count_high": 2, "relevance_high": 3, "cross_source_bonus": 1},
"audit_weights": {"info": 0, "warning": 5, "error": 15, "critical": 30}
},
"metadata": {
"created_at": "...",
"updated_at": "...",
"research_loops_completed": 0
}
}
{
"type": "web",
"task_id": "task-1",
"item_id": "item-1",
"field_ids": ["field-1", "field-2"],
"focus": "...",
"iteration": 0,
"findings": [
{
"source": "URL",
"title": "...",
"published_date": "YYYY-MM-DD or null",
"field_data": { "field-1": "data", "field-2": "data" },
"summary": "...",
"key_quotes": ["..."],
"relevance": "high",
"uncertain": false
}
],
"gaps": ["..."]
}
{
"loop": 1,
"coverage_matrix": { "item-1": { "field-1": { "covered": true, "sources": 2, "confidence": "high" } } },
"overall_coverage": 0.75,
"gaps": [
{ "item_id": "item-1", "field_id": "field-2", "reason": "no_findings", "severity": "high" }
],
"new_tasks": [ { "id": "task-r1-1", "type": "github", "item_id": "item-1", "field_ids": ["field-2"], ... } ],
"should_continue": true
}
Templates live in templates/:
survey.md.tmpl — general research reportcomparison.md.tmpl — side-by-side comparisontechnical.md.tmpl — architecture/implementation analysisTo use a template, set plan.template to survey, comparison, or technical.
The final report.md includes:
The report includes inline SVG charts (rendered by scripts/svg_charts.py):
SVG is embedded directly in Markdown. No external dependencies or JavaScript.
Every new research run tracks phase-level events in <run-dir>/logs/provenance.jsonl. Legacy root and artifacts/ logs are combined when read:
View with: deep_research.py provenance --workspace <dir>
Provenance is optional and backward-compatible. Old workspaces without provenance simply omit timeline charts.
Run automated checks on research findings:
deep_research.py audit --workspace agent-frameworks
Output: <run-dir>/artifacts/audit_report.json with overall score (0-100) and recommendations. Results are also embedded in the Markdown report.
Generate a complete package manifest:
deep_research.py package --workspace agent-frameworks
Produces:
<run-dir>/artifacts/package.json - machine manifest with metadata, internal file list, and stats<workspace>/README.md - human index containing only public deliverables (legacy workspaces keep artifacts/README.md)New-run storage structure:
<project>/
<workspace>/ # Public deliverables only
report.md # Polished report (Markdown + SVG)
summary.md # Optional executive summary
README.md # Public deliverable index
execution_roadmap.md # Optional promoted custom deliverable
tco_model.md # Optional promoted custom deliverable
.omagents/
deep-research/<run-id>/
plan.json # Research definition
pre_research.json # Consolidated pre-research input
pre_research_curated.json # Optional curated input
pre_findings/ # Raw pre-research evidence
findings/ # Raw research evidence
artifacts/ # Derived files; retained by default
findings_merged.json
gap_report.json
audit_report.json
report_raw.md
package.json
state/
orchestration_state.json
pre_research_state.json
logs/
provenance.jsonl
loops/
deep-research-<run-id>/tasks.json
deep-research-pre-<run-id>/tasks.json
Run the full pipeline with pause/resume:
# First run
deep_research.py run-all --query "AI agent frameworks" --template comparison --workspace agent-frameworks
# After subagents complete
deep_research.py run-all --resume --workspace agent-frameworks
The orchestrator (orchestrate.py) is a pausable state machine:
batch_size tasks at once) for the agent to dispatch subagents (pauses)The agent calls --resume after subagents complete. The state machine picks up from where it left off via <run-dir>/state/orchestration_state.json. Resume from the same project root and workspace; if no checkpoint exists, the command fails instead of silently creating a replacement run.
To skip pre-research (not recommended): --skip-pre-research
Check status: deep_research.py status --workspace <dir>
task(background: true). The orchestrator dispatches up to batch_size tasks at once.[uncertain] so the gap analyzer can flag them.--template comparison for side-by-side comparisons (gets version/strengths/weaknesses fields automatically).--template technical for architecture analysis (gets architecture/API/performance fields automatically).Run a multi-source, iterative deep research workflow using structured items × fields and produce a Markdown report.
---name: deep-researchdescription: Run a multi-source, iterative deep research workflow using structured items × fields and produce a Markdown…---# packages/core/skills/deep-research/SKILL.mdよくある質問
公開元から packages/core/skills/deep-research/SKILL.md をダウンロードするか、パスをコピーしてリポジトリを開いてください。PlugMCP はスキルを掲載するだけで、ファイルはホストしていません。
公開元は https://github.com/omagents/omagents で管理しています。
Claude、Cursor、Codex、Grok Build は、公開元のリポジトリから追加した SKILL.md を読み込めます。Grok Bot は、チャットでスキルの GitHub フォルダーのリンクを送るとインストールします。