hyperfx-aihyperfx-ai/marketing-skills/skills/customer-research/SKILL.md

customer-research

Skill107 starsChanged 5 months agoMITView on GitHub

Mine online communities and analyze existing assets to understand what customers actually think, say, and struggle with. Use when the user wants to do customer research, ICP research, voice-of-customer (VOC), review mining, Reddit mining, YouTube comment analysis, G2/Capterra scraping, build customer personas, map jobs to be done, understand churn reasons, or find authentic customer language for copy. Also use when given transcripts, surveys, or support tickets to synthesize.

We split this skill into the rules it gives an agent

13 rules. 0 are common, 10 are distinctive, and 3 are very specific to this project.

0
Common
Most of the 58 edited versions we read keep these.
10
Distinctive
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Distinctive:
Not all scrapers need to be active for every run — enable the ones relevant to your ICP (Reddit and one review site is the minimum).
line 33
Distinctive:
Every tool in this skill is named by its canonical tool name.
line 37
Very specific:
If a tool is not found: in Hyper chat, find its toolkit id with discover_toolkits and pass it to enable_toolkit.
line 45
Distinctive:
Always capture verbatim language: Don't paraphrase customer quotes — the exact words are what gets used in copy and messaging.
line 63
Distinctive:
Scrape before summarizing: Don't rely on your training data to describe what customers say about a product.
line 64
Distinctive:
Don't invent persona details: If you don't have data for a persona field, leave it blank rather than filling it in with assumptions.
line 67
Very specific:
Read references/synthesis-templates.md for the extraction framework, persona template, and VOC quote bank format.
line 80
Distinctive:
Before calling anything, decide which sources are worth hitting for this specific audience:
line 96
Distinctive:
Minimum viable run: Reddit + one review site: Add supplementary sources only when the minimum doesn't produce enough signal, or when the …
line 106
Very specific:
After pulling from 3+ sources, synthesize into the research report format in references/synthesis-templates.md.
line 204
Distinctive:
Only build personas if you have ≥5 independent data points from a consistent segment.
line 213
Distinctive:
Only ask what's genuinely missing.
line 221
Distinctive:
Ask which one(s) the user needs before generating:
line 233

“Common” is measured: kept by at least 6 in 10 of the 58 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

Customer Research

Guide for gathering and synthesizing real customer intelligence — from online communities, review sites, video comments, and social platforms — using the Hyper MCP scraper toolkit.

The goal is always the same: surface what customers actually say (in their own words), not what you assume they say.

Out of scope — defer to other skills

Request	Send them to
Researching competitor brands (site, ads, search rank)	`competitor-intel`
Writing copy informed by the research	`copywriting`
Optimizing a page using VOC insights	`page-cro`
Keyword research and SERP analysis	`seo-research`

Requirements

Hyper MCP installed. https://app.hyperfx.ai/mcp
Reddit Scraper, Twitter Scraper, YouTube Scraper, TikTok Scraper and Instagram Scraper toolkits enabled at https://app.hyperfx.ai/apps.

Not all scrapers need to be active for every run — enable the ones relevant to your ICP (Reddit and one review site is the minimum). If a scraper tool is not found, skip that source and continue with the others.

How to run the tools in this skill

Every tool in this skill is named by its canonical tool name. Run it with the call your surface gives you:

Surface	Find a tool	Run it
Hyper chat	Call the tool by its name; `search_tools(queries=["<provider> <action>"])` shows its parameters	`<name>(...)`
MCP client (Claude, Cursor, Codex, ChatGPT)	`search("<what you want to do>")`, then `describe("<name>")`	`call_read("<name>", {...})`, `call_write` or `call_destructive`: the one that `describe` names in `call_with`
Hyper CLI	`hyperai search "<what you want to do>"`, then `hyperai describe <name>`	`hyperai call <name> --json '{...}'`

If a tool is not found: in Hyper chat, find its toolkit id with discover_toolkits and pass it to enable_toolkit. On an MCP client or the CLI, tell the user which integration to connect in Hyper.

Tool surface

Tool	Purpose
`reddit_scrape`	Mine posts and comments from subreddits or by keyword
`x_tweets_search`	Search X/Twitter with advanced operators and engagement filters
`youtube_videos_search_top`	Find the top YouTube videos on a topic — use as input for comment mining
`youtube_comments_search`	Pull comments from specific YouTube video URLs
`youtube_video_transcripts_fetch`	Fetch the full transcript of a YouTube video for language/topic extraction
`tiktok_videos_scrape`	Search TikTok by keyword or hashtag — find trending conversations and comments
`firecrawl_urls_scrape`	Scrape review pages (G2, Capterra, Trustpilot, app stores); `proxy="auto"` for bot-protected sites
`google_search_results_search`	Find discussion threads, forum posts, and `site:` searches
`instagram_posts_scrape`	Pull recent posts from specific brand or community accounts

Critical rules

Always capture verbatim language. Don't paraphrase customer quotes — the exact words are what gets used in copy and messaging. Extract and preserve them.
Scrape before summarizing. Don't rely on your training data to describe what customers say about a product. Actually fetch the sources.
Label confidence on every insight. High = 3+ independent sources, unprompted. Medium = 2 sources or prompted only. Low = single source. Never present a Low-confidence finding as a conclusion.
Mind the bias of each source. Reddit skews technical and skeptical. Review sites skew toward power users and people with strong opinions. Support tickets skew toward problems. Factor this in before generalizing.
Don't invent persona details. If you don't have data for a persona field, leave it blank rather than filling it in with assumptions.
youtube_video_transcripts_fetch is slow (~15–30s). It spins up an isolated sandbox. Only use it for videos where the language in the spoken content (not comments) is what matters.

Two modes

Most research combines both modes. Establish which applies before starting.

Mode 1 — Analyze existing assets

The user provides raw material: interview transcripts, survey responses, NPS verbatims, support tickets, win/loss notes. No tool calls needed — the job is extraction and synthesis.

Read references/synthesis-templates.md for the extraction framework, persona template, and VOC quote bank format. Then produce the requested deliverable.

Mode 2 — Go find research online

The user needs intel from online communities, review sites, and social platforms. This is where MCP tools do the heavy lifting.

The steps below name the tool of each source. Read references/source-playbooks.md only when a scrape fails or returns nothing.

Mode 2 workflow

Bias toward action. If the user's message includes a product name (or URL) and a recognizable goal (research competitors, build a persona, understand churn, find VOC language), skip the questions, state your plan in one sentence, and start Step 1. Only ask when something essential is genuinely missing — product identity or target segment, for example. Don't ask all five questions before doing anything.

Step 1 — Pick sources based on ICP type

Before calling anything, decide which sources are worth hitting for this specific audience:

ICP	Required	Supplement if time allows
B2B SaaS, technical buyers	Reddit (role subs) + G2/Capterra	YouTube tutorials, X/Twitter
SMB / founders	Reddit (r/entrepreneur, r/smallbusiness) + G2/Capterra	YouTube, X/Twitter
Developer / DevOps	Reddit (r/devops, r/programming) + G2/Capterra	YouTube, Hacker News
B2C / consumer	Reddit hobby subs + app store reviews (1–3 star)	YouTube comments, TikTok
Enterprise	G2 Enterprise filter + X/Twitter	LinkedIn, YouTube

Minimum viable run: Reddit + one review site. Add supplementary sources only when the minimum doesn't produce enough signal, or when the ICP table above calls for them.

Step 2 — Run targeted scrapes

Pull from at least 2 sources. Single-source findings are low confidence by definition.

Reddit — the highest-signal source for most ICPs:

reddit_scrape(
    searches=["[product category] frustrations", "[competitor name] problems"],
    sort="top",
    time="year",
    max_items=50,
    skip_comments=False,
    search_posts=True,
    search_comments=True
)

For specific subreddits, pair with start_urls:

reddit_scrape(
    start_urls=["https://www.reddit.com/r/marketing/"],
    searches=["CRM"],
    sort="top",
    time="year",
    max_items=30
)

YouTube comments — rich qualitative data:

# Step 1: find the relevant videos
youtube_videos_search_top(query="[product category] honest review", max_results=5, sort_by="views")

# Step 2: mine comments from the top results
youtube_comments_search(
    start_urls=["https://www.youtube.com/watch?v=VIDEO_ID_1", "https://www.youtube.com/watch?v=VIDEO_ID_2"],
    max_comments=100,
    comments_sort_by="0"   # "0" = top comments, "1" = newest
)

X/Twitter — complaints, frustrations, and niche conversations:

x_tweets_search(
    search_terms='"[product name]" frustrating OR broken OR switched OR canceled',
    max_items=50,
    min_faves=5
)

Review sites (G2, Capterra, Trustpilot):

# G2 reviews for a specific product
firecrawl_urls_scrape(
    url="https://www.g2.com/products/[product-slug]/reviews",
    proxy="auto"
)

TikTok — consumer conversations and trending frustrations:

tiktok_videos_scrape(
    search_queries=["[product category] problems", "[competitor name] review"],
    results_per_page=30
)

Google discovery — find threads and communities you haven't thought of:

google_search_results_search(
    query='site:reddit.com "[product category]" "I switched" OR "I quit" OR "stopped using"',
    num_results=20
)

Step 3 — Extract signal from raw data

For each source, extract into this structure:

Field	What to capture
Verbatim quote	Exact words — do not paraphrase
Source	Platform, URL, date
Sentiment	Positive / negative / neutral / frustrated
Theme	Pain / trigger / outcome / alternative / language
Profile signals	Role, company size, industry hints from context

Step 4 — Synthesize across sources

After pulling from 3+ sources, synthesize into the research report format in references/synthesis-templates.md. The report includes:

Top themes ranked by frequency × intensity
VOC quote bank organized by theme
Confidence labels on every finding
Source bias notes

Step 5 — Build personas (optional)

Only build personas if you have ≥5 independent data points from a consistent segment. If not, say so and describe what additional research is needed first.

Persona template is in references/synthesis-templates.md.

Questions to ask before starting

Only ask what's genuinely missing. If the product and goal are clear, go. If not, lead with these — one or two at a time, not all at once:

What's the product? (if not obvious from context — a URL works)
What's the goal? Improve messaging? Build personas? Understand churn? Find product gaps?
Who is the target segment? (all customers, a specific tier, churned users, prospects who didn't convert)
What do you already have? (transcripts, surveys, tickets, nothing)
What deliverable do you need? (synthesis report, quote bank, persona, competitive language comparison)

Deliverables

Ask which one(s) the user needs before generating:

Deliverable	When to use
Research synthesis report	General intelligence gathering — themes, quotes, implications
VOC quote bank	Copy projects — verbatim customer language organized by theme
Persona document	ICP definition work, onboarding, sales training
Jobs-to-be-done map	Product prioritization, messaging architecture
Competitive language comparison	Positioning work — how customers describe you vs. competitors
Research gap analysis	When the user has partial data and wants to know what's missing

Download now (ZIP)

Other versions65 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 65
coreyhaines31/marketingskills★ 58ksame name
anthropics/knowledge-work-plugins★ 34ksame name
Nexus-JPF/note-companion★ 870same name
vercel-labs/marketing-team-eve-template★ 459same name
Cesarjoquin/Marketing-Skills★ 190same name
LOGIN-TB/claude-skills★ 80same name
open-fox/agents★ 55same name
Infinite-Labs-AI/infinite-skills★ 43same name
rainday/smart-blog-skills★ 35same name
SZcalligrapher/slash-skills-subscription★ 32same name
55 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
Used alongsideProjects with it also use popups, free-tools and 10 more.
Other files people use alongside this one.
- CesarjoquinSkill
  popups
  When the user wants to create or optimize popups, modals, overlays, slide-ins, or banners for conversion purposes. Also use when the user mentions "exit intent," "popup conversions," "modal optimization," "lead capture popup," "email popup," "announcement banner," "overlay," "collect emails with a popup," "exit popup," "scroll trigger," "sticky bar," or "notification bar." Use this for any overlay or interrupt-style conversion element. For forms outside of popups, see cro. For general page conversion optimization, see cro.
  Also in 22 projects that use this
- CesarjoquinSkill
  free-tools
  When the user wants to plan, evaluate, or build a free tool for marketing purposes — lead generation, SEO value, or brand awareness. Also use when the user mentions "engineering as marketing," "free tool," "marketing tool," "calculator," "generator," "interactive tool," "lead gen tool," "build a tool for leads," "free resource," "ROI calculator," "grader tool," "audit tool," "should I build a free tool," or "tools for lead gen." Use this whenever someone wants to build something useful and give it away to attract leads or earn links. For downloadable content lead magnets (ebooks, checklists, templates), see lead-magnets.
  Also in 23 projects that use this
- coreyhaines31Skill
  marketing-council
  When the user wants multiple expert perspectives on a marketing question — a simulated board of advisors staffed by legendary marketers (Seth Godin, David Ogilvy, Eugene Schwartz, April Dunford, Rory Sutherland, Alex Hormozi, Byron Sharp, and more). Also use when the user mentions 'marketing council,' 'board of advisors,' 'advisory board,' 'what would Seth Godin say,' 'what would Ogilvy think,' 'channel Hormozi,' 'get multiple perspectives,' 'debate this,' 'have the council review,' 'marketing mentors,' or asks how a famous marketer would approach their problem. The council gives each advisor's take through their documented frameworks, surfaces where they disagree, and synthesizes a recommendation. For executing the winning direction, hand off to positioning, offers, copywriting, ads, or the relevant skill.
  Also in 18 projects that use this
- ukunal91appSkill
  community-marketing
  Build and leverage online communities to drive product growth and brand loyalty. Use when the user wants to create a community strategy, grow a Discord or Slack community, manage a forum or subreddit, build brand advocates, increase word-of-mouth, drive community-led growth, engage users post-signup, or turn customers into evangelists. Trigger phrases: "build a community," "community strategy," "Discord community," "Slack community," "community-led growth," "brand advocates," "user community," "forum strategy," "community engagement," "grow our community," "ambassador program," "community flywheel.
  Also in 36 projects that use this
- pixelswithblissSkill
  co-marketing
  When the user wants to find co-marketing partners, plan joint campaigns, or brainstorm partnership opportunities. Use when the user says 'co-marketing,' 'partner marketing,' 'joint campaign,' 'who should we partner with,' 'integration marketing,' 'cross-promotion,' 'collaborate with another company,' 'partnership ideas,' or 'co-brand.' For customer referral programs, see referral-program. For launch-specific partnerships, see launch-strategy.
  Also in 23 projects that use this
- timruebenachSkill
  competitor-profiling
  When the user wants to research, profile, or analyze competitors from their URLs. Also use when the user mentions 'competitor profile,' 'competitor research,' 'competitor analysis,' 'profile this competitor,' 'analyze competitor,' 'competitive intelligence,' 'competitor deep dive,' 'who are my competitors,' 'competitor landscape,' 'competitor dossier,' 'competitive audit,' or 'research these competitors.' Input is a list of competitor URLs. Output is structured competitor profile markdown files. For creating comparison/alternative pages from profiles, see competitor-alternatives. For sales-specific battle cards, see sales-enablement.
  Also in 24 projects that use this
- +5 more from Cesarjoquin
In this repository31 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- ad-creative-generationSkill
- amazon-adsSkill
- analytics-insightsSkill
- blog-generationSkill
- brand-contextSkill
- cold-email-outreachSkill
- competitor-intelSkill
- email-lifecycleSkill
- gmailSkill
- google-adsSkill
- google-sheetsSkill
- hyper-cliSkill
- image-generationSkill
- instagramSkill
- linkedinSkill
- meta-ads-librarySkill
- meta-adsSkill
- openai-adsSkill
- pinterest-adsSkill
- reddit-adsSkill
- redditSkill
- seo-researchSkill
- slackSkill
- snapchat-adsSkill
- tiktok-adsSkill
- tiktokSkill
- twilioSkill
- video-generationSkill
- youtubeSkill

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free