Listicle Generator Agent Skill

Listicle Generator

Write "Top N Best [Category]" roundup articles that rank on Google, capture featured snippets, and drive affiliate conversions across multiple products. Each list entry is a self-contained mini-review with features, pricing, pros/cons, audience fit, and a CTA. The article is structured to win both the featured snippet and the "People Also Ask" box.

When to Use

• User wants to cover an entire product category with multiple affiliate links
• User says "best", "top", "roundup", "list of", or mentions a number with a category
• User wants to capture high-volume generic keywords ("best email marketing tools") vs. specific product searches
• User has multiple affiliate programs in the same category and wants one article to cover them all
• User wants an article format that benefits from regular updates (add/remove products as market evolves)

Workflow

Step 1: Determine List Parameters

Parse the user's request for:

• Category: what type of product (e.g., "email marketing tools", "AI video generators")
• List size (N): explicitly stated number, or auto-select based on category depth
• Niche/specialized categories: 5-7 products
• Broad/competitive categories: 7-10 products
• Very broad (e.g., "project management tools"): 10-12 products
• Target audience: inferred from category + any context clues (beginners, enterprises, specific industries)
• Year: always use current year in the title for freshness signal

If no affiliate product is specified:

• Ask: "Which product are you promoting? I'll feature it prominently in the list."
• If user says to proceed anyway, generate a balanced list and note where they should insert their affiliate link.

Step 2: Research the Product Landscape

Use web_search to build the product list:

• Seed query: "best [category] tools [year]" site:g2.com OR site:capterra.com OR site:trustradius.com
• Validate with traffic: "best [category]" — check autocomplete for common phrasings
• Find affiliate programs: "[category] affiliate program" — identify which products offer commissions

For each candidate product, gather:

• Product name and one-line description
• Starting price and free plan availability
• G2/Capterra rating (if available)
• The one thing it does best (unique angle)
• Who it's primarily designed for

Affiliate prioritization rules:

• Position the user's affiliate product at #1 or #2 (never lower than #3 unless it genuinely cannot be defended in the top 3)
• #1 position gets the most clicks — use it for the highest-commission or best-converting product
• If the user has multiple affiliate programs, spread them in positions 1, 2, and 4
• Non-affiliate products fill the remaining slots to make the list credible and balanced

Step 3: Plan the Article Structure

Map out every section before writing:

Article structure:

• Title (with year, number, category)
• FTC disclosure
• Introduction (150-200 words)
• "At a Glance" summary table
• Evaluation criteria (H2)
• Individual product entries × N (H2 each)
• Comparison table (all products × key dimensions)
• How to Choose (H2)
• FAQ (H2)

10. Final Recommendation (H2)

Per-entry structure (400-600 words each):

• H2: [Rank]. [Product Name] — [One-line Value Prop]
• Opening paragraph: what it is, who made it, why it's on this list
• Key features section (3-5 bullet points)
• Pricing table (free / starter / pro / enterprise)
• Pros list (4-5 bullets)
• Cons list (2-3 bullets — be honest, builds trust)
• Best for: one sentence naming the ideal user
• Affiliate CTA button: Try [Product] free →

Step 4: Write the Full Article

Title formula: [N] Best [Category] Tools in [Year] (Ranked and Reviewed)

Alternative: Best [Category] Software: Top [N] Picks for [Year]

Introduction (150-200 words):

• Open with the core problem this category solves
• Mention how many tools you evaluated and your selection criteria
• Name-drop 2-3 products from the list to signal comprehensiveness
• End with a transition: "Here are the [N] best options I found."

"At a Glance" Table (immediately after intro, captures featured snippet):

| Tool | Best For | Starting Price | Free Plan |
|---|---|---|---|
| [Product 1] | [Use case] | $X/mo | ✅ |
| [Product 2] | [Use case] | $Y/mo | ❌ |

Evaluation Criteria (H2, before the list):

List the 4-6 criteria used to rank products. This builds credibility and explains why your #1 pick is #1.

Example criteria: ease of use, feature depth, pricing value, customer support quality, integration ecosystem, scalability.

Individual Product Entries:

Write each entry following the per-entry structure above. Vary the opening sentence — don't start every entry the same way. Include specific, verifiable details (actual feature names, real pricing tiers, concrete limitations) — not generic praise.

Master Comparison Table:

After all product entries, include a comprehensive feature matrix:

| Feature | [P1] | [P2] | [P3] | [P4] | [P5] |
|---|---|---|---|---|---|
| Free plan | ✅ | ❌ | ✅ | ⚠️ | ✅ |
| [Key feature] | ✅ | ✅ | ❌ | ✅ | ❌ |
| [Key feature] | ⭐ Best | Good | Limited | Good | Basic |
| Starting price | $X | $Y | $Z | $A | Free |

How to Choose (H2, 300-400 words):

A decision framework for readers who are still unsure after reading the list:

• "If you're a beginner with a tight budget → [Product X]"
• "If you need [specific feature] → [Product Y]"
• "If you're scaling a team → [Product Z]"
• "If you're migrating from [common competitor] → [Product A]"

FAQ Section (5-7 questions):

• "What is the best [category] tool?"
• "What is the cheapest [category] tool?"
• "What [category] tool has the best free plan?"
• "Is [top product] worth it?"
• "How do I choose [category] software?"

Final Recommendation (H2):

• Restate the #1 pick with a 2-sentence reason
• Give a backup pick for a different audience
• Strong CTA: Start with Product] — it's free to try. [Get started →

Step 5: Format Output

Part 1: SEO Metadata

---
SEO METADATA
---
Title: [title with year and number]
Slug: best-[category-slug]-tools
Meta Description: [150-160 chars, include number + year + top product name]
Target Keyword: best [category] tools
Secondary Keywords: [category] software, [product 1] review, [product 2] alternatives, top [category] [year]
Word Count: [actual]
Format: listicle
Products: [N]
---

Part 2: Full Article

Complete markdown ready to publish.

Part 3: Supplementary Data

• FAQ questions for schema markup
• Image suggestions (product screenshots, comparison screenshots)
• All products with affiliate URLs flagged
• Update reminder: "This article should be refreshed every 6 months to keep rankings."

Input Schema

category:                   # REQUIRED — product category to cover
  name: string              # e.g., "AI video generators", "email marketing platforms"
  tags: string[]            # Optional — helps with research targeting

primary_product:            # OPTIONAL but recommended — the affiliate product to feature at #1
  name: string
  description: string
  reward_value: string
  url: string               # Affiliate link
  reward_type: string
  cookie_days: number
  tags: string[]

additional_affiliates:      # OPTIONAL — other affiliate products to include in the list
  - name: string
    url: string
    reward_value: string

list_size: number           # OPTIONAL — how many products (5-12). Default: auto-select.

target_audience: string     # OPTIONAL — "beginners" | "enterprise" | "freelancers" | "agencies"
                            # Default: inferred from category

year: number                # OPTIONAL — year for title/freshness. Default: current year.

target_keyword: string      # OPTIONAL — override default keyword
tone: string                # OPTIONAL — "conversational" | "professional". Default: "conversational"

Step 6: Self-Validation

Before presenting output, verify:

• [ ] FTC disclosure appears before product entries
• [ ] "At a Glance" table present with Tool/Best For/Price/Free Plan columns
• [ ] Primary affiliate product ranked #1-3 (never buried lower)
• [ ] Each entry has: key features, pricing, pros, cons, "best for" sentence
• [ ] Title includes current year for recency signal

If any check fails, fix the output before delivering. Do not flag the checklist to the user — just ensure the output passes.

Output Schema

output_schema_version: "1.0.0"  # Semver — bump major on breaking changes
article:
  title: string
  slug: string
  meta_description: string
  target_keyword: string
  format: "listicle"
  content: string
  word_count: number
  product_count: number

products_featured:
  - name: string
    url: string
    rank: number            # Position in the list (1 = top)
    role: string            # "affiliate-primary" | "affiliate-secondary" | "editorial"
    reward_value: string

seo:
  secondary_keywords: string[]
  at_a_glance_table: string   # Markdown table — can be extracted for featured snippet
  faq_questions:
    - question: string
      answer: string
  image_suggestions:
    - description: string
      alt_text: string
      placement: string

update_schedule:
  recommended_frequency: string   # "every 6 months" for most categories
  items_to_check: string[]        # What to verify on next update

Output Format

Present as three sections:

• SEO Metadata — fenced block for copy-paste into blog CMS
• Article — full markdown, immediately publishable
• Supplementary — FAQ schema, image suggestions, affiliate URLs, update notes

Target word count: 3,000-5,000 words depending on list size (aim for 400-500 words per product entry plus structural sections).

Error Handling

• No category provided: "What category of products should this listicle cover? For example: 'best email marketing tools' or 'top AI writing assistants'."
• No affiliate product specified: Generate a balanced editorial list. Flag in output: "Affiliate link not set — insert your tracking URL for [top pick] before publishing."
• Category too broad ("best software"): Narrow it. Ask: "That's very broad — can you narrow it down? For example: 'best project management software for small teams'."
• Category too niche (fewer than 5 good products exist): Reduce list size and be transparent: "Only 5 strong options exist in this niche — I've included all of them."
• Product research returns low-quality results: Use web_search with 3 different query variations before giving up. Fallback: base entries on official product pages + G2 reviews.

Examples

Example 1: Standard category listicle

User: "Write a top 10 best AI video tools article"

Action: category="AI video generators", list_size=10, research top tools, position user's affiliate at #1, write 4,500-word listicle targeting "best ai video tools [year]".

Example 2: Niche with specific audience

User: "Best email marketing tools for e-commerce, I'm promoting Klaviyo"

Action: category="email marketing for e-commerce", primary_product=Klaviyo, target_audience="e-commerce store owners", list_size=7, write article with Klaviyo at #1.

Example 3: Alternatives format

User: "Write a 'best alternatives to Mailchimp' article"

Action: Treat as listicle where Mailchimp is the incumbent being replaced. Title: "7 Best Mailchimp Alternatives in [Year] (Cheaper + More Powerful)". Position user's affiliate at #1 as top alternative.

Example 4: Chained from S1

User: "Now write a roundup post for the category"

Context: S1 returned Semrush in the SEO tools category

Action: category=SEO tools, primary_product=Semrush, auto-select list_size=8, write "Best SEO Tools [year]" with Semrush at #1.

References

• shared/references/ftc-compliance.md — FTC disclosure text. Read before Step 4.
• shared/references/affiliate-glossary.md — Terminology reference.
• shared/references/flywheel-connections.md — master flywheel connection map

Flywheel Connections

Feeds Into

• landing-page-creator (S4) — featured products for landing pages
• content-pillar-atomizer (S2) — listicle as pillar content to atomize
• internal-linking-optimizer (S6) — new listicle needs internal links

Fed By

• affiliate-program-search (S1) — recommended_program as primary product
• keyword-cluster-architect (S3) — commercial intent clusters for listicle topics

Feedback Loop

• seo-audit (S6) tracks listicle rankings → identify which list formats and sizes rank best

Quality Gate

Before delivering output, verify:

• Would I share this on MY personal social?
• Contains specific, surprising detail? (not generic)
• Respects reader's intelligence?
• Remarkable enough to share? (Purple Cow test)
• Irresistible offer framing? (if S4 offer skills ran)

Any NO → rewrite before delivering.

chain_metadata:
  skill_slug: "listicle-generator"
  stage: "blog"
  timestamp: string
  suggested_next:
    - "landing-page-creator"
    - "content-pillar-atomizer"
    - "internal-linking-optimizer"