# Tech Topic Research

> >

- **Type:** Skill
- **Install:** `agentstack add skill-85danf-agent-skills-tech-topic-research`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [85danf](https://agentstack.voostack.com/s/85danf)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [85danf](https://github.com/85danf)
- **Source:** https://github.com/85danf/agent-skills/tree/master/claude/skills/tech-topic-research/tech-topic-research

## Install

```sh
agentstack add skill-85danf-agent-skills-tech-topic-research
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Deep Research

Teach or evaluate a topic through progressive disclosure. Deliver a useful gist
within seconds, then deepen the answer with parallel web research and a written
study guide when the user wants more.

## When to use this skill

Use this skill when the user explicitly invokes it with a topic, or when the
user asks to:

- Learn about, understand, or evaluate a technology, tool, framework, library,
  service, concept, or methodology.
- Compare two or more such items ("X vs Y", "X or Y for {use case}",
  "compared to Z").
- Decide whether to adopt a tool, prepare for an interview on a topic, build a
  mental model, or get a curated reading list.

**This skill is invoked only by explicit user request — never autonomously.** The frontmatter flag `disable-model-invocation: true` blocks auto-matching; hosts that don't honor it MUST still refuse without an explicit user request. Explicit invocation is consent to _consider_ running the skill; the [Token cost and approval gate](#token-cost-and-approval-gate) (Phase 1 step 5) still applies.

## When NOT to use this skill

Skip this skill — it is the wrong tool — when:

- The user wants a single-fact lookup ("what version of X ships JSONB?", "who
  is the CEO of Y?"). One WebSearch call answers it.
- The user is debugging a specific error and wants a fix. Use a debugging
  workflow, not a research one.
- The user wants a quick sanity check or a yes/no answer.
- The user already has a clear opinion and just wants confirmation.
- The user explicitly asks for "a quick answer" or "in one sentence".

If you are not sure whether the request is research or a lookup, default to
the lookup — research is opt-in, see the next section.

## Token cost and approval gate

> ⚠️ **This skill is heavy on token usage.** A Standard run spawns four
> parallel haiku subagents, each issuing 4–6 web searches and several
> WebFetch calls. A Deep run adds an Opus subagent and a Sonnet reviewer.
> Total cost is typically **5–30× a normal turn**, and the subagent fan-out
> cannot be cancelled mid-flight.

### Estimated cost per run

| Tier                  | Subagents                                                | Typical token cost     | Typical wall-clock |
| --------------------- | -------------------------------------------------------- | ---------------------- | ------------------ |
| **Quick**             | 0 (gist only)                                            | ~1× a normal turn      | /summaries/.md` siblings (Phase 6 with >8 sources); fresh approval is unsupported. Subagent fan-out requires user confirmation via the Token cost gate.

## Prerequisites

1. The host runtime exposes the tools listed in `compatibility:` above. If
   `Task` / `run_in_background` is unavailable, the skill falls back to
   sequential WebSearch from the main agent (Quick depth only).
2. The user has supplied a topic. If not, ask for one before any web search.
3. No configuration file or credentials are required.

## Configuration

This skill has no separate config file. All knobs are inputs collected during
the workflow: topic, depth tier, familiarity level, goal, and focus areas.

## Pre-flight checks

No script-based preflight is required because the skill calls only host-provided
tools. Before starting Phase 1, confirm in this order:

1. A topic is present. If not, ask the user for one.
2. The host advertises WebSearch and WebFetch. If neither is available, stop
   and report that deep research cannot run on this host.
3. The host advertises the Task tool with native subagent registration (each
   `agents/.md` is registered as `subagent_type: ""`) and
   `run_in_background`. If not, restrict the run to **Quick depth** (gist
   only) and tell the user why.

## Skill Directory

Supporting files split across two locations:

- `agents/.md` lives at the **plugin root**
  (`plugins/tech-topic-research/agents/`) — required so Claude Code registers
  them as native subagents (`subagent_type: ""`). The body is
  the spawned subagent's full system prompt; no paste at fan-out.
- `references/` (alongside this SKILL.md) — search strategies, teaching
  tone, analysis tools, source-quality tiers, comparison-mode rules,
  synthesis engine.
- `assets/` (alongside this SKILL.md) — output and plan templates.

## Workflow

Always follow this sequence. Never skip Phase 1 or Phase 2 — Phase 1 informs
the questions Phase 2 asks.

### Phase 0 — Topic input

Parse the topic from the user's message.

- If no topic was provided, ask for one and stop.
- If two or more named items appear with `vs`, `versus`, `compared to`, or `or`
  between them, confirm comparison mode before proceeding.

### Phase 1 — Preliminary assessment and gist

**Main agent only. No subagents.** This phase runs **before** any clarifying
questions.

1. **Step 1: Anchor the current date.** Before any WebSearch, retrieve today's
   date with `date +%Y-%m-%d` (host shell). If Bash is unavailable, read it
   from the host's system message. Otherwise **ask the user** — never guess
   from training data. Save as `{current_date}` and `{current_year}`; pass
   them into per-call subagent prompts that need a freshness anchor.
2. **Get a current overview from the live web. Mandatory — never
   gist from training data alone.** Try main-agent WebSearch; if it
   returns "tool not available", spawn one `docs-searcher` subagent
   in gist mode (`Mode: gist` → 5-bullet gist, +1 haiku, footnote ¹).
   If both fail, stop and tell the user the host has neither live-web
   nor `docs-searcher`. Do NOT fall back to training data.
3. Deliver the gist conversationally:
   - **What it is** — 2–3 sentences.
   - **Why it matters** — the problem it solves.
   - **Where it fits** — ecosystem context.
   - **Mental model** — one analogy ("Think of it as…").
   - **Confidence:** HIGH / MEDIUM / LOW based on how much the WebSearch
     results agreed with each other and how recent they were
     (see [`references/analysis-tools.md`](references/analysis-tools.md)
     Confidence Criteria for definitions).
4. Internally note the key dimensions Phase 2 will offer as focus-area
   options: main subtopics, recent developments or controversies, common use
   cases, related/competing technologies.
5. **Stop. Run the [token-cost approval gate](#token-cost-and-approval-gate)**
   — render the cost table (Step A), then the gate (Step B). Do not proceed to
   Phase 2 until the user has explicitly picked Standard, Deep, or stop.

**Comparison mode (Phase 1):** see [`references/comparison-mode.md`](references/comparison-mode.md).

### Phase 2 — Informed clarification

Phase 2 only runs after the user picked **Standard** or **Deep** at the
[token-cost approval gate](#token-cost-and-approval-gate) (Phase 1 step 5).
If the user picked "stop", the gist is the final answer — do not run Phase 2.

Depth is already established by the gate. Use `AskUserQuestion` (or the
host's equivalent) for the three remaining questions, informed by Phase 1:

1. **Familiarity**: new to this / heard of it / tried it / use it regularly.
2. **Goal**: evaluate for adoption / learn to use / understand concepts /
   prepare for interview.
3. **Focus areas** (multi-select; options derived from the Phase 1 dimensions).

**Comparison mode (Phase 2):** see [`references/comparison-mode.md`](references/comparison-mode.md).

### Phase 3 — Research plan and subagent fan-out

1. Formulate the plan from the gist plus the user's answers. Use the
   skeleton in
   [`assets/research-plan-template.md`](assets/research-plan-template.md).
   Show the filled plan to the user before fanning out — if the user
   redirects (different focus, narrower scope, new angle), update the plan
   and confirm before any subagent is spawned. **When filling the plan,
   explicitly initialize `refinement_state.used = false`,
   `refinement_state.what = ""`, `refinement_state.subagents_added = []`.
   This reset is mandatory before fan-out.**
2. Read `references/teaching-tone.md` and use it to shape the explanation
   style.
3. Spawn subagents. **All in a single message**, all with
   `run_in_background: true`, so they run in parallel.

**Standard depth** spawns four searcher subagents (haiku): `agents/docs-searcher.md` (`subagent_type: "docs-searcher"`), `agents/community-searcher.md` (`"community-searcher"`), `agents/tutorial-searcher.md` (`"tutorial-searcher"`), `agents/integration-searcher.md` (`"integration-searcher"`).

**Deep depth** adds `agents/deep-analyst.md` (`"deep-analyst"`, opus, always) and `agents/comparison-searcher.md` (`"comparison-searcher"`, haiku, when alternatives are a focus area or always in comparison mode).

**Comparison mode** doubles each searcher pool — spawn each role **twice**, once per item. The `comparison-searcher` is single-instance and receives both items. See [`references/comparison-mode.md`](references/comparison-mode.md) for equal-treatment rules.

### Subagent invocation pattern (native registration)

Each `agents/.md` is a registered Claude Code subagent. Spawn via Task tool with `subagent_type: ""`; the role body becomes the spawned subagent's system prompt — no paste step. The worker reads its assignment from `prompt:` and loads canonical references via `Read`.

```text
Task tool parameters:
  subagent_type: "docs-searcher"   # from agents/.md frontmatter
  description: "docs-searcher for {topic}"
  run_in_background: true
  prompt: |
    Topic: {topic}
    Focus areas: {focus_areas}
    Gist summary: {gist_summary}
    User familiarity: {familiarity}
    User goal: {goal}
```

Do not pass `model:` or paste the role body — both come from `agents/.md`. For `comparison-searcher`, the topic field carries both items plus a `comparison_mode: true` line. Spawn the wave in one multi-tool message. Structured output envelope contract canonical in [`references/output-envelope.md`](references/output-envelope.md); spawned subagents `Read` it themselves.

While subagents run, draft Phase 4 from your own knowledge plus Phase 1 findings.

#### First-finish-search early exit

Do not block waiting for the slowest subagent. As soon as you have:

- For Standard: docs-searcher **and** community-searcher **and** tutorial-searcher **and** integration-searcher results.
- For Deep: the above plus deep-analyst results.

…proceed to Phase 4 even if a refinement-loop subagent (see below) is still running. Its results merge into Phase 5 / Phase 6 as it finishes.

In **comparison mode**, the FFS rule applies **per item**: each item must have all four searcher results before Phase 4 starts. If item A is complete and item B is not, do not start Phase 4.

If any required subagent has not returned by its timeout (see "Timeout thresholds" below), the run fails. Tell the user explicitly which role timed out and stop. Do not synthesize on incomplete data.

**Deep tier deep-analyst exception.** **This exception overrides the preceding fail-on-timeout rule for the `deep-analyst` role only.** If `deep-analyst` (Opus) has not returned by its 25-minute timeout while every other Deep-required subagent has, do not silently downgrade. Stop, surface the timeout to the user, and ask whether to (a) wait an additional 10 minutes, (b) downgrade to Standard delivery and write the final document without the red-team / strengths-and-weaknesses sections, or (c) abort. Default to (c).

**Timeout thresholds.** A subagent that has not returned **15 minutes from its
own spawn time** (Standard) or **25 minutes from its own spawn time** (Deep)
is considered timed out. The budget is **per-subagent**, not aggregate;
comparison mode keeps the same per-subagent budget (the doubled pool does not
get a doubled budget). Drop the timed-out subagent from the result set, fail
the run if a required FFS subagent is missing (see FFS rule above), and note
the gap in the final document's Methodology Appendix. Do not retry; proceed
with the subagents that did return only when FFS is satisfied.

#### Mid-run outline refinement (optional, time-boxed)

When the first wave of findings reveals an angle the Phase 2 plan did not name, see [`references/search-strategies.md`](references/search-strategies.md) § "Mid-Run Outline Refinement" for the full protocol. Capped at **one** refinement loop per run (Standard/Deep only); forbidden on Quick depth. Refinement state is tracked in the research-plan template's `refinement_state` field.

#### AS_OF freshness gate

For time-sensitive topics every cited source must carry a publication date and the final document must record an `AS_OF` value (anchored in Phase 1 Step 1). Stale sources downgrade or disqualify per [`references/freshness-gate.md`](references/freshness-gate.md). Apply these rules before drafting Phase 4.

### Phase 4 — Practical explanation

By the FFS rule, all four searcher results are present at this point. Read
[`references/synthesis-engine.md`](references/synthesis-engine.md) for the
triangulate → patterns → fact-to-insight → red-team protocol, then
[`references/teaching-tone.md`](references/teaching-tone.md) for tone
adaptation, then the **So What? Engine** section of
[`references/analysis-tools.md`](references/analysis-tools.md). Deliver
conversationally:

- Core concepts and terminology, in plain language.
- A simplified mental model of how it works (not implementation details).
- Key use cases with concrete examples.
- "So What?" applied to 3–5 of the most important concepts.
- Common misconceptions.

**Comparison mode (Phase 4):** see [`references/comparison-mode.md`](references/comparison-mode.md).

### Phase 5 — Getting started / integration

Tutorial-searcher and integration-searcher results are guaranteed present at this point per the FFS rule. Deliver:

- Step-by-step getting started: install, hello world, first real use.
- Integration patterns and ecosystem connections.
- Common pitfalls and how to avoid them.
- "If you only remember 3 things" — key takeaways.

If depth is **Standard**, write the final document using
[`assets/study-guide-template.md`](assets/study-guide-template.md) (or
[`assets/comparison-guide-template.md`](assets/comparison-guide-template.md)
for comparison mode), then proceed to Phase 7. Standard tier skips Phase 6
(Deep dive) and runs Phase 7's qualitative Quality Checklist before delivery.

**Comparison mode (Phase 5):** see [`references/comparison-mode.md`](references/comparison-mode.md).

### Phase 6 — Deep dive (Deep tier only)

Wait for the deep-analyst result. Re-load
[`references/synthesis-engine.md`](references/synthesis-engine.md) — the
red-team subsection is mandatory in Deep tier. Compile:

- Strengths with confidence levels (see `references/analysis-tools.md`).
- Weaknesses and limitations.
- Alternatives comparison table.
- Community sentiment summary.
- Caveats and edge cases.
- "When to use / When NOT to use" decision guide.
- Further reading: curated, annotated links.

Write the comprehensive document using
[`assets/study-guide-template.md`](assets/study-guide-template.md) (or
[`assets/comparison-guide-template.md`](assets/comparison-guide-template.md)
for comparison mode). Cite every source by tier per
[`references/source-quality.md`](references/source-quality.md). When the
final document cites more than eight sources, also write a per-source
mini-summary for each one using
[`assets/source-summary-template.md`](assets/source-summary-template.md),
saved alongside the study guide under `summaries/.md`, so a reviewer
can verify any single claim by opening one summary.

**Comparison mode (Phase 6):** see [`references/comparison-mode.md`](references/comparison-mode.md).

### Phase 7 — Quality assurance (all tiers)

Phase 7 runs for both Standard and Deep tiers. Run the qualitative
Quality Checklist from
[`references/analysis-tools.md`](references/analysis-tools.md) before
delivering any document.

**For the Deep tier additionally**, run the **Deep-tier numeric gates**
subsection of the same reference. If any gate fails, return to Phase 6 —
do not ship a Deep document t

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [85danf](https://github.com/85danf)
- **Source:** [85danf/agent-skills](https://github.com/85danf/agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-85danf-agent-skills-tech-topic-research
- Seller: https://agentstack.voostack.com/s/85danf
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.