---
name: marketing-docs-seo-rewriter
description: Audit and rewrite product marketing pages, application documentation, developer docs hubs, self-hosting pages, screenshots pages, FAQs, dashboards/data-heavy product pages, and public documentation for clear conversational positioning, human tone, SEO intent, internal linking, structured metadata, visual proof, dense-information usability, and accessible output. Use when the user asks to apply marketing/article learnings to a site, improve product messaging, simplify technical product copy, humanize AI-sounding copy, run an SEO sweep, restructure marketing/docs pages, improve dense dashboard or complex application presentation, fix contrast/readability issues, improve keyboard or screen-reader usability, or maintain a reusable plan for future marketing content sources.
---

# Marketing Docs SEO Rewriter

## Overview

Use this skill to turn product marketing and documentation into clear, search-friendly, accessible, user-centered pages. Keep the public copy conversational: explain what users can do and why it helps before using technical terms.

## Core Rules

- Start from the audience, job, and decision point for each page.
- Use source articles as reusable marketing guidance, not as copy to paste.
- Keep planning notes and article analyses local or ignored unless the user explicitly asks to publish them.
- Verify claims against the product repo, README, release notes, screenshots, or current docs before changing public copy.
- Prefer plain user language over internal product architecture words.
- On marketing and overview pages, use SVGs, diagrams, screenshots, or other images as the main way to explain content when a visual can do so clearly. Limit the supporting copy for each visual content block to two sentences.
- Write precise copy with familiar words. Name the actions people take and the outcomes they want, such as "filter failed payments and retry them," instead of abstract claims such as "optimize revenue operations."
- Make copy sound like someone who knows the product and reader; replace hype and generic claims with specific, verifiable details.
- Use screenshots and captions as proof of what the product actually does.
- For dashboards, admin consoles, analytics, reporting, monitoring, or other data-heavy products, evaluate whether the public copy, docs, and screenshots prove dense workflows are learnable, flexible, efficient, and safe.
- Treat SEO, accessibility, routing, and contrast as part of the rewrite, not a separate afterthought.
- Account for people using keyboards, screen readers, zoom, high contrast settings, reduced motion, low vision support, and plain-language scanning.
- Do not rely on color, position, animation, screenshots, or icons alone to communicate essential information.

## Workflow

1. **Collect context**
   - Read the existing public pages, docs, sitemap, style system, screenshots, README, and app release/source docs relevant to the product.
   - Read brand voice samples, founder notes, support docs, customer language, changelogs, or existing strong pages when available.
   - Look for existing accessibility patterns, such as landmarks, skip links, focus styles, form labels, alt text conventions, and reduced-motion support.
   - For application or developer documentation, read `references/application-documentation-patterns.md`.
   - For dashboards, data tables, admin consoles, analytics, reporting, monitoring, workflow builders, or other dense application surfaces, read `references/dense-data-application-patterns.md`.
   - If the user provides an article URL or asks to use outside learnings, browse it, extract reusable lessons, cite it in the final answer, and avoid long copied text.
   - Read `references/source-learning-log.md` for prior source lessons. When using a new article, also read `references/article-intake.md`.

2. **Create or update a local plan**
   - Make a page inventory with audience, search intent, page job, documentation presentation model, dense-data proof needs when relevant, value promise, CTA, next step, and accessibility risks or assistive-technology needs.
   - If the repo has a local/git-ignored planning folder, use it. If not, create one only when appropriate and add it to `.gitignore`.
   - Keep internal plans, progress notes, and source analyses out of public docs unless the user explicitly wants them public.

3. **Rewrite consistently**
   - Update each page around a single visitor question.
   - Keep visual-first marketing and overview sections to one clear SVG, diagram, screenshot, or image with no more than two sentences of supporting copy.
   - Make title tags, meta descriptions, H1s, Open Graph/Twitter metadata, schema, primary CTAs, and internal links match the page intent.
   - Use `references/human-tone-copy-review.md` when rewriting marketing copy, docs introductions, CTAs, launch/product copy, FAQs, or any text that sounds generic or AI-generated.
   - Replace internal terms with user-facing language unless the reader is in an operator/reference page and needs the detail.
   - Make headings, link text, button text, form labels, error copy, and FAQ questions descriptive when read out of visual context.
   - Add or improve FAQ answers for common objections, fit/non-fit, pricing/hosting responsibilities, backups, updates, and privacy where relevant.

4. **Use visuals as evidence**
   - Prefer real screenshots, product images, or precise SVG diagrams over abstract decoration, and let them carry most of the explanation when they can show the idea clearly.
   - Give screenshots useful captions that say what the screen helps the user do.
   - Ensure alt text describes what the screenshot proves.
   - For dense product screenshots, prefer realistic data states that show filtering, drilldown, status, history, export, collaboration, or recovery paths instead of empty dashboards or decorative charts.
   - Mark decorative images as decorative when the stack supports it, and keep essential product claims in accessible text, not only inside images.
   - Do not apply the two-sentence limit to procedures, pricing, legal terms, safety guidance, or reference material that must remain complete and accessible as real text.

5. **Fix accessibility, interaction, and layout**
   - Check semantic structure: one H1, ordered headings, useful landmarks, descriptive navigation labels, accessible names for controls, and correct form labels.
   - Check keyboard behavior: tab order, visible focus, skip links, modal focus management when relevant, and no keyboard traps.
   - Check contrast for muted text, buttons, nav states, tinted cards, code blocks, and dark hero sections, and provide non-color cues for states and errors.
   - Check reflow and zoom resilience: mobile wrapping, horizontal overflow, touch target size, sticky-nav anchor offsets, and route/page navigation.
   - Check dense tables, charts, filters, dashboards, status badges, and drilldowns for labels, keyboard access, readable wrapping, non-color cues, visible focus, and usable empty/loading/error states.
   - Make code and terminal blocks readable on both light and dark surfaces.
   - Respect reduced-motion preferences for animated or scroll-linked effects.

6. **Validate**
   - Use `references/page-sweep-checklist.md` before finishing.
   - Validate HTML, JSON-LD, sitemap XML, internal links, titles/descriptions, H1 count, route status, contrast-sensitive colors, keyboard focus, accessible names, reduced-motion behavior, and desktop/mobile overflow.
   - Run automated accessibility checks, browser inspection, or a manual keyboard/screen-reader-oriented pass when feasible. If not feasible, say which accessibility checks were not run.
   - If a dev server or static server is needed for QA, stop it before the final response.

## Reference Routing

- Read `references/article-intake.md` when incorporating a new article, framework, teardown, or external marketing source.
- Read `references/application-documentation-patterns.md` when auditing or restructuring app docs, developer docs, docs hubs, install guides, quickstarts, API docs, self-hosting docs, troubleshooting docs, or contribution/help pages.
- Read `references/dense-data-application-patterns.md` when public pages, docs, screenshots, or product UI claims involve dashboards, admin consoles, analytics, monitoring, reporting, data tables, workflow builders, high-stakes operations, or complex application surfaces.
- Read `references/human-tone-copy-review.md` when copy needs to sound more natural, specific, founder-written, customer-aware, or less AI-generated.
- Read `references/page-sweep-checklist.md` before implementing or validating a full rewrite.
- Read `references/source-learning-log.md` to reuse prior article lessons and append new source summaries when asked.
- Read `references/distribution.md` when packaging, validating, or preparing this skill for distribution.