| name | reddit-business-idea-validator |
|---|---|
| description | Validate a business idea by scraping Reddit posts/comments and running a multi-agent LLM analysis pipeline that produces a scored HTML report. Use whenever the user says things like "验证创业想法", "调研 XX 在 Reddit 上的反响", "这个产品有市场吗", "validate business idea", "is X a good business idea", "analyze market demand for X", "what pain points do people have around X", or provides a product/niche/idea and wants market signals, pain points, sentiment, competitive landscape, or a go/no-go recommendation. Also use when the user references this repo's pipeline ("跑一下 agent", "用 orchestrator 验证", "生成报告") and asks for a report. Produces an HTML report at reports/{idea}_{timestamp}.html with a 0-100 overall score, pain points, existing solutions, opportunities, recommendations, and a 4-category comment tag analysis. |
Reddit Business Idea Validator
Drive the existing pipeline in this repo (run_agent.py / agents/orchestrator.py) end-to-end. The pipeline is fully implemented — DO NOT reimplement scraping, analysis, or report rendering. Your job is to: (1) preflight the environment, (2) launch the pipeline with the right parameter profile, (3) recover from common failures using checkpoints, and (4) surface the score and report path to the user.
Prerequisites
- Working directory: repo root
D:\reddit_business_agent(or whatever the user's cwd is — always invoke scripts via absolute paths derived from<skill_dir>/..). .envin repo root with at minimum:OPENAI_API_KEY,OPENAI_BASE_URL(must end with/v1),OPENAI_MODELREDDIT_CLIENT_ID,REDDIT_CLIENT_SECRET,REDDIT_USER_AGENT
- Python 3.10+,
pip install -r requirements.txtalready run. - Reddit app type must be "script" at https://www.reddit.com/prefs/apps (otherwise 401 on auth).
File Layout
.claude/skills/reddit-business-idea-validator/
├── SKILL.md # this file
├── scripts/
│ ├── preflight.py # Phase 1: env/deps/API checks
│ ├── run_pipeline.py # Phase 3: non-interactive runner
│ ├── recover.py # Phase 4: list/inspect/resume runs
│ └── extract_report.py # Phase 5: read run_id → report/score
└── references/
├── failure-recovery.md # error → fix map
├── param-matrix.md # fast / standard / deep profiles
└── report-anatomy.md # report sections explained
All scripts accept -h / --help. Most emit JSON or JSONL so you can parse
them programmatically. They are thin wrappers around OrchestratorAgent —
business logic stays in agents/.
Workflow
Phase 0 — Decide if this skill applies
Apply when the user provides an idea/product/niche AND wants one of: market validation, pain-point discovery, demand estimation, sentiment, competitive landscape, go/no-go recommendation, or a Reddit-based report.
Do NOT apply for: pure keyword research, SEO tasks, generic LLM brainstorming, or when the user clearly wants a different data source (App Store, Amazon, Xiaohongshu, etc.) — this pipeline only covers Reddit.
If the user does not state a data source but mentions "Reddit", " subreddit", "post", or English-language markets, default to this skill.
Phase 1 — Preflight (always run first)
python "<skill_dir>/scripts/preflight.py"
Outputs a single JSON object. Read it and react:
| Field | On false |
|---|---|
env_ok | List the missing keys from missing[], point user to .env.example, STOP |
deps_ok | Offer pip install -r requirements.txt, then re-run preflight |
reddit_ok | Likely wrong app type — tell user to verify Reddit app is "script" type at https://www.reddit.com/prefs/apps |
llm_ok | Check OPENAI_BASE_URL ends with /v1; check API quota/billing |
Only proceed to Phase 3 when env_ok && deps_ok && reddit_ok && llm_ok are
all true. Preflight is fast (<5 s) — re-run freely.
Phase 2 — Pick a parameter profile
Default to standard. Offer the choice via AskUserQuestion if the user
hasn't specified; otherwise pick based on signals:
- "fast" / "快速" / "试试" / "smoke test" / dev iteration → fast
- default / "完整" / "正式" / "深度调研" / no signal → standard
- "尽可能多" / "最深" / "thorough" / one-shot for a real decision → deep
See references/param-matrix.md for exact numbers per profile.
Phase 3 — Run the pipeline
Launch in background, then poll output. The runner emits JSONL on stdout (one event per line) and a final summary event you can parse.
python "<skill_dir>/scripts/run_pipeline.py" "<idea>" --profile standard
Use the Bash tool with run_in_background: true. Read incremental output
with TaskOutput. Each line is JSON; key events:
{"event":"run_started","run_id":"...","profile":"standard","idea":"..."}
{"event":"stage","step":"scrape_data","progress":0.0,"message":"执行: 抓取..."}
{"event":"stage","step":"scrape_data","progress":1.0,"message":"完成: 抓取..."}
...
{"event":"done","success":true,"report_path":"D:\\...\\reports\\<idea>_<ts>.html","score":72,"run_id":"...","execution_time":187.4}
On event:"done" with success:true, you have the report path and score —
go to Phase 5.
On event:"done" with success:false, read error and failed_step, then
jump to Phase 4 / references/failure-recovery.md.
Phase 4 — Recover from failure
Two recovery modes:
4a. Resume from checkpoint — useful when scrape or analysis succeeded but a later step crashed (timeout, network blip):
python "<skill_dir>/scripts/recover.py" --resume-last --idea "<idea>" --profile standard
This finds the latest run_id for that idea, inspects which checkpoints exist, and re-invokes the pipeline using existing partial results where possible.
4b. Just list & inspect — for understanding state:
python "<skill_dir>/scripts/recover.py" --list # all runs
python "<skill_dir>/scripts/recover.py" --list --idea "<idea>" # filtered
python "<skill_dir>/scripts/recover.py" --show <run_id> # checkpoint detail
For known errors (401, quota, malformed JSON), follow references/failure-recovery.md
instead of blind retry — some failures are deterministic and need a human
fix.
Phase 5 — Surface results to the user
After event:"done":
Extract full result (cheap, idempotent):
python "<skill_dir>/scripts/extract_report.py" --run-id "<run_id>"
Returns JSON with
report_path,score,summary, top pain points, opportunities, and recommendations.Tell the user in chat, concisely:
- Overall score (0-100) and one-line gut interpretation (≥75 strong, 50-74 promising, 30-49 weak, <30 likely no-go)
- Top 3 pain points
- Top 3 opportunities
- Report absolute path — offer to open in browser
- Run id (so they can resume later or compare)
Do not paste the full HTML. It's large. Summarize; the user can open the file.
Offer follow-ups: re-run with
deepprofile, compare with another run, adjust the idea wording and re-validate.
Operating Principles
- Never reimplement pipeline stages. Call
run_pipeline.py. - Always run preflight before the pipeline on a fresh session — costs 5 seconds, saves a 10-minute failure.
- Background the pipeline. It can take 3-30 min depending on profile.
Use
run_in_background: trueand pollTaskOutput; don't block the turn. - Parse JSONL, don't regex human text. Stderr still has human logs for debugging — only stdout is structured.
- Be honest about scores. A 35/100 is a useful negative result. Don't sugarcoat; the user wants signal.
- Resume > restart. If a stage crashed after a successful scrape,
reuse the scrape via
recover.py --resume-lastinstead of re-scraping (Reddit rate limits are real).
Common Mistakes to Avoid
- Don't pass
--profile fastto "be helpful" without asking — fast misses signal. Default isstandard. - Don't read
.envkeys yourself to "verify" — preflight already does it authoritatively. - Don't try to
pip installnew packages mid-run; if preflight says deps missing, ask the user. - Don't shorten the business idea when passing it through — the pipeline uses it as the search keyword verbatim.
- Don't run two pipelines in parallel — they share
reports/and checkpoint dirs and will race on filenames.
References (read on demand)
references/failure-recovery.md— error → fix table, opened when phase 3/4 failsreferences/param-matrix.md— exact knobs per profilereferences/report-anatomy.md— what each section of the HTML report means