# Aeo Content Writer > Blog post writer for AEO-optimized, data-driven sites. Writes posts based on BLS/O*NET data or equivalent authoritative sources, following the site's tone guide and content structure. Career/product pages generated by data pipelines are out of scope — use this skill for editorial blog posts only. - Skill: `yoyothesheep/aeo-content-writer` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add yoyothesheep/aeo-content-writer` - Raw SKILL.md: https://api.skillmd.com/api/skills/yoyothesheep/aeo-content-writer/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: yoyothesheep (https://skillmd.com/u/yoyothesheep) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/yoyothesheep/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. 4. **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 `` block per the sitemap format in CLAUDE.md. Set `` 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"