Blog Topic Research

blog-topic-research

Generates topic candidates for a blog with documented user demand. The skill exists to fight hallucinated SEO ideas: every topic it proposes must point to a URL that proves someone is asking about it.

research <N> topics [for cluster <C>] [--append-to <path>]

• N - number of topics to return (default 50; cap 100)
• cluster - if the blog has cluster taxonomy, restrict to one cluster the user names
• --append-to <path> - after presenting results, ask the user before appending accepted topics as JSON to the given path (a backlog file, a CSV, whatever the blog uses)

The skill is content-only: it does no scraping of its own. It drives the agent's WebFetch and WebSearch tools to fetch sources, and (optionally) shells out to a Python similarity script for the cannibalization step.

The contract

For every topic the skill emits, it captures:

Hard rules:

• No URL, no topic. If the skill cannot cite a verifiable demand signal, the topic is dropped. No "this seems like a good topic" reasoning.
• No paraphrased evidence. The evidence field is copied byte-for-byte from the source (PAA question text, GitHub issue title, Reddit post title, forum thread title).
• No invented version numbers, prices, or stats. All numbers in the topic title must come from a source URL or be omitted entirely.
• Signal score >=3. Each signal scores 1 (exists), 2 (engaged), or 3 (heavy engagement) per the strength tiers below. One 3-star signal is enough; three 1-stars is enough.
• Specificity floor. Title must be either >=7 words OR contain a concrete qualifier: a version number, an error code/string, a named integration pair (X to Y), or a named edge case. Reject vague titles like "n8n tutorial" or "what is automation".
• Cannibalization check. Three layers when the user supplies an existing-titles cache: (1) Jaccard token overlap >=0.6 against any cached title = drop. (2) Cosine similarity >=0.85 = drop. (3) Token-dupe (shared distinctive numeric/error-code + shared tool keyword, regardless of cosine rank) = drop. Cosine 0.75-0.85 with no token-dupe = REVIEW (kept but flagged). If the user has no cache, run only Jaccard and skip the rest with a one-line note in the summary footer.
• Substance distilled, not invented. problem_summary, confirmed_fixes[], version_context, and question_variants[] are derived from fetched bodies - never hallucinated. If a body doesn't mention a fix, confirmed_fixes[] stays empty. If no version is named, version_context is null. The writer treats these as a verified scaffold and still re-fetches at least one primary source for currency.
• No padding. If the skill cannot reach N validated topics, it returns what it has and reports the shortfall.

Demand-signal taxonomy

A signal is valid only if its type is one of these, and the linked URL contains the verbatim evidence text:

Strength tiers (used to compute signal_score):

Engagement counts are read from the source page at fetch time. Record the count in the signal entry so the user can audit (e.g. [strength=3, 14 reactions]).

Does NOT count:

• The skill's own intuition.
• "Common pain point" with no link.
• "I've seen this on Twitter" without a specific URL.
• Doc paraphrases without a source.
• Topics extracted from another SEO blog without an underlying user-demand URL.

Sources to mine

The user supplies the source list for their blog (or asks the skill to suggest one). Generic source templates per cluster type:

Developer-tool / SaaS clusters

For each tool the blog covers, mine:

• The tool's official community forum (filter to "Questions" / "Bug reports", sort by reply count).
• The tool's GitHub issues, sorted by reactions desc, last 90 days.
• The tool's subreddit (top of week / top of month).
• Stack Overflow's tag page for the tool, sorted by views.
• The vendor's docs site (changelog, recently updated pages, "Common errors" if it exists).
• The vendor's blog (feature announcements - every new feature seeds new questions).

Code-language / framework clusters

• Stack Overflow tag page for the language / framework, sorted by views.
• The framework's GitHub issues + discussions.
• Reddit r/<language> and r/<framework>.
• Recent docs changes (a doc page that was edited last week often answers a recurring question).

Vertical clusters (e.g. ecommerce, customer-support, marketing-ops)

• Subreddits dedicated to the vertical (r/ecommerce, r/customerservice, etc.).
• Vendor template galleries (e.g. n8n's workflow gallery, Make's scenario library, Zapier's app directory) - each gallery entry is a verified user-demand signal because people search the named outcome.
• Forum threads asking "how do I [outcome]" with high engagement.

Always also mine

• Google Suggest autocomplete for the tool / language / vertical names.
• People Also Ask boxes on SERPs for the same.
• Google Trends rising queries for the cluster's main terms.

If the user has a specific cluster list, ask them for the source URLs before mining; if they don't, suggest a list and let them edit it.

Process

Step 1 - Inventory existing coverage (cannibalization prep)

If the user has an existing backlog file (backlog.json, posts.csv, an RSS feed of published posts, whatever), ask for the path and a way to enumerate titles. The cannibalization step needs an embedding cache built from these existing titles.

If a Python embedding script is available, the user can build a cache (a JSON file mapping each existing title to its OpenAI text-embedding-3-small vector) and point the cannibalization step at it. Typical cost is ~$0.02 per 1M tokens.

If no Python / no cache, fall back to Jaccard-only cannibalization (cheap, less accurate; surfaces near-identical titles but misses synonym dupes).

Also build a token-set per existing title (lowercase, alphanumeric, stopwords stripped) for the Jaccard prefilter used in Step 4.

Step 2 - Compute cluster targets

If the user has cluster weights (e.g. "30% n8n, 20% AI coding, ..."), apply them: subtract current backlog counts per cluster, then distribute N proportionally to the largest deficits.

If cluster <C> was specified, allocate all N to that cluster.

If no cluster taxonomy at all, treat the whole blog as one cluster and aim for format diversity instead (see Step 3 format matrix).

Step 3 - Mine candidates per cluster

For each cluster, walk its source list. For each source URL:

1. Fetch via WebFetch (or WebSearch for SERP-derived signals).
2. Extract candidate query strings: GitHub issue titles, PAA questions, Reddit post titles, forum thread titles, autocomplete suggestions.
3. Record the source URL + the verbatim title text + the engagement count (reactions, comments, upvotes, replies) so a strength tier can be assigned later.
4. Mine the body, not just the title. For each high-engagement issue / thread / SO question, fetch the body and extract:
   • Error strings (lines like Error:, TypeError:, Traceback, exception class names, stack-frame headers).
   • Code blocks between triple-backticks (often contain the failing snippet that names the real edge case).
   • Version-qualified phrases ("after upgrade to 1.65", "on Cursor 0.42", "since the v3 release"). Each extracted string becomes a candidate seed in its own right. Long-tail troubleshooting queries are usually the literal error message, which never appears in the post title.

Google-side seeds - use WebSearch with these patterns and parse for autocomplete + PAA. Run the full set per cluster, not just the troubleshooting one - long-tail diversity is what stops the corpus drifting into all-how-to-fix:

Repeat the matrix per tool / framework / vertical in the cluster.

Per-format source pointers (in addition to the per-cluster source list above):

• use-case - vendor template galleries are the highest-signal source. Each gallery entry is a verified user-demand signal (people search the named outcome). Reddit threads like "how do I [outcome] with [tool]" with many comments count too. Drop any seed whose only signal is an existing SEO blog's listicle - that's a competitor signal, not a user-demand signal.
• listicle - Google autocomplete depth-2 on best <category> and top <N> <category>; competitor roundup SERPs (look at what the top 3 results list). Reddit posts asking "what's the best X for Y" with many comments score high.
• migration - Reddit threads with titles starting moving from / switching from; Stack Overflow questions about exporting + re-importing between two tools; vendor migration docs (the doc exists because users ask).
• release-recap - the vendor changelogs already in the source list, but mine for specific versions shipped in the last 90 days. A release-recap post for <tool> <version> is only worth writing if (a) that version is current or one minor behind, and (b) the changelog has at least one user-facing entry, not just internal refactors. Older recaps go stale fast.

Each extracted query becomes a candidate. The source is its first demand signal.

Step 3b - Recursive autocomplete pass

For each candidate that survived Step 3, append one more qualifier word and re-query Google Suggest. Keep any deeper completion that returns a new variant. This is what gets you actual long-tail vs mid-tail - one autocomplete pass surfaces "how to fix n8n webhook error", a second surfaces "how to fix n8n webhook error 404 after restart".

Common qualifiers to try (try several, keep what returns a real completion):

error, not working, after update, stuck, slow, timeout, free, limit, vs <known competitor>, <current year>, self-hosted, cloud, docker

Cap at 2 recursive passes to bound runtime. Each new completion inherits the parent's first signal and must still pass Step 4 on its own.

Step 3c - Distill substance from the source body

For each candidate that survived Step 3b, build the writer-facing scaffold by re-reading the body of the highest-engagement demand signal (the one that scored 2 or 3 in the strength table - usually a high-reaction GitHub issue, pinned forum thread, or popular SO question). If you already fetched the body in Step 3.4, reuse it; otherwise fetch now.

Extract four fields:

1. problem_summary - 1-2 sentences in writer-voice describing the symptom + trigger. Factual, no marketing copy. Example: "n8n's HTTP Request node returns 401 when an OAuth2 credential's access token has expired and the refresh-token grant is missing the offline_access scope." Pull verbs and nouns from the body; don't paraphrase the title.

2. confirmed_fixes[] - list of {kernel, source} entries. Each kernel is one short phrase capturing the action (env var to set, version to downgrade to, setting toggle, code edit). The source URL is where the fix is reported (forum reply, vendor doc, GitHub commit, changelog entry). Walk the thread replies, accepted-answer block, vendor "common errors" page. Skip noise: ignore "have you tried restarting" or fixes contradicted by later replies. If the issue is genuinely still open with no working fix, leave confirmed_fixes[] empty - the writer will frame the post around "what's known so far" rather than fabricating a fix.

3. version_context - extract any version-qualified phrase the body or thread uses to scope the problem ("after upgrade to n8n 1.65", "Cursor 0.42 only", "introduced in CrewAI 0.114", "Power Automate desktop V2"). If multiple versions are named, pick the one most closely tied to the failure. If the body is version-agnostic, set null.

4. question_variants[] - 2-4 near-paraphrases of the topic that surface in PAA boxes, autocomplete depth-2 completions, sibling forum thread titles, or SO related-questions. Each variant must be a real captured string from a source - do not invent paraphrases. These feed the writer's FAQ block and LSI keyword spread.

If any of these can't be filled honestly from the body, leave the field at its empty default ("", [], null) rather than fabricating. A sparsely-filled scaffold is more useful than a hallucinated one - the writer can re-research, but cannot un-trust a polluted blob.

Step 3d - DataForSEO volume & difficulty enrichment

If DATA_FOR_SEO_API_BASE64 is configured in the environment, enrich every surviving candidate with real Google search-volume + keyword-difficulty. This is the quantitative half of demand validation — the qualitative URL signals prove someone asks; this proves how many and how hard it is to rank.

The env value is base64(login:password) and is used verbatim as the HTTP Basic credential. Batch all candidate primary keywords into one keyword_overview call (it accepts up to 700 keywords per request, ~$0.01 total — far cheaper than per-keyword lookups):

curl -s -X POST "https://api.dataforseo.com/v3/dataforseo_labs/google/keyword_overview/live" \
  -H "Authorization: Basic $DATA_FOR_SEO_API_BASE64" -H "Content-Type: application/json" \
  -d '[{"keywords":["<kw1>","<kw2>","..."],"location_code":2840,"language_code":"en"}]'

For each returned item read keyword_info.search_volume, keyword_properties.keyword_difficulty, and search_intent_info.main_intent. Attach a keyword_data demand signal to the matching candidate, scored per the strength tier table above, and record the volume figure in the signal's evidence string.

This signal counts toward signal_score — a winnable keyword (vol >=300, KD <=15) is a 3-star signal that can carry a candidate to the >=3 threshold on its own, the same as a heavy GitHub issue. Conversely, if the target blog is a new or low-authority domain, **drop any candidate whose keyword_difficulty exceeds your authority ceiling** (a sensible default is KD>35 for a domain with little ranking history — check the domain's standing with domain_rank_overview and raise the ceiling as authority grows). Log these under high-kd-unwinnable in the summary footer.

Graceful fallback: if DATA_FOR_SEO_API_BASE64 is unset, the API errors, or the account balance is exhausted (status_code 40200 / money.balance 0), skip this step entirely and fall back to qualitative-only scoring exactly as before. Print one line: keyword enrichment skipped: <reason>. The skill must never block on DataForSEO — it is an accelerant, not a gate.

Step 4 - Classify, score, and validate

For each candidate:

1. Cluster - derived from the tool / framework / vertical named in the topic. If the topic spans two clusters, pick the one with the higher-strength demand signal.

2. Format - match phrasing (evaluate in order; first match wins):

   • migrate from X to Y / switch from X to Y / move from X to Y -> migration
   • what's new in <tool> <version> / <tool> changelog / <tool> release notes / <tool> v<N> features -> release-recap
   • best X for Y / top N X / free X / X alternatives / most popular X -> listicle
   • X vs Y / X or Y -> x-vs-y
   • <error string> / not working / fix / fails / broken -> how-to-fix
   • connect X to Y / integration / integrate X with Y -> how-to-connect
   • build <outcome> with <tool> / <outcome> using <tool> / <tool> for <vertical/use-case> -> use-case
   • automate X / <tool> workflow for Y -> how-to-automate
   • what is X / X explained / how does X work -> what-is

   Ambiguity rules: prefer use-case over how-to-automate when the title names a concrete artefact ("daily Slack digest", "invoice extraction agent"); prefer how-to-automate for generic processes ("automate email triage"). Prefer listicle for >=3 options and x-vs-y for exactly 2.

3. Cannibalization - three-layer check against the existing-titles cache built in Step 1:

   • Jaccard prefilter: token-set overlap against existing titles; drop if >=0.6 (cheap kill on obvious dupes).
   • Semantic + token-dupe check (only if an embedding cache was built):
     • Cosine similarity >=0.85 against any existing title -> drop, log under cannibalization-semantic.
     • Token-dupe: a shared distinctive numeric / error-code AND a shared tool keyword between candidate and any existing title anywhere in the cache, regardless of cosine rank -> drop. (Catches substance-dupes whose surface wording differs enough that cosine ranks them low. Example: "Make AI Agent 40-second timeout" vs "Make HTTP module 40-second timeout error" - cosine 0.51, but shared [40-second, make] flags it.)
     • Cosine 0.75-0.85 with no token-dupe -> REVIEW (kept but flagged). The user decides at append time.
     • Cosine <0.75 with no token-dupe -> accept.
   • If no embedding cache, run only the Jaccard prefilter and add a one-line cannibalization: jaccard-only note to the summary footer so the user knows the check was reduced.

4. Score signals - assign each signal 1-3 per the strength tier table. If signal_score < 3, fetch one more SERP and look for additional signals (PAA, second forum thread, SO question, vendor doc). If still < 3, drop under low-signal-score.

5. Specificity floor - title must be >=7 words OR contain a concrete qualifier (version number, error code/string, named integration pair, named edge case). If neither holds, try to rewrite the title using a qualifier from the source text; if that's not possible, drop under low-specificity.

6. Primary source - find at least one vendor doc / GitHub issue / official changelog URL the writer can cite. If none, drop.

7. Keywords - extract the primary keyword (the topic's core noun phrase) plus 3-5 LSI variants from the source text. Do not invent variants.

Step 5 - Output

Print one block per accepted topic in this exact shape so the user can scan or pipe it:

[01/50] cluster=<cluster>  format=how-to-fix  priority=2
TOPIC: How to fix the n8n "Cannot read properties of undefined" error in Code node
slug:  n8n-cannot-read-properties-undefined-code-node
keywords: n8n Code node error, undefined property, JavaScript error, item access, $json
commentary: Specific to mistakes when accessing $json on the wrong item; vendor docs do not show the failure mode.
problem: The n8n Code node throws "Cannot read properties of undefined" when the script accesses $json on an item index that doesn't exist (typically the second iteration of a for-loop reading $items[1].json with only one input item).
fixes:
  - guard with $items[i]?.json before accessing  (https://github.com/n8n-io/n8n/issues/<id>#issuecomment-<n>)
  - use $input.item.json instead of $items[i] when iterating  (https://docs.n8n.io/code/builtin/data/)
version_context: n/a
question_variants:
  - "n8n Code node Cannot read properties of undefined reading 'json'"
  - "n8n JavaScript error TypeError undefined json"
  - "Code node loop fails when item missing"
demand: (signal_score=4)
  - github_issue: https://github.com/n8n-io/n8n/issues/<id>  ("Code node throws Cannot read properties of undefined") [strength=3, 14 reactions]
  - reddit:       https://www.reddit.com/r/n8n/comments/<id>  ("Help: Code node error when looping over items") [strength=1]
sources:
  - https://docs.n8n.io/code/builtin/data/  (n8n docs - Built-in data variables)

If confirmed_fixes is empty (open issue with no working fix), print fixes: (none documented yet - frame as 'what's known so far') instead of an empty list. If version_context is null, print version_context: n/a. If question_variants is empty, omit the line entirely (rare but valid).

If the topic landed in the REVIEW band of the cannibalization check, append a dedup_review line so the user can decide knowingly:

dedup_review: cosine=0.81 vs "n8n Code node returns undefined when reading $json" (backlog-queued)

Then a summary footer:

Requested: 50
Validated: <X>
Dropped:   <Y>  (cannibalization-jaccard: <a1>, cannibalization-semantic: <a2>, cannibalization-token-dupe: <a3>, low-signal-score: <b>, no primary source: <c>, off-cluster: <d>, low-specificity: <e>, high-kd-unwinnable: <f>)
Cluster mix:  <cluster1>=__  <cluster2>=__  ...
Format mix:   how-to-fix=__  how-to-connect=__  how-to-automate=__  x-vs-y=__  what-is=__  use-case=__  listicle=__  migration=__  release-recap=__

If --append-to <path> was passed: print the diff (count + cluster mix changes), ask Append <X> topics to <path>? [y/N]. On y, write each topic as JSON to the target path with:

{
  "id": "<slug>",
  "topic": "<title>",
  "cluster": "<cluster>",
  "format": "<format>",
  "priority": 100,
  "status": "queued",
  "tags": ["<format-tag>", "<tool-tag>"],
  "notes": "<commentary>",
  "added_at": "<YYYY-MM-DD>",
  "research_proof": {
    "demand_signals": [...],
    "primary_sources": [...],
    "keywords": [...],
    "problem_summary": "<1-2 factual sentences from the highest-engagement signal's body>",
    "confirmed_fixes": [
      {"kernel": "<short fix phrase>", "source": "<url>"},
      {"kernel": "<short fix phrase>", "source": "<url>"}
    ],
    "version_context": "<version qualifier or null>",
    "question_variants": ["<variant 1>", "<variant 2>", "<variant 3>"]
  },
  "published_slug": null,
  "published_at": null
}

The research_proof blob is preserved on the backlog entry while status = "queued" so a downstream writer skill can read it later (saves re-research). When the topic ships, strip the proof blob to keep the backlog file from ballooning at scale; the published post carries the citations.

Anti-hallucination guardrails

• WebFetch / WebSearch only. Never fabricate a URL. If a fetch fails, drop the candidate - do not invent the response.
• Verbatim evidence. Each evidence string is copied byte-for-byte. No paraphrase. Length cap 120 chars; truncate with ... if longer.
• No invented numbers. Version numbers, prices, error codes in the topic title must appear in at least one source URL. If unsure, drop them from the title.
• Date-bound the run. Every source URL must resolve on the run date. If 404 / removed, the signal is invalid even if the URL was good last week.
• Signal score >=3, strictly enforced. Cumulative strength below 3 goes to low-signal-score. The strength tier table is the only authority - do not invent your own scoring.
• Specificity floor enforced. Vague titles without a concrete qualifier go to low-specificity. Long-tail is proven by what's in the title, not by hand-waving "this is specific".
• Cluster discipline. Stick to the user's cluster taxonomy. Never invent a new cluster mid-run; if a topic doesn't fit, drop it or ask the user.
• Allowed-tag check. If the blog has a tag allowlist, surface any new implied tag to the user before accepting - do not silently expand the tag set.
• No commercial-intent topics by default. Reject SaaS reviews, lead-gen queries, affiliate-driven comparisons unless the user explicitly says they want them. Display-ad RPM is poor for these and they get out-bid by affiliate sites anyway.

What this skill does NOT do

• Does not draft posts. Pair with a writer skill downstream.
• Does not guess search volume. Absolute volume + difficulty figures come from one source only: the DataForSEO Labs API (Step 3d), and only when DATA_FOR_SEO_API_BASE64 is configured. A 5400 / mo figure is allowed only if it traces to a real keyword_overview response — never hand-estimated, never carried over from an SEO blog. With no API key, demand stays qualitative (proven by source URLs).
• Does not modify the blog's strategy docs. Cluster targets and weights are the user's call.
• Does not auto-publish. With --append-to <path> it adds to a backlog as queued; the user picks what gets written next.
• Does not run on a schedule by itself. Pair with a scheduling skill if you want a weekly or monthly research run.

One-command summary

research <N> topics [for cluster <C>] [--append-to <path>]

1. Refresh / build an embedding cache from existing titles, if the user has one.
2. Compute per-cluster target counts.
3. Mine candidates from the cluster source list, capturing verbatim text + URL + engagement count per signal. Mine issue / thread bodies for error strings and version-qualified phrases, not just titles.
4. Recursively expand surviving candidates through Google Suggest (up to 2 passes) to push from mid-tail into long-tail.
5. Distill substance per surviving candidate from the highest-engagement signal's body: problem_summary, confirmed_fixes[], version_context, question_variants[]. Empty defaults are valid; never fabricate. 5b. Enrich each candidate with real DataForSEO volume + KD (one batched keyword_overview call) when DATA_FOR_SEO_API_BASE64 is set; attach a keyword_data signal, drop terms above your authority ceiling. Skip gracefully if no key/balance.
6. Validate each: format match, cluster fit, three-layer cannibalization (Jaccard >=0.6 OR cosine >=0.85 OR token-dupe = drop; cosine 0.75-0.85 = REVIEW), signal_score >= 3, specificity floor, >=1 primary source, real keywords.
7. Print structured per-topic blocks + summary footer.
8. If --append-to <path>, confirm with user, then write to the backlog file with the proof blob preserved.

Source: jeremylongshore/claude-code-plugins-plus-skills → plugins/productivity/publishing-skills/skills/blog-topic-research/SKILL.md