Seo Implementer

---
name: seo-implementer
description: >
  SEO fix file generator. Reads the audit-actions.json produced by seo-geo-audit and generates
  ready-to-deploy fix files: rewritten meta tags, JSON-LD schema blocks, robots.txt corrections,
  .htaccess redirects, optimized content snippets, and an implementation checklist.
  Use this skill for: "generate the fixes", "create the schema markup", "write the meta tags",
  "implement the audit recommendations", "generate the corrections", "build the JSON-LD",
  "fix the SEO issues", "create the redirect rules", "deploy the audit fixes",
  "génère les corrections", "implémente les recommandations".
  Also triggers when the user has just completed an audit with seo-geo-audit and asks for next steps,
  or when audit-actions.json exists in the project folder.
---

# Skill: SEO Implementer — Audit-to-Fix File Generator

All responses and files are produced **in English by default**. Switch to the user's language if they explicitly request it.

---

## Overview

This skill is **Step 3** in the SEO-GEO pipeline. It reads the structured output from the audit and generates concrete, copy-paste-ready fix files.

### Position in the pipeline

```
[seo-collector] → site-data.json
                       ↓
[seo-geo-audit] → audit-report.md + audit-actions.json
                       ↓
             ┌─────────────────────────┐
             │  SEO IMPLEMENTER (this) │
             └─────────────────────────┘
                       ↓
                    fixes/
                       ↓
              [seo-monitor]
```

### What it produces

```
seo-project-[domain]/
└── fixes/
    ├── meta-tags.html              ← Rewritten title + meta description per page
    ├── schema-organization.json    ← Organization/LocalBusiness JSON-LD block
    ├── schema-faq.json             ← FAQPage JSON-LD blocks
    ├── schema-products.json        ← Product/Offer JSON-LD blocks (if e-commerce)
    ├── schema-breadcrumb.json      ← BreadcrumbList JSON-LD
    ├── robots-txt-patch.txt        ← Lines to add/modify in robots.txt
    ├── redirects.htaccess          ← Redirect rules (Apache) or redirects.conf (Nginx)
    ├── redirects-vercel.json       ← Redirect rules (Vercel/Next.js format)
    ├── content-rewrites.md         ← Optimized content snippets per page
    ├── implementation-checklist.md ← Step-by-step deployment guide
    └── verification-tests.md       ← Post-deployment verification steps
```

---

## Step 0: Load inputs

### Required input
- **`audit-actions.json`** — produced by `seo-geo-audit` Step 9. Contains all scored issues with priorities and suggested values.

### Optional inputs
- **`site-data.json`** — from the collector, for additional technical context (CMS detected, current meta tags, robots.txt content)
- **`client-profile.md`** — from shared context, for business info (industry, audience, language)
- **`audit-report.md`** — the human-readable report, for context on recommendations

### If no audit-actions.json exists

Ask the user:
```
I need the audit results to generate fix files.
Would you like me to:
  1. Run the full audit first (triggers seo-geo-audit)
  2. Work from a specific list of issues you provide manually
```

---

## Step 1: Meta tags generation

Read `fixes_needed.meta_tags` from `audit-actions.json`.

For each page with issues, generate optimized tags.

### Rules for meta tag writing

**Title tags:**
- 50–60 characters (hard limit: 60)
- Primary keyword near the beginning
- Brand name at the end, separated by ` | ` or ` — `
- Compelling — should make the user want to click
- Unique per page — no duplicates across the site

**Meta descriptions:**
- 140–160 characters (hard limit: 160)
- Contains a clear value proposition
- Includes a call to action (Discover, Shop, Learn, Get...)
- Contains the primary keyword naturally (not forced)
- Unique per page

**H1 tags:**
- One per page, unique
- Contains the primary keyword
- Clear and descriptive, matches the page content
- Different from the `<title>` (complementary, not identical)

### Output format: `fixes/meta-tags.html`

```html
<!-- ============================================ -->
<!-- META TAGS — Generated by SEO Implementer     -->
<!-- Domain: [domain] | Date: [date]              -->
<!-- ============================================ -->

<!-- PAGE: [URL] -->
<!-- Issue: [issue from audit-actions.json] -->
<!-- Previous title: [current_value or "none"] -->
<title>[New optimized title]</title>
<meta name="description" content="[New optimized description]">
<!-- Recommended H1: [New H1 suggestion] -->

<!-- PAGE: [next URL] -->
...
```

> **AI writing detection**: When writing meta tags and content, read [`ai-writing-detection.md`](../seo-geo-audit/ai-writing-detection.md) to avoid AI writing markers. Meta descriptions should sound natural and human, not formulaic.

---

## Step 2: Schema markup generation

Read `fixes_needed.schema_markup` from `audit-actions.json`.

Generate complete, valid JSON-LD blocks ready to paste into `<head>`.

### 2.1 Organization / LocalBusiness schema

File: `fixes/schema-organization.json`

For General mode, use `Organization`. For Local mode, use `LocalBusiness` (or the specific subtype: `Restaurant`, `MedicalBusiness`, `LegalService`...) and include `address`, `geo`, and `openingHoursSpecification`.

Always include:
- `@context`, `@type`, `name`, `url`, `logo`
- `sameAs` array with all official social profiles
- `contactPoint` with phone and available languages
- For Local: `address` (PostalAddress), `geo` (GeoCoordinates)

### 2.2 FAQPage schema

File: `fixes/schema-faq.json`

For each page that needs a FAQ schema, generate a complete `FAQPage` JSON-LD block with `mainEntity` array of `Question` + `acceptedAnswer` pairs.

> **GEO boost**: FAQPage schema provides +40% AI visibility. If the page doesn't have a FAQ section yet, suggest 3-5 relevant questions based on the industry and page content.

### 2.3 Product / Offer schema (e-commerce)

File: `fixes/schema-products.json`

Only generate if `site-data.json` indicates e-commerce or `client-profile.md` says e-commerce. Include `name`, `description`, `image`, `brand`, `offers` (with `price`, `priceCurrency`, `availability`).

> **Note for Shopify/WooCommerce**: These platforms often inject Product schema via JS. Check `site-data.json` → `schema_markup.reliability` before generating. If reliability is "low" (JS-injected), note in the checklist to verify via Rich Results Test first.

### 2.4 BreadcrumbList schema

File: `fixes/schema-breadcrumb.json`

Generate `BreadcrumbList` JSON-LD with `itemListElement` array, one `ListItem` per level from Home to current page.

---

## Step 3: Robots.txt patch

Read `fixes_needed.robots_txt` from `audit-actions.json`.

File: `fixes/robots-txt-patch.txt`

Generate:
1. Lines to ADD (e.g., unblocking AI bots)
2. Lines to REMOVE or MODIFY (with explanation)
3. A full recommended robots.txt as reference

Always include `Sitemap: https://[domain]/sitemap.xml` at the end.

---

## Step 4: Redirect rules

Read `fixes_needed.redirects` from `audit-actions.json`.

Generate redirect rules in **multiple formats** — detect the platform from `site-data.json` → `cms_detected` and prioritize the matching format, but generate all for portability:

| Platform | File | Format |
|---|---|---|
| Apache | `fixes/redirects.htaccess` | RewriteRule |
| Nginx | `fixes/redirects-nginx.conf` | rewrite ... permanent |
| Vercel / Next.js | `fixes/redirects-vercel.json` | JSON redirects array |
| Shopify | `fixes/redirects-shopify.csv` | CSV (Redirect from, Redirect to) |

Each redirect includes a comment explaining the reason (404, chain redirect, duplicate content).

---

## Step 5: Content optimization snippets

Read `fixes_needed.content` from `audit-actions.json`.

File: `fixes/content-rewrites.md`

For each page flagged with content issues, generate:

1. **Answer-first paragraph** — 2-3 sentences that directly answer the main query this page should rank for. Written in authoritative tone, with at least one statistic or source citation. This is what AI engines will extract and cite.

2. **Suggested FAQ section** — 3-5 relevant Q&A pairs in explicit format. Concise answers (2-3 sentences each), factual, answer-first.

3. **Internal links to add** — Suggested anchor text and target pages to strengthen the internal linking structure.

> **AI writing detection**: Read [`ai-writing-detection.md`](../seo-geo-audit/ai-writing-detection.md) before writing content. Avoid em dashes, "leverage", "robust", "in today's digital age", and other AI markers. Write naturally.

---

## Step 5.5: Analytics tracking fixes

Read `analytics_tracking` from `site-data.json` (collector Step 5.5) and `fixes_needed.technical` from `audit-actions.json`.

File: `fixes/analytics-setup.md`

Only generate this file if the collector detected tracking issues (maturity level "basic" or missing tools).

```markdown
# Analytics Tracking Recommendations — [domain]

## Current state
- Tools detected: [list from site-data.json]
- Maturity level: [basic/intermediate/advanced]
- Issues: [list from collector]

## Recommended setup

### Priority 1: GA4 configuration (if missing or misconfigured)
[GA4 measurement ID setup instructions, adapted to detected CMS]

### Priority 2: Key conversion events to configure
[Based on site type from client-profile.md:]

#### E-commerce sites:
- `add_to_cart` — when user adds item to cart
- `begin_checkout` — when user starts checkout flow
- `purchase` — when order is completed (with value, currency, items)
- `view_item` — when user views a product page

#### Lead generation sites:
- `form_submit` — when contact/quote form is submitted
- `phone_click` — when phone number is tapped on mobile
- `cta_click` — when primary CTA is clicked

#### Content/Blog sites:
- `scroll_depth` — 25%, 50%, 75%, 100% thresholds
- `article_read` — time on page > 30 seconds
- `newsletter_signup` — email subscription

### Priority 3: Consent management (if missing)
[CMP recommendation based on region — Cookiebot/OneTrust for EU/GDPR, generic for US]

### Priority 4: Heatmap/Session recording (if missing)
[Recommend Microsoft Clarity (free) or Hotjar]
```

> **CMS-specific**: Adapt GA4 setup instructions to the detected CMS. Shopify has native GA4 integration. WordPress uses plugins (MonsterInsights, GA4WP). Webflow has built-in GA integration. Custom sites need manual gtag.js injection.

---

## Step 6: Implementation checklist

File: `fixes/implementation-checklist.md`

Generate a step-by-step deployment guide, ordered by priority (🔴 HIGH → 🟡 MEDIUM → 🟢 LOW).

For each action include:
- **What**: precise description
- **File**: which fix file to use
- **Where to deploy**: CMS location, file path, or admin panel section
- **How to verify**: test URL or tool to confirm it works
- **Estimated time**: in minutes or hours
- **Checkbox**: `- [ ] Done`

End with a **post-deployment verification** section:
- Run Google Rich Results Test
- Check robots.txt accessibility
- Verify sitemap validity
- Test each redirect individually
- Check mobile rendering
- Submit updated sitemap in GSC
- Request re-indexing of modified pages

---

## Step 7: Verification tests

File: `fixes/verification-tests.md`

Generate specific test commands/URLs for each fix category:
- **Meta tags**: browser tab check + view-source verification
- **Schema**: Rich Results Test URL + Schema.org Validator
- **Robots.txt**: direct fetch + Google Robots Testing Tool
- **Redirects**: `curl -I` commands with expected Location headers
- **AI bot access**: Brave Search indexation check

---

## Output summary

After generating all files, present a summary:

```
═══════════════════════════════════════════
SEO FIX FILES GENERATED — [domain]
Date: [date]
═══════════════════════════════════════════

📁 Files generated in fixes/:
   ✅ meta-tags.html          — [N] pages with rewritten tags
   ✅ schema-organization.json — Organization/LocalBusiness block
   ✅ schema-faq.json          — [N] FAQ blocks
   ✅ schema-breadcrumb.json   — Breadcrumb trail
   ✅ robots-txt-patch.txt     — [N] bot rules to update
   ✅ redirects.[format]       — [N] redirect rules
   ✅ content-rewrites.md      — [N] pages with content suggestions
   ✅ implementation-checklist.md — Step-by-step deployment guide
   ✅ verification-tests.md    — Post-deployment test plan

📊 Fix summary:
   🔴 High priority: [N] actions
   🟡 Medium priority: [N] actions
   🟢 Low priority: [N] actions

💡 Estimated implementation time: [X] hours total
   Quick wins alone: [Y] hours

Would you like me to:
  1. Walk through the high-priority fixes one by one?
  2. Generate a .docx report of the implementation plan?
  3. Start monitoring with the seo-monitor skill?
```

---

## CMS-specific adaptation

| CMS | Schema method | Redirect method | Notes |
|---|---|---|---|
| WordPress | Yoast/RankMath or `header.php` | `.htaccess` or Redirection plugin | Check existing schema plugins — avoid duplicates |
| Shopify | `theme.liquid` `<head>` or metafields | Admin > Navigation > URL Redirects | May already inject Product schema via JS |
| Webflow | Page settings custom code `<head>` | Project settings 301 Redirects | Native redirect support |
| Wix | Wix SEO tools or Velo custom code | URL Redirect Manager | Limited schema support |
| Next.js | `_document.js` or page `<Head>` | `next.config.js` or `vercel.json` | Use ISR for dynamic schema |
| Static | Direct `<head>` injection | `.htaccess` or `nginx.conf` | Full control |

Always check `site-data.json` → `cms_detected` and adapt deployment instructions.

---

## Best practices

### Do NOT generate
- Schema for pages where it's already correctly present
- Redirects for URLs already returning 200
- Content rewrites for pages that scored well

### Always include
- Comments in every file explaining what and why
- Source audit date and score in file headers
- CMS-specific deployment instructions
- Warning labels on fixes that could break existing functionality

### File encoding
- All files in UTF-8
- JSON must be valid (parseable)
- HTML entities properly escaped in meta tags