Home / All Skills / Docs & Knowledge / research
English (EN)简体中文 (ZH)日本語 (JA)
Docs & Knowledge · mattpocock/skills

research

Investigate a question against high-trust primary sources and capture the findings as a Markdown file in the repo. Use when the user wants a topic researched, docs or API facts gathered, or reading legwork delegated to a background agent.

L2 Local · Restricted workspaceV1 Commit-PinnedWrite FileDual-pass Audit
Author mattpocockGitHub mattpocock/skills ↗Stars 253948License MITCommit 3cca18b368
Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

Implementation principle = pure prompt orchestration + host background agent capabilities, with zero code inside the skill: instructs the primary agent to delegate research to a background agent (asynchronous, without blocking the primary agent), allowing host-provided sub-agents/tools to handle actual reading and file persistence.

skills/engineering/research/SKILL.md
Spin up a **background agent** to do the research, so you keep working while it reads.
The entire skill consists solely of this instruction text. There are no scripts, hooks, or direct calls to specific host APIs—'background agent' is an existing delegation capability provided by the host (Claude Code/Codex, etc.), and the skill simply specifies how to use it.

Source quality discipline is the core mechanism: enforces primary sources (official documentation, source code, specifications, first-party APIs) over secondary interpretations, tracing every claim back to its originating authority—countering hallucinations and secondary distortion via provenance rules.

skills/engineering/research/SKILL.md
Investigate the question against **primary sources** (official docs, source code, specs, first-party APIs), not a secondary write-up of them. Follow every claim back to the source that owns it.
The mechanism here is an applied constraint (bias) rather than automated verification: it does not validate citation authenticity, but requires the agent to trace every assertion back to a primary origin.

The output format is fixed as a 'single Markdown file in the repository + per-claim source citations', capturing research findings as versionable, verifiable repository assets rather than ephemeral conversation summaries.

skills/engineering/research/SKILL.md
Write the findings to a single Markdown file, citing each claim's source.
A single file with citations forms the deliverable contract; there is no rigid structural template, allowing free-form organization.

Placement strategy: prioritizes following existing repository note conventions; if none exist, the agent selects a reasonable location and explicitly informs the user of its path.

skills/engineering/research/SKILL.md
Save it where the repo already keeps such notes; match the existing convention, and if there is none, put it somewhere sensible and say where.
Leaves 'convention discovery and location decision-making' to agent judgment rather than interactively querying the user.

2Core Capabilities

01Asynchronous background research delegation (the primary agent is not blocked and can continue working)
02Primary source prioritization and claim provenance tracing (official documentation/source code/specifications/first-party APIs, rejecting secondary summaries)
03Consolidates findings into a single Markdown file with citations attached to each claim
04Persists files following repository note conventions and reports the saved path (picks a reasonable location and explains if no conventions exist)
05Trigger scope declarations: topic research, documentation/API fact-gathering, delegating extensive reading legwork to a background agent
06Host tool UI self-description (Codex/OpenAI-ecosystem display_name + short_description)

4Recommended Governance & Evidence

Suggested Controls for Safe Operation
For Agent Runtime
Restrict working directory
For Administrators
Retain operation logs
Evidence & Triggers (File Paths & Excerpts)
  • 本地工作目录: File read/write & artifact generation: A single Markdown research note file within the repository (written by the host agent; follows repository note conventions by default, or is placed at a reasonable agent-selected path disclosed to the user).
Audit Notes: The entire directory contains only 2 text files (SKILL.md 794B + agents/openai.yaml 94B; verified via git ls-files and find with no scripts, hidden files, or symlinks), and verbatim inspection confirms no network endpoints, credential access, or embedded executable content. The sole 'action' is instructing the model to write a single Markdown note file into the user's repository (the deliverable itself, executed under host permission constraints). Being pure prompt orchestration, it aligns with the classification criteria of identical skills in the same repository batch (e.g., grill-with-docs: pure instructions + internal project doc writing, also evaluated as green).

5Second-Pass Verification

  • [ok] 目录内容仅 SKILL.md + agents/openai.yaml 两个文件（无脚本/附属代码） — git ls-files skills/engineering/research 仅列出两文件；find -type l 为 0；ls -la 无隐藏条目——与第一遍一致
  • [ok] 实现依赖'宿主后台 agent 能力'而非内置机制 — git show 复核 SKILL.md 全文仅 794B 指令文本，无任何对具体宿主 API/工具名的调用代码，'background agent' 确为宿主既有能力
  • [ok] 一手信源优先 + claim 回溯规则存在且为 skill 核心 — 复核到 SKILL.md 正文步骤 1 原文：'Investigate the question against **primary sources** … Follow every claim back to the source that owns it.'
  • [ok] 引用纪律（逐 claim 标注来源） — 复核到步骤 2：'Write the findings to a single Markdown file, citing each claim's source.'
  • [ok] 仓库约定落盘 + 无约定自选并告知 — 复核到步骤 3 原文 'Save it where the repo already keeps such notes; match the existing convention…'
  • [ok] agents/openai.yaml 仅界面元数据、无行为 — git show 复核 94B，仅 interface.display_name/short_description 两字段
  • [ok] external_deps 为空（无 CLI/API/网络端点/第三方包） — 两文件全文逐词复查：无 URL、无域名、无命令行、无包名、无环境变量引用；'official docs, source code, specs, first-party APIs' 只是信源类型描述，非调用点
  • [ok] 安全分级 green（无脚本/无网络外发/无凭证/无隐藏内容） — 找反例未果：无 .sh/.py/可执行位文件、无 fetch/curl 字样、无 key/token/env 字样；唯一写入为交付用的仓库 Markdown（宿主动作）。与同批纯指令型 skill 分级口径一致

6Verdict & Scenarios

  • Asynchronous delegation ensures the primary agent is never blocked by research tasks
  • Source quality discipline is built directly into instructions, mitigating secondary distortion and hallucinated citations
  • Mandatory citations ensure outputs remain fully verifiable
  • Outputs serve as long-term repository assets aligned with existing repository note conventions
  • Zero dependencies and zero code ensure exceptional host portability
    • Best for: Scenarios where reading documentation, looking up API facts, or conducting research needs to be delegated and persisted as verifiable repository notes; particularly suited for repositories with existing notes/docs directory conventions when the primary agent needs to perform other tasks in parallel.
    Not for: Scenarios requiring rigid formats, structured templates, or strict length limits (the skill imposes no layout contract); interactive, multi-turn deep investigations needing real-time oversight (background agent progress is opaque); contexts involving adversarial or sensitive information where citations cannot be verified by humans.
    Install Agent-Ready
    ① Verified Mirror 2026-09-06
    Option A · Direct DownloadDownload research.tar.gz
    sha256: b3019d041dd6a97f…
    Option B · Copy Guide for Agent
    install.json
    Agents automatically download and verify mirrors from this JSON guide.
    ② Upstream GitHub
    GitHub Repo ↗
    Pinned to commit 3cca18b368.