SEO Content Writing skill for Codex

Done well: a reader who searched the query gets the answer in the first screen, can act on it without opening another tab, and sees evidence that the author has done the thing. Search engines are served by the same qualities; nothing in the draft exists only for a crawler.

Before writing

• Get the brief (from content-briefs) or build a mini one: query, intent, reader, angle, must-cover subtopics, the conversion goal, and available evidence.
• Read AGENTS.md and any style guide in the repo (docs/style*, CONTRIBUTING.md, brand voice files). Check how content is stored: MDX/Markdown with frontmatter, CMS export, or HTML; match existing frontmatter fields (title, description, date, author, tags, canonical).
• Collect facts you will state. If Codex cannot verify a claim offline, mark it [VERIFY: ...] for the author rather than asserting it. Never invent statistics, quotes, case studies or customer names.

Workflow

- [ ] 1. Write the answer first (the two sentences that resolve the query)
- [ ] 2. Lay out H2s in the order the reader needs them
- [ ] 3. Draft sections with evidence slots filled or flagged
- [ ] 4. Add examples, tables, code, visuals where they beat prose
- [ ] 5. Title, meta description, slug, internal links
- [ ] 6. Edit pass: cut, verify, de-template
- [ ] 7. Run the publishing checklist

1. Answer first

The intro does three jobs in under 100 words: state the answer or outcome, say who it is for or when it applies, preview what the rest covers. No history of the topic, no “In today’s fast-paced world”, no restating the title as a question.

<!-- Weak -->
Connection pooling is an important topic for many developers. In this article, we will
explore what PgBouncer is and why you might want to use it.

<!-- Strong -->
Run PgBouncer in transaction mode in front of Postgres, set `default_pool_size` to about
your database's CPU count times two, and point your app at port 6432. The config below
handles 2,000 client connections on a 100-connection Postgres. Prepared statements need
one extra setting, covered in step 4.

2. Structure

• H2s should read like a table of contents a reader would choose. Use the searcher’s words in headings when natural (“How to size the pool”), not keyword-stuffed labels.
• Procedures: numbered steps, one action per step, expected result after the step.
• Comparisons: a table early, prose after for nuance and recommendation.
• Definitions/glossary: one-sentence definition, example, why it matters, related terms.
• Keep paragraphs short (2–4 sentences). Bold sparingly for scan anchors.

3. Evidence and experience

Google’s guidance (helpful, reliable, people-first content; E-E-A-T as a quality lens) rewards visible first-hand experience. Add at least one of these per article:

• Tested commands, configs or code with versions and the output you got.
• Original screenshots, measurements, benchmarks, costs, timelines.
• Specific failure cases and how they were fixed.
• Named author byline with relevant role; reviewer for YMYL topics (health, finance, legal, safety).

Cite primary sources inline (official docs, standards, studies) for factual claims.

4. Vocabulary and entities

• Use the primary phrase in the title, H1 and intro where it reads naturally; after that, write normally. Cover related terms because the topic requires them, not to hit a list.
• Name entities precisely: product names with versions, standards with numbers, people with roles. Ambiguity costs both readers and search engines.

5. Metadata and links

• Title under ~60 characters, primary topic first, distinctive promise; meta description 120–160 characters with a concrete detail. Write 2–3 options, pick one.
• Slug: short, lowercase, hyphenated, stable.
• 3–6 contextual internal links to genuinely related pages with descriptive anchors; suggest 2–3 existing pages that should link to this one.

6. Edit pass

Cut on sight:

• Filler openers and closers (“In conclusion”, “It is important to note that”).
• Sentences that restate the heading.
• Generic advice that applies to any topic (“Make sure to test thoroughly”).
• Hedging stacks (“may potentially help to possibly”).
• Lists of three where one item is padding.

Check:

• Every command, code block and link was run or opened. Every number has a source.
• Reading level fits the audience; jargon defined at first use for mixed audiences.
• The article still answers the query if the reader reads only the intro and headings.

7. Publishing checklist

• Answer in first 100 words
• All brief table-stakes covered; information-gain element present with evidence
• No [VERIFY] markers left; no invented facts
• Title, description, slug, author, dates in frontmatter
• Images: meaningful alt text, dimensions, compressed; LCP image not lazy
• Internal links in and out added
• Article/BlogPosting structured data from template, matching visible author and dates
• dateModified changed only if content changed meaningfully

Refreshing existing content

1. Pull the page’s Search Console queries (last 3 months vs prior period).
2. Keep what still ranks; do not rewrite sections that earn the clicks.
3. Update outdated facts, versions, screenshots; add sections for high-impression queries the page does not answer explicitly.
4. Keep the URL. Update dateModified and visible “Updated” date only with real changes.

Gotchas

• Scaled content abuse: publishing many pages generated to manipulate rankings is spam regardless of whether a model or a person wrote them. AI assistance is fine; unreviewed, unoriginal volume is not.
• Writing for a word count produces padding; writing for a keyword list produces unnatural headings. Both read as low quality.
• “Best X” lists without evidence of testing are the pattern Google’s reviews system demotes. Show how products were evaluated.
• Fake freshness (changing the year in the title without updating content) erodes trust and can trigger title rewrites.
• Do not copy competitors’ structure wholesale or paraphrase their sections; that adds nothing and risks copyright issues.

Output

Deliver the draft in the repo’s content format plus a short note:

**Draft:** content/guides/pgbouncer-setup.mdx (1,850 words)
**Title / meta:** chosen option + 2 alternates
**Evidence used:** benchmark from brief; config tested with PgBouncer 1.24 in Docker
**Needs author:** 2 [VERIFY] markers (driver support for protocol-level prepared statements)
**Links:** out ×4, suggested inbound from /postgres/performance and /docs/connection-limits