research
Gather keyword metrics, related terms, questions, full SERP benchmark, top-page extractions, and deep web research for a target keyword, then emit a beat spec the outline must satisfy. Triggered by /r
SKILL.mdpaperclip-source/blog-engine/.claude/skills/research/SKILL.md
GitHubResearch Skill
Produce a research dossier that ends in a beat spec — a quantified statement of what this article must do to deserve the top of this SERP. The outline is bound by the beat spec; the quality gate scores against it. If the research is thin, everything downstream is thin: this is the most leverage-dense stage of the pipeline.
Tool calls: read
references/semrush-mcp-cheatsheet.mdfirst — it pins the REAL tool/report names and parameter shapes (the only pattern isget_report_schema→execute_report). Never callmcp__semrush__keyword-overview,topic-research,serp-resultsor other invented names; they don't exist.
Input
A target keyword as a string. Example: ai girlfriend app.
If invoked with no argument, read the most recent context file in content-pipeline/0-context/ and prompt the user for the keyword.
Process
Slugify.
python scripts/slugify.py "<keyword>"; store the slug.Read brand context.
brand-config.md— audience, products, voice. Research framing should consider what this brand can credibly own.Pull keyword data via Semrush MCP (cheatsheet steps 1–4):
phrase_this+phrase_kdi→ volume, CPC, competition, KD%phrase_fullsearch+phrase_related(limit 40–50) → variation pool; keep 10–15 same-intent keywords with volumesphrase_questions(limit 30–40) → group into 3–5 question themes; drop spamphrase_organic(limit 10–20) → the ranking URLs, in order
Build the SERP benchmark (MANDATORY — the heart of this skill). Extract the full content of the top 5–8 ranking pages (skip ads, skip our own domain): for each page, POST to Firecrawl (
https://api.firecrawl.dev/v1/scrape, body{"url": <url>, "formats": ["markdown"]}, headerAuthorization: Bearer $FIRECRAWL_API_KEY); fall back to WebFetch on error. From each extraction record:- Word count (of article body, excluding nav/boilerplate — estimate honestly)
- Title + full H2/H3 list
- Format (guide / listicle / comparison / how-to / explainer) and item count if list-shaped ("9 apps reviewed")
- Evidence types used: tables (count them), screenshots/images (count), original data, expert quotes, hands-on detail
- What it does well; where it's thin or generic Then compute the benchmark table:
- Median + max word count of the top 3
- Modal format and item-count range
- Table/visual usage across the SERP ("4 of 5 pages have a comparison table")
- Consensus topics — covered by 3+ of the extracted pages (the article MUST cover all of these)
- Partial topics — covered by 1–2 (differentiate with more depth)
- Gaps — asked by searchers (question themes, deep research) but covered by nobody (the information-gain opportunity)
Authority check.
domain_ranksfor the top-3 domains,url_organic(limit 10) for the top-3 URLs → is this SERP beatable, and what secondary keywords do winning pages also rank for (fold the good ones into the outline's subtopics).Deep web research via OpenRouter (Perplexity). Voice-of-customer + community signals (Reddit, forums, review sites):
doppler run -- python .claude/skills/research/scripts/openrouter_research.py \ --keyword "<keyword>" --slug "<slug>"Output lands at
content-pipeline/1-research/{slug}-deep.md. IfOPENROUTER_API_KEY_BLOG_AGENTisn't set, skip and note it in the dossier — don't fail the pipeline.Recommend an angle. One-sentence thesis that wins against the current SERP, with justification grounded in the benchmark's gaps + what this brand can credibly demonstrate first-hand.
Write the beat spec — the dossier's final section, in exactly this shape:
## BEAT SPEC (binding on outline + quality gate) - Target word count: <max(1.1 × median of top 3, 1800)> (±20%) - Format: <modal SERP format>; item count: <max items on SERP + 1, if list-shaped> - Comparison table: <required iff ≥2 of top 5 have one — list required columns> - Must-cover topics (consensus): <bulleted list — every one becomes outline coverage> - Differentiation topics: <partial-coverage topics we go deeper on> - Information gain (≥1 REQUIRED): <the thing nobody on page 1 has — original comparison, first-hand product walkthrough, fresh data, better explanation> - Secondary keywords to work in naturally: <from url_organic + variations> - Beatability: <honest read — authority spread, content quality of incumbents>Write the dossier to
content-pipeline/1-research/{slug}.mdpertemplates/research-template.md. No{{VAR}}markers left. Include a "Deep web research findings" summary section (the-deep.mdfile stays available to/draft).Emit chartable data (unchanged): if the dossier surfaces numeric breakdowns worth charting, write
content-pipeline/1-research/{slug}-data.json({label: number}dicts, snake_case keys,_meta.sourcefor auditability). Don't fabricate; omit if nothing chartable.
Output
content-pipeline/1-research/{slug}.md — 1,200–2,500 words. Dense, scannable, no fluff. The outline skill reads it end-to-end.
Quality checklist
Before saving, verify:
- Primary keyword has volume, KD%, CPC (real Semrush numbers, not guesses)
- 10–15 same-intent related keywords with volumes
- 10+ questions grouped into 3+ themes
- Top 5+ pages extracted with word count, H2 list, format, item count, table/visual counts
- Benchmark table computed (median/max words, modal format, table usage)
- Consensus / partial / gap topics explicitly listed
- BEAT SPEC section present, complete, and numerically specific
- One-sentence recommended angle with justification
- Deep-research section present (or explicit note that OpenRouter wasn't configured)
- At least 3 verbatim user quotes when deep research ran
- No raw CSV/JSON dumps; everything synthesized
- Brand context reflected — the angle is something THIS brand can credibly own
When to re-run
If the SERP shifts (new competitor, format change) or the angle stops holding. Re-running here is cheaper than reworking any later stage.