audience-research
Mine where your audience actually talks (reviews, Reddit, YouTube comments, communities) and produce two brand files, audience.md (segments, awareness, jobs-to-be-done, watering holes) and voc.md (verbatim pain/desire/objection language with sources). Use it before positioning or copy work, when launching into a new market, or when copy keeps missing because nobody knows how customers actually describe the problem.
How do I install this agent skill?
npx skills add https://github.com/boringmarketer/boring-marketing-skills --skill audience-researchIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill facilitates market research by mining public data from various websites using subagents and local scripts. The primary security consideration is the ingestion of untrusted external content from reviews and forums, which poses a surface for indirect prompt injection.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
Audience Research
Find the rooms where your buyers complain, compare, and confess, and bring back their exact words. Done means two files: an audience profile where every claim traces to evidence, and a verbatim language bank that lets every downstream skill enter the conversation already happening in the customer's head. The judgment this skill carries: knowing which sources are signal for which business, and refusing to launder paraphrase as voice-of-customer. The method is a floor, not a ceiling. When the category in front of you argues for different sources or sequence, take them and say why.
Context
Only if ./brand/, ./brands/ or MARKETING.md exists (nothing to load otherwise), run:
python3 ${CLAUDE_SKILL_DIR}/../start-here/scripts/brand_context.py --for audience-research
(If the script or python3 is unavailable, read the files named in reads: directly,
section-anchored where specified. If none exist, proceed standalone. Ask only for what
the task strictly requires.)
If positioning.md#market-assessment exists, use its declared Category: and the known
competitors as mining seeds. If audience.md or voc.md already exist (check brand.yaml), default to
Refresh mode unless the user asks to start over.
Modes
- Full research (default): Phases 1-4 below. Needs a product URL or a one-line description + category.
- Refresh ("refresh my audience research"): diff new mining against existing files. See Refresh mode.
- Interview fallback: no URL, web access failing, or the user explicitly wants a fast
draft. See Interview fallback. The audience.md header carries
Data: MODEL KNOWLEDGE, and the chat note says in plain words that this is a draft from category knowledge, not mined research. Never let it masquerade as mined research. - Quick Mode: a narrow ask ("what do customers say about onboarding?", "mine pricing objections") gets a targeted mine of 2-3 sources on that theme only, appended to voc.md under the matching section. No source map ceremony, no full synthesis. Deliver, then one line of what's-next.
Phase 1: Source map
From the product category, pick 5-8 mining sources. This is a judgment call, not a checklist: the wrong sources return polite noise; the right ones return rage, longing, and exact vocabulary.
Highest-signal sources by business type:
| Business type | Mine first | Also strong | Usually weak |
|---|---|---|---|
| B2B SaaS | G2 + Capterra (2-4★), category subreddits, competitor G2 reviews | LinkedIn comment threads, niche Slack/Discord (if public), HN threads | Twitter praise, vendor case studies |
| E-com / consumer product | Amazon reviews (own + competitor, 2-4★), Reddit | Trustpilot, YouTube review comments, TikTok comments | Instagram comments (performative) |
| Mobile / app | App Store + Play Store reviews (sort: recent, not helpful), Reddit | YouTube tutorial comments | The app's own community (survivor bias) |
| Services / agency | Reddit ("anyone hired a...?" threads), X/LinkedIn discussions | Google/Clutch reviews, podcast episode comments | Testimonial pages |
| Local service business | Google reviews (2 to 4 stars) of the business and the top 3 in its map pack, Reddit trade and city threads ("anyone used a good plumber in...?"), Angi, Yelp and BBB complaints | Nextdoor and neighborhood groups when public, Thumbtack | The business's own testimonials page |
| Creator / info product | YouTube comments on category videos (not the creator's own), Reddit | X replies under big accounts in the niche, Udemy/Skool reviews of competing courses | The creator's own audience (already converted) |
Rules that govern the map:
- Local example (sample business Hartline Plumbing, Dallas TX). Mine its Google reviews and those of the top three plumbers in the map pack, one Dallas thread search ("plumber", "water heater", "overcharged"), and the one-to-three-star Angi or Yelp reviews. The switching triggers are usually showing up late, surprise bills and no callback. Those words become the language for ads and the first screen.
- Competitor reviews outrank your own. Your reviews tell you about your product; competitor reviews tell you about the market. Competitor 1-star reviews are switching triggers verbatim. Default: at least one miner on a competitor review surface.
- Find the real subreddits, don't guess. Search
site:reddit.com [category problem language]and verify the sub is alive (posts in the last week, comments per post >3) before assigning a miner to it. A dead sub burns a slot. We use Exa for this search: it matches on meaning, so a thread that describes the problem in the customer's own words comes up even when no keyword matches (free tier, then pay as you go). Without it, thesite:reddit.comsearch in WebSearch does the job. - One source per distinct conversation type. Reviews = post-purchase judgment. Reddit/forums = pre-purchase confusion and comparison. YouTube comments = aspiration and skepticism. Social = identity and hot takes. You want coverage across types, not five review sites.
- 5-8 sources is the budget. If the category is tiny (niche B2B), 4 deep sources beat 8 thin ones. Say so and proceed.
- Hard caps: each miner ≤ 5 page fetches on its source and ≤ 8 minutes,
no sub-agents. A miner that hits its cap returns its pack as-is, labelled
budget-capped.
Keep the source map as working notes (source, type, why); it becomes Watering Holes in audience.md, not chat output. Do not ask permission to mine unless access is ambiguous (private community, login wall).
Phase 2: Parallel mining
Check the web first. Before dispatching, make sure your own WebSearch works (the Phase 1 subreddit search counts; otherwise run one). If it is denied or errors, the miners will be blocked too: don't dispatch them, go to Interview fallback and say why in one line. If miners come back blocked anyway, do the same with whatever they returned.
We use Firecrawl to read the review and forum pages: full-page reads, so every quote comes from the page itself and not a summary. It has a free tier of 1,000 credits a month with no card, and Hobby starts at $16 a month (billed yearly) for 5,000. Without it, WebFetch reads the public pages; where it returns only a summary, take the quote from the search result with its full URL or report the skip.
Fan out one subagent per source, all in parallel, using the Task/Agent tool
(general-purpose). Each subagent's brief must include:
- The source URL(s)/search strategy, the product, category, and known competitors.
- Instruction to read
${CLAUDE_SKILL_DIR}/references/voc-mining-judgment.mdbefore mining. It carries the signal/noise rules (2-4★ first, specificity weighting, astroturf detection, "I wish it..." flags). - Budget: ≤ 5 page fetches, ≤ 8 minutes, no sub-agents. Return the pack when either is
hit. Scraping order: Firecrawl MCP tools if available (
FIRECRAWL_API_KEYunlocks this), else WebFetch/WebSearch. Scrape real pages. Quotes from search-result snippets are acceptable only with the full source URL, never from memory. Enhanced (SCRAPECREATORS_API_KEYset): for Reddit and community material, use ScrapeCreators (paid, with a small free allowance; it reads Reddit, YouTube, TikTok, X and other posts and comments a logged-out page hides) and only its documented endpoints; baseline: use WebFetch/WebSearch on public pages and label the smaller sample. Or treg, one token for many data APIs (pay per call), if you'd rather not open a separate account. - The return contract: an evidence pack of 8-15 entries, no prose narrative:
- quote: "<verbatim, unedited, keep typos, keep profanity, ellipses only for trims>"
source_url: <full URL>
source_type: review | reddit | youtube | forum | social
date: <as precise as the page allows; "undated" if truly absent>
context: <one line: who's speaking, star rating, what they were replying to>
intensity: <1-5 per the rubric in voc-mining-judgment.md>
theme: pain | desire | objection | vocabulary | switching-trigger
segment_signal: <role/identity cues in the text, or "none">
Hard rules for miners: verbatim or nothing: paraphrase is not evidence; no quote without a URL; skip inaccessible sources (login walls, blocked scrapes) and report the skip rather than improvising; flag suspected astroturf entries instead of silently including them.
25 verbatim quotes across ≥3 source types is the bar for synthesis. Reach it and
stop mining. Only if the first wave came back thin (under 15) run one second wave on the
two richest sources (competitor #2, "best alternative to X" threads). Still under 25?
Synthesize anyway. Record the confidence in the voc.md header (Data: LIVE (n quotes, below the 25 bar; segment claims are provisional)) and say it once in plain words in the chat
note.
Phase 3: Synthesis
This is where judgment earns its keep. Load references/voc-mining-judgment.md yourself
before synthesizing if you haven't already.
Cluster pains by frequency × intensity. A complaint mentioned 12 times at intensity 2 and one mentioned 4 times at intensity 5 with vivid language are different animals: the first is a fact about the category, the second is often the campaign. Score both axes; don't let raw counts alone pick the lead pain.
Separate table stakes from differentiators. Complaints every vendor in the category receives (slow support, "pricing is confusing", onboarding friction) are table stakes. Necessary to acknowledge, useless to lead with. Desires and pains that customers use to choose between options are the differentiating material. Test: would this quote appear under any competitor's reviews too? If yes, table stakes.
Name the dominant emotion. One word per segment: frustration, anxiety, embarrassment, overwhelm, distrust, FOMO. Copy that matches the dominant emotion converts; copy that matches the feature list doesn't. Cite the 2-3 quotes that earn the label.
Harvest repeated exact phrases. When three unrelated strangers use the same phrase ("I just want it to work", "death by a thousand integrations", "felt like I needed a degree to set it up"), that phrase is headline material. Record it with its count in voc.md's Vocabulary section, these go to /direct-response-copy untouched.
Tag awareness level per segment (Schwartz): unaware / problem-aware / solution-aware / product-aware / most aware. Read it from the language: describing symptoms with no category name = problem-aware; comparing named tools = product-aware; asking "is this even possible?" = unaware-to-problem. Also note the category's sophistication stage if the evidence supports it. What claims customers now roll their eyes at.
Flag surprises. Anything that contradicts the brand's current positioning
(positioning.md#market-assessment) or obvious founder assumptions gets its own section. The gold
is usually what the founder didn't expect: the segment nobody markets to, the "wrong" use
case people love, the objection that isn't price. If nothing surprised you, you mined too
shallow. Say which sources you'd go deeper on.
Discard before writing: astroturf-flagged quotes, vendor-planted comparisons, quotes about a different product than they appear to be (common on Amazon variant listings).
Phase 4: Output
Write files first, then summarize. Data lines and VOC IDs stay in the files, not chat. If audience.md or voc.md exist, auto-version the
old copy to ./brand/.history/<file>.<YYYY-MM-DD>.md, then write; show a 3-line summary
of what changed. Update brand.yaml timestamps for both files.
./brand/voc.md: the verbatim language bank. Conforms to
${CLAUDE_SKILL_DIR}/../start-here/references/schemas/voc.schema.json. Every quote carries a stable ID so downstream skills
and audience.md can cite it:
# Voice of Customer: <brand>
Data: LIVE (47 quotes, 6 sources) · Mined: YYYY-MM-DD · Sources: <list>
## Pains
### <theme name>: frequency 9 · peak intensity 5
- [VOC-P01] "exact quote" · <source_url> · YYYY-MM · intensity 4 · <context>
...
## Desires (IDs VOC-D..)
## Objections (IDs VOC-O..)
## Switching Triggers (IDs VOC-S..; mostly from competitor 1★ reviews)
## Vocabulary (IDs VOC-V..; exact repeated phrases, with counts; their words vs. industry words)
Quote it, don't paraphrase it. That rule binds every skill that reads this file.
./brand/audience.md: who they are. Every claim cites VOC IDs or a source URL; a
claim with no citation either gets evidence or gets cut:
# Audience: <brand>
Data: LIVE (...) · Updated: YYYY-MM-DD
## Segments (per segment: who they are, JTBD, awareness level + the quote that proves it)
## Pain Language (top pains ranked by frequency × intensity, table-stakes flagged, citing VOC-P IDs)
## Desires & Buying Triggers
## Objections (and what evidence would dissolve each)
## Watering Holes (where they actually talk: the live sources from Phase 1, with which segment lives where)
## Dominant Emotion & Sophistication
## Surprises (findings that contradict current positioning/assumptions)
The ## Pain Language heading is load-bearing. Other skills read
audience#pain-language by anchor.
Then deliver in chat per the output contract: ## AUDIENCE RESEARCH: {Brand} with one line
of date and what the research is for (no data label); the 5 most actionable findings on
one screen (lead pain + its phrase, dominant emotion, sharpest switching trigger, the
headline-ready vocabulary, the biggest surprise), each with one verbatim quote and where it
was said ("Google review, Mar 2026"), never a VOC ID; one Sources and assumptions note
in plain words (how many quotes from how many sources, read live on what date; any source
skipped or budget-capped; segment claims that are provisional; what to confirm); Files
saved with paths and (new)/(updated) markers; What's next.
Refresh mode
When audience.md/voc.md exist and the user says refresh:
- Read both files; note
Mined:date and the sources used. - Re-run Phase 2 with a smaller fan-out (3-4 subagents) against the same watering holes plus any new competitor, instructing miners to prioritize content newer than the last mine date.
- Diff, don't rewrite: classify findings as NEW (theme absent from existing files), SHIFTED (frequency/intensity moved, language changed), or CONFIRMED (still true, one line, no re-litigation).
- Append new quotes to voc.md with fresh IDs (never renumber existing ones; downstream
files cite them); update audience.md sections only where something shifted; version
the old copies to
.history/as usual. - Chat output leads with NEW and SHIFTED only.
Interview fallback
No URL, no web access, or the user wants a draft now. Deliver a draft first, questions
last: write ./brand/audience.md from what you know of the category, labeled Data: MODEL KNOWLEDGE (not yet checked against real customers; verify before spending), in
the same structure as a Full run so a later run upgrades it in place. Every segment and
pain in it is a hypothesis. End the file and the chat reply with these questions; the
answers turn the draft into evidence:
- Who buys this, and what's their job title or life situation?
- What were they doing about the problem before finding you?
- What's the last thing 2-3 real customers said to you, as close to word-for-word as you can get?
- Why do the people who don't buy say no?
- Where did your best customers say they heard about you or hang out online?
- What's the one belief about your market you'd bet money on that you've never verified?
voc.md holds only real words: write it from answers to Q3, marked source: founder-recall;
never invent quotes. If the web was the blocker, say in one line that allowing WebSearch
and WebFetch (/permissions) and re-running upgrades the draft to mined research.
Output
Per ${CLAUDE_SKILL_DIR}/../start-here/references/output-format.md: HEADER / CONTENT / FILES SAVED / WHAT'S NEXT. Files
first, chat second. Append one line per file to ./brand/assets.md. One optional
one-line ask at most ("If a finding turns out wrong in market, tell
/performance-review"). No feedback interview.
What's next (pick 2-4 that fit the situation):
/positioning-angles: the VoC white space + switching triggers feed angle generation directly (~15 min)/direct-response-copy: voc.md Vocabulary section is the headline bank; copy can now quote, not invent (~15 min)/lead-magnet: the top problem-aware pain usually names the magnet (~10 min)/brand-voice: if vocabulary mining showed the brand speaks industry while customers speak plain (~10 min)
When the user edits your work
Apply the edit, then make it stick: save a gold case to ./brand/gold/<this skill>/ and
one to three yes/no checks to ./brand/checks.md, and confirm in one line. Before handing
over any work, answer the checks the context block loaded, silently, and fix every no.
How: ${CLAUDE_SKILL_DIR}/../start-here/references/taste-loop.md.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/boringmarketer/boring-marketing-skills/audience-research">View audience-research on skillZs</a>