Topic Research

Run a second-hop deep research pass through the Tavily CLI after an initial scan, then normalize the result into a local `research.md` contract. Use when Cod...

Security Scan

The skill mostly does what its description says (call a local Tavily CLI, produce normalized research.md and raw JSON), but there are inconsistencies and a few design choices that increase risk and deserve clarification before trusting it.

Purpose & Capability

The SKILL.md and runtime.py clearly require the 'tvly' (Tavily) CLI to be installed and available on PATH, and the README instructs running an external install script (curl | bash). However the registry metadata lists no required binaries or primary credential — that mismatch is incoherent. A research skill that depends on a third‑party CLI should declare that dependency explicitly in the manifest.

Instruction Scope

Instructions are focused on building a query, calling 'tvly research --json', parsing JSON, and writing a normalized markdown and raw JSON into content-production/inbox/. That matches the stated purpose. Two points to watch: (1) the code allows 'source_file' in frontmatter to be an absolute path and will read it as-is — that enables the skill to read arbitrary files if the input frontmatter is malicious or mistaken; (2) the skill will write files into repo-local paths (content-production/inbox/...), which is expected but may overwrite existing files without further safeguards.

Install Mechanism

The skill itself has no install spec (instruction-only), which is low-risk. But the README recommends installing Tavily via a remote install script (curl -fsSL https://cli.tavily.com/install.sh | bash). Installing third-party CLIs via curl|bash is a higher‑risk action and should be audited before execution. The skill does not ship or pin the Tavily binary and relies on whatever the remote installer provides.

Credentials

The skill requests no environment variables or credentials in the manifest, which is consistent with not embedding credentials. However, it depends on a logged-in Tavily CLI; Tavily will presumably access its own auth tokens/config locally (not declared here). Also, because 'source_file' can be absolute, an attacker or misconfigured input could point the skill at sensitive local files — this is a proportionality/design concern rather than explicit credential exfiltration in the skill itself.

Persistence & Privilege

The skill is not marked always:true and does not request elevated platform privileges. It writes outputs into repository-local directories and does not appear to modify other skills or global agent settings.

What to consider before installing

This skill legitimately wraps a Tavily CLI workflow to produce normalized research reports, but before installing or running it: - Expect to install and trust a third‑party CLI (tvly). Audit the installer (https://cli.tavily.com/install.sh) before running curl | bash. Prefer installing from a reviewed package or vendor documentation if possible. - Confirm the manifest is updated to declare 'tvly' as a required binary so the skill's declared requirements match its runtime needs. - When creating the input markdown, avoid giving an absolute source_file that points outside the project (the skill will read absolute paths). Treat inputs as untrusted and run the skill in a workspace that contains no secrets. - Be aware the skill will write files into content-production/inbox/ and content-production/inbox/raw/research/ and may overwrite existing files. If you need higher assurance, request the author to: (1) add 'tvly' to required binaries in the registry metadata, (2) remove or restrict absolute-path reads for source_file, and (3) avoid recommending curl|bash installs in the README (or provide a pinned, auditable installer).

This skill deepens a selected topic after news-collect or any manually chosen theme. It does not replace first-pass collection. The report now also produces a local writing decision layer.

Quick Start

Run the default command:

.venv/bin/python -m skill_runtime.cli run-skill topic-research --input content-production/inbox/20260405-agent-topic-research.md

Prepare Input

Pass a markdown request file with YAML frontmatter.

Supported fields:

• topic
• question
• model: mini / pro / auto
• source_file: optional path to a prior news-report.md
• seed_urls: optional list or comma-separated URLs

Example:

---
topic: AI coding agents
question: 这些产品近一周的产品化方向和商业化信号是什么？
model: pro
source_file: content-production/inbox/20260405-ai-news-report.md
seed_urls:
  - https://example.com/a
  - https://example.com/b
---

补充说明：优先输出能转成中文公众号选题判断的结论。

Follow Research Workflow

1. Validate that tvly is installed and available on PATH.
2. Combine the request fields into a single research query.
3. Call tvly research ... --json.
4. Save the raw JSON and rewrite the result into a normalized markdown research report.
5. Add a writing-decision section covering whether the topic is worth writing, recommended structure, opening hooks, title directions, and evidence risks.

Write Output

Write the report to:

content-production/inbox/YYYYMMDD-<slug>-research.md

Write the raw JSON to:

content-production/inbox/raw/research/YYYY-MM-DD/<slug>.json

Respect Constraints

• Only use the repo-local dependency marker skills/tavily-research/ for this integration
• Do not silently fall back if tvly is missing or not logged in
• Keep the output contract stable even if Tavily CLI changes its JSON schema

Read Related Files

• Runtime entry: skill_runtime/engine.py
• Wrapper runtime: skills/topic-research/runtime.py
• Vendor dependency marker: skills/tavily-research/
• Data contract: docs/data-contracts.md