Aeo Content Writer

AEO Content Writer Skill

This skill writes blog posts that are data-driven, AEO-optimized, and follow the site's tone and content standards.

When to Use This Skill

Trigger this skill when the user asks to:

• "Draft the blog post about [Topic]"
• "Write a post about [labor market trend / AI impact topic]"

Core Workflow

Step 0: AEO Brief Intake (when writing from a research report)

If the user references an AEO topic research report or says they want to write a specific post from a research report, do this before anything else:

1. Identify the specific recommendation. Ask the user which post/recommendation they're targeting if not obvious. Reference it by its exact title and slug from the report. Do not proceed ambiguously.

2. Extract from the content brief:

• Target questions — the exact queries the post is designed to answer. These drive the H1, meta title, and FAQ pairs.
• Reddit phrasing — exact phrases from the glossary and brief. These go verbatim into headlines, subheads, and intro paragraphs. Do not paraphrase.
• Content structure — use the brief's numbered outline as the skeleton. The section order, H2s, and framing are deliberate; follow them unless you have a strong reason to deviate.
• Word count target — treat the range as a floor, not a guideline. Under-length posts are the primary reason sites fail to get cited.
• Key data to pull — specific data points named in the brief. These are the data points that make the post citable; don't substitute with vaguer claims.
• Slug — use exactly as specified.

3. Sanity-check against the Winning Content Formula (Section 6 of the report): Before writing, verify the planned post will include:

• Direct answer paragraph (2–3 sentences) at the very top
• Key Takeaway (2–3 sentences, specific numbers) after the opening paragraph, before the first H2 — only if the opening paragraph is narrative rather than data-dense. If the opening already leads with strong stats, skip it.
• Key Takeaways box (3–5 bullets) near the top
• Numbered list with consistent sub-structure per entry (if it's a listicle)
• At least one inline table for salary/comparison data
• Table of contents (for posts over 2,500 words)
• FAQPage schema via faqPairs prop (6–8 pairs, schema-only — not a visible section)
• Question-formatted H2s throughout, each followed by a direct-answer first paragraph
• Visible data attribution line near the top
• Minimum 3–5 external citations to authoritative sources

If any of these are missing from your plan, add them before writing.

Step 1: Information Gathering

Before writing a single word, gather the necessary data:

1. Read CONFIG.md: Load TONE_GUIDE_PATH, SITE_CONTEXT, AGENTS_DOC, DATA_SOURCES, SITE_REPO, DATA_REPO, BLOG_COMPONENT_DIR, and BLOG_ROUTE_DIR from .claude/skills/aeo-content-writer/CONFIG.md.
2. Read the Tone Guide: Review the file at TONE_GUIDE_PATH.
3. Read Site Context: Review the file at SITE_CONTEXT for platform background, data sources, and what this skill is responsible for.
4. Read Agents Doc: Review the file at AGENTS_DOC for agent coordination context.
5. Gather Data: Pull from DATA_REPO and authoritative external sources listed in DATA_SOURCES. Find real numbers for any salary, job growth, or openings claims.
6. Find 3 High-Quality Sources: Government data, peer-reviewed labor economics, major research reports (McKinsey, WEF). Avoid Gartner/IDC/MarketsandMarkets.

Step 2: Blog Post Format

Read CLAUDE.md before writing any files — it contains file paths, component names, route boilerplate, slug format, POSTS array fields, thumbnail spec, and sitemap format.

You must generate all of the following:

A. Post Component

• Export named constants at the top: slug, title, published date, published date ISO, description. Add edited date constants if this is an edit.
• Must follow the structure: Lead with finding → Show evidence → Explain meaning → Caveats → Actionable takeaway.
• Define 6–8 FAQ pairs (schema-only — not rendered on page). Each pair:
  • question: a natural-language query ending with ? that a real user would type
  • answer: 2 sentences max, names specific numbers or named entities, directly answers the question
• Pass faqPairs to the layout component.
• Must include a Data Sources section at the bottom with numbered links, each with an id="source-N" anchor. Every source must include a hyperlink. Never leave a source as plain text without a URL.
• When directly citing a source in body text, use inline superscript footnotes referencing #source-N. Number inline citations to match the source list order. Never cite sources only in captions.

B. Route Page

Create the route page using the pattern in CLAUDE.md. Export a metadata object with title, description, and canonical URL.

C. Blog Index Entry

Add to the POSTS array per the field spec in CLAUDE.md.

D. Thumbnail Function

Follow the thumbnail spec in CLAUDE.md. Do not reuse another post's thumbnail function.

E. Sitemap

Add a <url> block per the sitemap format in CLAUDE.md. Set <lastmod> to today's date.

Step 3: AEO Optimization (Answer Engine Optimization)

To ensure the content is picked up by AI search engines (Perplexity, ChatGPT, Google AI Overviews):

• Direct Answers: The first paragraph of any section must directly answer the implied question without preamble.
• High Information Density: Use specific numbers, percentages, and named entities. AI engines prefer dense, factual text over narrative fluff.
• Question H2s: Where natural, frame section headings as questions users actually search (e.g., "Will AI Replace Software Engineers?"). The paragraph immediately following must answer in the first 1–2 sentences — no preamble. Don't force it if the section topic doesn't map cleanly to a question.
• Schema Readiness: faqPairs drive the FAQPage JSON-LD schema injected by the layout component — they are schema-only, not rendered on page. Write questions that match real search queries distinct from the H2s. Answers must be ≤2 sentences with a specific data point in each. Target 6–8 pairs.

Step 3b: Self-Evaluation Pass

After completing the draft, run a self-evaluation before saving. Read the tone guide at TONE_GUIDE_PATH and check the draft against:

1. AEO formula — quick answer block present, FAQ pairs written, at least one comparison table, question H2s throughout
2. Author assignment — assign the correct author based on topic per the tone guide's author assignment rules
3. Tone checklist — flag any instance of banned phrases, vague claims that could be specific, sections that don't lead with the answer, generic CTAs
4. Competitor differentiation — does at least one section say something top-cited competitors in this niche don't?

Output the evaluation as a brief flagged list before the draft. Format:

• ✓ pass or ✗ [specific issue] for each criterion
• If any ✗, fix before saving. Do not ask the user to fix — fix it yourself.

Step 4: Accessibility & Mobile

Apply these explicitly — do not defer to the publish-checklist skill:

• Expandable sections (career cards, accordions): aria-expanded on the toggle button.
• Decorative SVGs: aria-hidden="true" or inside pointer-events-none containers.
• All interactive elements (links, buttons) are keyboard-accessible with visible focus states.
• Responsive typography: body prose uses text-base md:text-lg.
• Data tables: wrap in overflow-x-auto or use dl stat rows that widen to w-5/6 on mobile.
• Charts/graphs: use grid-cols-1 sm:grid-cols-[...] so labels stack above bars on mobile.
• Content previews on index pages: line-clamp-3.

Step 5: Internal Linking

Every new post must:

1. Link to 2–3 existing published pages (blog posts, career pages, or industry pages) where naturally relevant. Use descriptive anchor text matching the target page's topic.
2. After writing, identify which existing pages should link forward to the new post. List them in the handoff: "Also add a link to this post from [page] in the section about [topic]."

Do not skip — internal linking shares page authority across the cluster and signals topical depth to Google.

Step 6: Output and Handoff

1. Write all files per the paths in CLAUDE.md.
2. Ask the user to review the new content live in their browser at the local dev URL.
3. Once the user approves the live preview, run the publish-checklist on the new post.

Optional — Google Docs sync (only if the user requests it):

• Check CONFIG.md for a GOOGLE_DOCS_* key matching the content type (e.g. GOOGLE_DOCS_BLOG).
• If no key is set, tell the user and stop.
• Google Drive MCP must be authenticated. If tools are unavailable, prompt: "Run /mcp and select Google Drive to enable doc sync."
• Always call mcp__claude_ai_Google_Drive__read_file_content before any write to get current doc state.
• Write (new draft): Append to the doc with a --- separator and an H1 post title above the content.
• Edit (user asks to edit a section): Read the doc, locate the section, make the targeted change only.
• Confirm after: "Done. View at https://docs.google.com/document/d/[ID]/edit"