SEO Cluster Builder

Skill for building complete, production-ready SEO topic clusters. Each cluster includes: competition research, article content with natural internal links, schema markup per article, SEO meta tags, and a copy-paste–ready HTML output file.

This skill encodes the exact workflow used to build the "Pinata Sinh Nhật" and "Tổ Chức Tiệc Sinh Nhật" clusters for pinata.vn — two real-world clusters that demonstrate the full pattern.

Workflow Overview

PHASE 1 — RESEARCH (always first)
  └── Fetch live site + competitor data
  └── Identify content gaps and keyword angles

PHASE 2 — CLUSTER DESIGN
  └── Choose pillar topic and angle
  └── Map 6–8 cluster articles with intent groups
  └── Design internal link graph

PHASE 3 — CONTENT GENERATION
  └── Write all articles with inline links
  └── Generate schema per article
  └── Write SEO meta tags

PHASE 4 — OUTPUT
  └── Produce single HTML file (copy-paste ready)
  └── Validate all schema JSON + internal links
  └── Generate summary table

Read references/phase1-research.md before starting Phase 1. Read references/phase2-design.md before designing the cluster. Read references/phase3-content.md before writing articles. Read references/phase4-output.md before generating the final file.

Critical Rules (apply to every cluster)

R1 — Research before writing

ALWAYS fetch the client's site and top 3 competitor pages before writing a single word. Never design a cluster based on assumptions.

R2 — Audit existing content first

Search site:[domain] for existing articles on the topic. Flag:

• Cannibalization risk (2+ articles targeting same keyword)
• Redirect opportunities (old thin articles → new pillar)
• Bridge opportunities (existing articles that can link INTO the new cluster)

R3 — Angle selection

Never compete head-on against sites with DA 50+. Always find a specific angle the domain can win:

• Product-specific angle (e.g., "trò chơi tiệc sinh nhật" instead of "tổ chức tiệc sinh nhật")
• Long-tail angle (e.g., "tiệc sinh nhật chủ đề khủng long" instead of "trang trí sinh nhật")
• Local angle (e.g., city-specific landing pages)

R4 — Internal links must be IN the article body

Every article must have ≥ 3 internal links placed naturally within the content — NOT only in a sidebar, footer, or link map note. Validate programmatically before output.

R5 — Schema validation

All JSON-LD blocks must parse as valid JSON before inclusion. Run validation; never output unchecked schema.

R6 — No duplicate content between clusters

When adding a new cluster to a site that already has clusters, check for topical overlap. Add bridge links between clusters; do not rewrite the same content twice.

Cluster Architecture

Standard structure (6–8 articles)

PILLAR (1 article)
│  Intent: Informational overview — answers "what is X" + summarizes all subtopics
│  Word count: 2,000–3,000 words
│  Internal links: OUT to every cluster article (minimum)
│
├── INFORMATIONAL CLUSTER (1–2 articles)
│   Intent: Deep-dive on background, history, "why"
│   Word count: 1,200–1,800 words
│
├── HOW-TO CLUSTER (1–2 articles)
│   Intent: Step-by-step guides
│   Schema: HowTo (required)
│   Word count: 1,500–2,000 words
│
├── COMMERCIAL CLUSTER (1–2 articles)
│   Intent: Price, where to buy, comparison
│   Schema: FAQPage + ItemList
│   Word count: 1,200–1,500 words
│   Note: These articles must link directly to product/service pages
│
└── THEME/LONG-TAIL CLUSTER (2–3 articles)
    Intent: Specific use cases, characters, locations
    Word count: 1,000–1,500 words each
    Note: Highest conversion — user has specific intent

Internal link minimum requirements

Schema Matrix

Each article type requires specific schema blocks:

See references/phase3-content.md for complete schema templates.

Output File Format

The final deliverable is a single HTML file that:

1. Renders in browser — agent/user can preview each article
2. Has a Copy button for each section (meta tags, schema, article body)
3. Contains an audit box at the top flagging pre-existing issues
4. Contains an internal link map per article showing which URLs to link to
5. Contains a summary table at the bottom with publish order

File naming: cluster-[topic-slug].html CSS: Use the shared stylesheet in assets/cluster-style.css (inline into <style> tag)

See references/phase4-output.md for the full HTML template and component library.

Validation Checklist (run before finalising output)

# Pseudo-code — implement with actual Python in bash_tool
for each article:
    assert schema_blocks >= minimum_for_type       # R5
    assert json_valid(all_schema_blocks)           # R5
    assert internal_links_in_body >= 3             # R4
    assert internal_links_not_only_in_ilmap        # R4
    assert pillar_links_to_all_clusters            # architecture
    assert no_city_name_leaks_from_other_cities    # for geo clusters
    assert breadcrumb_present                      # schema matrix
    assert faq_present                             # schema matrix

Quick Reference: Cluster Examples

Full content of these reference clusters is in the session history. When in doubt about format or depth, refer to those examples.