If you ship comparison or alternatives pages with agents, the first place QA breaks is almost never the draft copy. It is the research underneath: a tier renamed last quarter, pricing pulled from a forum thread, or two official pages that disagree and got averaged into one “fact.” A competitor research skill fixes that by turning research into a versioned, cited research packet and entity registry that downstream schema and draft skills consume, instead of every stage re-scraping the same pair with different rules.
Anthropic’s Agent Skills documentation describes skills as reusable instruction files with explicit inputs, behavior, and tests, the same contract comparison pipelines need at stage one. Buyers evaluating BOFU pages expect citations they can audit; G2’s buyer-research guidance treats sourced comparisons as table stakes, not polish. When research is structured once and replayed by packet ID, legal and brand review can focus on judgment calls, not rediscovering URLs.
TL;DR
- A competitor research skill outputs a cited research packet and entity rows, not markdown prose alone.
- Use the Competitor research skill anatomy: inputs, rules, output schema, eval hooks.
- Allowlist primary sources; reject forum tier claims without doc URLs.
- Feed generate comparison pages ai agents and comparison page skill stages from one packet ID.
- Pin versions per version marketing workflows.
Start with one competitor pair
Before you wire a grid of fifty comparisons, run one pair end to end. I treat this like a unit test for judgment: if the skill cannot produce a defensible packet for a single A-vs-B, scaling triggers will only multiply noise.
- Pick one pair that matters to your ICP (not the easiest vendors on the internet, pick one where tiers and packaging actually confuse buyers).
- Run the competitor research skill with a minimal `dimensions[]` set (features, support, deployment is enough for a first pass).
- Open the packet JSON and inspect `facts[]` first: every row should have `source_url` and `captured_at`. Scan `entities[]` for tier names that match official wording, not marketing nicknames.
- If tier or pricing rows cite a domain outside your allowlist, that is a skill bug, not a data quirk, extend rules or the allowlist, then rerun.
- Run golden tests for that pair (expected fact count, forbidden domains) before you attach the skill to stage one of a workflow.
- Log the packet ID on the workflow run so when entity lock fails in draft QA, you can trace backward in minutes.
Short loops beat open-ended scraping. You are validating the contract (sources, schema, eval), not “doing research” in the abstract.
What a competitor research skill produces
Think of the skill as an evidence locker and your draft agent as the storyteller. The storyteller should arrange and explain; it should not raid the open web for tier facts because that is how research and draft diverge. The skill’s job is structured evidence for BOFU pages: downstream schema and draft skills read JSON; they do not re-scrape ad hoc.
The table below maps each artifact to who consumes it and why it exists, use it when scoping your first skill file.
| Output | Purpose | Downstream consumer |
|---|---|---|
| Research packet | Claims + URLs + dates | Schema builder |
| Entity registry | Normalized names/tiers | Draft + QA skills |
| Gap list | Missing facts for human fill | Editor queue |
| Freshness metadata | Chunk ages | Monitor job |
A research packet is the cited bundle of claims your comparison schema expects. An entity registry holds canonical product IDs and tier labels so “Pro” in a draft cannot drift from “Business” on the trust center. Freshness metadata tells monitors when to invalidate a packet before you republish stale pricing. Together, these outputs close the intent gap most tutorials skip: they define the schema downstream stages actually consume, not a prose summary that another agent reinterpreted.
Competitor research skill anatomy
The Competitor research skill anatomy is the named framework I use to keep research skills aligned with how we already encode marketing agent skills: inputs, rules, output schema, and eval hooks in one versioned file. Splitting those blocks lets SEO, product marketing, and GTM engineering own their slice without forking the whole skill.
What inputs does competitor research need per pair?
Inputs tell the agent what “done” means for this run. Typical keys include `competitor_a`, `competitor_b`, `icp_segment`, `source_allowlist[]`, `max_packet_age_days`, `dimensions[]` (features, support, deployment), and `risk_tier`. `dimensions[]` is how you reuse one skill for comparison pages versus alternatives lists without rewriting the skill, only the parameter set changes. `max_packet_age_days` is your freshness knob: BOFU claims on pricing and tiers should fail the packet when evidence is too old to defend in review.
Which source and entity rules are non-negotiable?
Rules encode policy, not suggestions. Primary docs and trust centers beat review aggregators for tier names; every fact row requires `source_url`; tier strings must match trust-center wording; when two sources disagree, you populate `conflicts[]` instead of blending them into a single row. That last point is where “research” differs from SEO copywriting, you are not picking the convenient answer; you are surfacing the fork for a human merge.
What schema should research packets emit?
Emit versioned JSON: `facts[]`, `entities[]`, `conflicts[]`, `retrieved_at`. No orphan claims without URLs. Shape drift (silent missing keys) is what breaks schema builders; versioning the schema in the skill file lets downstream skills fail fast instead of publishing half-structured rows.
How do eval hooks validate research quality?
Golden pairs assert expected fact counts and forbidden source domains. Wire those hooks into the same discipline you use for marketing skill evaluation: promote a skill tag only when the eval set passes, not when a single demo looked fine.
| Block | Owner | Updates when |
|---|---|---|
| Allowlist | SEO lead | New vertical |
| Dimensions | Product marketing | SKU change |
| Schema | GTM engineer | New CMS field |
| Eval set | Ops | Competitor rebrand |
When a competitor rebrands tiers, update the eval set before you update copy, otherwise golden tests green-light stale entity rows.
Source and entity rules
Most “allowlist and freshness” advice stays abstract until something breaks in production. Production competitor research skill files usually encode the following, treat them as BOFU substantiation rules, not general scraping hygiene.
- Allowlist tiers: Official docs, trust centers, release notes, and public cost pages (with capture date), not anonymous forums for tier facts.
- Entity normalization: Map marketing names to canonical product IDs used in schema rows so entity lock in draft QA is comparing apples to apples.
- Conflict policy: Surface dual URLs and pause for human merge, do not pick randomly or average contradictory pricing pages.
- Freshness: Fail the packet when critical dimensions exceed `max_packet_age_days` so monitors and editors get a hard signal.
- PII and ethics: No scraping behind login walls without legal approval.
Allowlist means the skill refuses to attach certain fields (especially tier and price) to domains you did not pre-approve. Entity normalization is the step competitors skip: without it, comparison drafts look fine while QA fails because “Enterprise” in prose never matched the registry.
Worked failure: forum tier name
Here is a failure we see when teams treat a scrape prompt as a competitor research skill. A packet pulled a tier label from a forum thread because it was the fastest string match. The comparison draft passed tone checks; entity lock failed later because the registry expected the trust-center tier name. Reviewers initially blamed the draft skill, until someone traced the bad tier to the packet ID in workflow logs. Without that ID, debug would have stayed in the wrong layer.
Why it happened: tier fields had no allowlist enforcement. How it surfaced: entity mismatch at draft QA, not at research time. What we changed: a research skill rule blocking non-allowlisted domains for tier fields, plus a golden test that fails forum-only tier claims. The broader lesson: research QA belongs at the packet layer; draft QA should not rediscover missing URLs or rogue tier names.
Dimension templates by page type
The same competitor research skill can serve comparison, alternatives, and use-case support pages if you parameterize `dimensions[]`. The table helps you pick minimum fact counts before you turn on triggers at scale.
| Page type | Typical dimensions | Minimum facts |
|---|---|---|
| Comparison pair | Features, support, deployment, integrations | 12+ cited rows |
| Alternatives list | Category fit, ICP band, migration notes | 8+ per vendor |
| Use case support | Workflow steps, tools used | 6+ proof URLs |
Authors pick the template in workflow parameters; the skill enforces row shape so schema builders do not parse prose. Ops teams should treat packet quality as the first QA gate, when packets pass, draft QA focuses on tone and structure, not archaeology.
Run one pair end to end before you attach triggers to a whole competitor grid. Fix allowlist gaps early, promote the skill tag only after golden pairs pass, then scale with the same packet contract so BOFU pages stay auditable under legal and brand review.
Golden tests for research skills
Golden tests are how you keep a competitor research skill honest after the first successful demo. Build a set of 8, 12 competitor pairs: stable incumbents, a recent rebrand, sparse public docs, and at least one regulated category if you serve one.
| Case | Expected |
|---|---|
| Well-documented pair | Pass with N facts |
| Forum-only tier claim | Fail allowlist |
| Conflicting cost pages | `conflicts[]` populated |
| Stale cached doc | Fail freshness |
Hold out cases for regression. Block promotion when pass rate drops without owner review, a regression case should fail loudly when someone loosens allowlist rules to “unblock” a launch.
Packet schema snapshot
If you are wiring schema or QA skills, this snapshot shows which arrays matter and which downstream lock consumes them.
| Array | Row fields | QA consumer |
|---|---|---|
| facts[] | claim, source_url, captured_at | Citation lock |
| entities[] | canonical_name, tier, product_id | Entity lock |
| conflicts[] | claim, url_a, url_b | Human merge |
| gaps[] | dimension, note | Editor queue |
Version the schema in the skill file so downstream skills fail fast on shape drift, not on silent missing keys. Citation lock and entity lock are only as good as the packet they reference; that is why packet IDs belong in workflow logs.
Maintenance checklist
Skills rot when competitors change packaging faster than your eval set. Keep this checklist next to the tag owner in your ops registry:
- Refresh allowlist when entering a new vertical.
- Add golden pair when a competitor rebrands tiers.
- Log packet IDs on workflow runs for debug.
- Pair skill promotion with comparison QA rubric bumps.
Wire research into comparison workflows
Stage one of comparison and generate alternatives pages ai agents pipelines should call the same research skill with different dimension sets, one research contract, many page types.
``` Trigger → competitor research skill → packet ID → schema skill → draft skills ```
Store packet IDs in workflow logs. Never let draft agents browse the open web without the same allowlist rules; if research and draft use different source policies, you will ship pages that look cited but are not reproducible.
Ops teams that reuse packets shrink time-to-publish and make QA deterministic: reviewers audit facts once at the packet layer. When I encode allowlists and entity maps in skills instead of engineer headcanon, that judgment compounds, each promotion is tested, pinned, and traceable.
The friction you feel when a comparison page breaks in QA is often debug fatigue. You reset context every campaign because research lived in chat threads, not in versioned skills. When operator judgment lives in a competitor research skill with golden eval and stable JSON, discovery and execution stay in one growth system. Research produces a packet ID; schema and draft stages inherit the same evidence; you can trace a bad claim to the exact run. That is the handoff we built Metaflow for: explore pairs quickly, solidify what worked into pinned skills and workflows, and log enough context that the next reviewer is not starting from zero.
Frequently Asked Questions About Building a Competitor Research Skill
What is a competitor research skill?
A competitor research skill is a versioned instruction file that gathers competitor facts into a cited research packet and entity registry for downstream pSEO stages, with allowlisted sources and explicit conflict handling instead of ad hoc browsing.
How is a competitor research skill different from a scrape prompt?
A scrape prompt returns one-off text; the skill emits schema-valid JSON, enforces allowlists, and includes eval hooks. Metaflow workflows invoke it by tag so comparison runs replay the same research contract instead of improvising sources per page.
What outputs should a competitor research skill emit?
At minimum, a research packet (claims with URLs and dates), normalized entities, freshness metadata, and optional `gaps[]` and `conflicts[]` arrays for editors, structured for schema and draft skills, not pasted as raw markdown alone.
How do you test a competitor research skill?
Use golden competitor pairs with expected pass/fail, minimum fact counts, and forbidden domains; rerun the set on every tag promotion. Metaflow can run those tests against a candidate skill version before you update the production pin.
Where does competitor research sit in pSEO workflows?
It is the first stage after trigger intake in comparison, alternatives, and related BOFU pipelines. Packet IDs flow to schema and draft stages, and Metaflow traces show which skill version produced the facts when QA flags an entity mismatch.
