ShipAny Page Builder (Dynamic Pages)

🚨 BLOCKING REQUIREMENTS - Execute in Order

Two modes available:

• Create New Page: Build from scratch with keywords and route
• Optimize Existing Page: Enhance SEO, add sections, improve copy

You MUST complete each checkpoint before proceeding. Do NOT skip any step.

📝 PRE-EXECUTION: Normalize Input

BLOCKING REQUIREMENT: MUST normalize user request into structured input first.

Extract and confirm:

• route: /features/ai-image-generator
• slug: features/ai-image-generator
• keywords: ["AI image generator", "create AI art", ...]
• locale: en (or zh, ja, ko, etc.)
• mode: create-new OR optimize-existing

Confirm by stating: "📝 INPUT NORMALIZED: route={route}, slug={slug}, {N} keywords, locale={locale}, mode={mode}"

Input guide: See references/00-guide.md

✅ CHECKPOINT 1: Load and Validate Keywords

BLOCKING REQUIREMENT: For non-EN pages, MUST load validated keywords FIRST.

For EN pages: Skip to Checkpoint 2

For non-EN pages (zh, ja, ko, etc.):

Read: .claude/skills/i18n-seo-localizer/data/keywords-{locale}.json
# OR: .codex/skills/i18n-seo-localizer/data/keywords-{locale}.json

Extract validated keywords:

• primary → Use in: Title, H1, Meta description
• alternatives → Use in: H2s, body content, FAQ
• semanticVariants, relatedTerms, longTail → Use for diversity

If keyword NOT found in data file:

1. ⛔ STOP - Do not generate with guessed keywords
2. Research using cumulative SERP analysis
3. Add to keywords-{locale}.json
4. Then proceed

Confirm completion by stating: "✅ CHECKPOINT 1 COMPLETE: Loaded validated keywords for {locale}, primary='{keyword}', {N} alternatives"

✅ CHECKPOINT 2: Generate/Optimize Content with SEO Standards

BLOCKING REQUIREMENT: Content MUST follow unified SEO standards.

SEO Standards: See ../_shared/references/seo-standards.md for complete requirements.

Quick requirements:

• Word count: EN 800+, ZH 500+, JA/KO 600+, European 800+
• Keyword density: ZH 2.0-3.0%, EN/European 1.8-2.5%, JA/KO 2.0-2.8%
• H1 rule (one-vote veto): MUST contain primary keyword
• H2 distribution: 2-4 with keywords, primary ≤50%
• H3 distribution: Primary ≤30% (recommended, not blocking)

Generation steps:

1. Generate headings FIRST
   • H1 (1): Must contain primary keyword
   • H2 (2-4): Mix of primary + variants
   • H3 (0-6): Mostly variants
2. Self-verify headings immediately
3. Generate body content (based on verified headings)
4. Create sections (hero, benefits, features, FAQ, CTA)
5. Optimize metadata (title, description)

For new pages: Create multi-locale JSON files

For existing pages: Modify JSON to enhance content

Confirm completion by stating: "✅ CHECKPOINT 2 COMPLETE: Generated {word_count} words, density {X}%, H1 check: pass"

Complete SEO guidelines: See references/02-seo-best-practices.md

✅ CHECKPOINT 3: Run Quality Validation (Gate 0)

BLOCKING REQUIREMENT: MUST run anti-stuffing detection script.

python scripts/check_keyword_quality.py \
  --file {generated_file} \
  --keyword {primary_keyword} \
  --locale {locale}

Checks performed:

• 🚨 H1 contains primary keyword (one-vote veto)
• 🚨 H2 distribution reasonable (2-4 with keywords, primary ≤50%)
• ℹ️ H3 distribution (primary ≤30%, warning only)
• ✅ Keyword spacing ≥ 50 chars (CN) / 200 chars (EN)
• ✅ Paragraph repetition ≤ 1 per paragraph
• ✅ No unnatural patterns ("X是X", "X的X")
• ✅ Readability ≥ 60

If detection fails: Auto-rewrite (max 3 times). Do NOT bypass this check.

Confirm completion by stating: "✅ CHECKPOINT 3 COMPLETE: Quality check passed, exit code 0"

✅ CHECKPOINT 4: Register Page and Update Config

BLOCKING REQUIREMENT: For new pages, MUST register path and update configs.

For new pages:

1. Register message path:

   bashCopy

   python scripts/create_dynamic_page.py {slug} {locale}
   

   OR manually update src/config/locale/index.ts

2. Update sitemap config: Add entry to src/config/sitemap-config.ts See references/05-sitemap-config.md

3. Configure internal linking (for L2+ pages): Update internal-links.json for navigation See references/07-internal-linking.md

For existing page optimization:

• Update sitemap-config.ts localeLastmod to today

Confirm completion by stating: "✅ CHECKPOINT 4 COMPLETE: Registered path, updated sitemap and internal links"

✅ CHECKPOINT 5: Validate Build

BLOCKING REQUIREMENT: Build MUST pass without errors.

pnpm build

Confirm completion by stating: "✅ CHECKPOINT 5 COMPLETE: Build passed successfully"

If build fails: Fix errors and rebuild. Do NOT mark complete until build passes.

📋 Quick Reference

Edit Scope:

• ✅ Create/modify: Page JSON files, locale index, sitemap config
• ❌ Do NOT touch: Theme blocks, core components, shared utilities, images in public/

Safety Constraints:

• Only use placeholder images in JSON
• Preserve existing functionality when optimizing
• Do NOT remove functional sections without user approval

Content Exclusions:

• ❌ Do NOT include: metadata.keywords, footer.friendLinks, backlinks

i18n Development (CRITICAL): Always use explicit locale in getTranslations():

// CORRECT
const t = await getTranslations({ locale, namespace: 'pages.xxx' });

See references/04-i18n-best-practices.md

🔄 Complete Workflow Documentation

Input Guide: references/00-guide.md Validation Checklist: references/01-checklist.md SEO Best Practices: references/02-seo-best-practices.md i18n Development: references/04-i18n-best-practices.md Sitemap Config: references/05-sitemap-config.md SEO Quality Pipeline: references/06-seo-quality-pipeline.md Internal Linking: references/07-internal-linking.md

🆚 Skill Boundaries

Last Updated: 2026-02-03