How to Build an SEO Content Brief with Codex (Full SKILL.md Included)

python3 ~/.codex/skills/codex-seo-content-brief/scripts/brief_context.py <site-url-or-sitemap> <competitor-url> [more competitors]

---
name: codex-seo-content-brief
description: Use when the user asks for a content brief, blog brief, service page brief, content outline, keyword brief, "brief for", writing brief, or content plan for a specific keyword or URL - produce a research-backed outline with competitor scoring, per-section word counts, keyword placement rules, and a page-type template. Triggers on "write a brief", "outline for", "what should this page cover", "improve this page".
---
# SEO Content Brief Generator

Research-backed briefs that give a writer a page capable of outranking the
current top results: competitor analysis with gap scoring, per-section word
counts, keyword placement rules, and a page-type template. You judge; the
scanner collects the evidence.

## Run

```bash
python3 ~/.codex/skills/codex-seo-content-brief/scripts/brief_context.py <site-url> <competitor-url-1> [competitor-url-2 ...] [--json]
```

`<site-url>` is the target site's homepage or sitemap (business context only).
Competitor URLs are the current top pages for the keyword; paste them from a
search, or ask the agent to run a search first. The scanner returns, per page:
title, words, H2 sections, meta description, and the first ~200 words.

## Step 1: determine the mode

- **Improve mode** (existing page URL): fetch it, list what is strong (keep),
  what is missing/thin/outdated (add or strengthen). Do not recommend a full
  rewrite when targeted improvements will win.
- **New page mode** (keyword or topic, no page yet): build from scratch,
  focused on the gaps the new page can fill.

## Step 2: analyze the SERP

Filter the top 5 page list down to real competitors. Drop Wikipedia, Reddit,
Pinterest, Amazon, YouTube, government sites, SEO tool pages, job boards,
directories, news aggregators, and social platforms - they win on domain
authority, not because their blueprint is good.

Score each real competitor 1-10 on Depth, Formatting, SEO, and UX. Then find
three gap types:

- **Topic gaps**: subtopics competitors miss entirely
- **Depth gaps**: topics covered but shallow
- **Quality gaps**: outdated info, no expert perspective, poor formatting

Priority for each gap: `Impact x Competitive Advantage / Effort`.

## Step 3: classify intent and SERP format

| Intent | Signal | Format Google rewards |
|---|---|---|
| Informational | learning keywords (how to, what is, guide) | guide, definition, listicle, FAQ |
| Commercial | researching before buying (best X, vs, review) | comparison, listicle, review |
| Transactional | ready to act (buy, book, enquire, sign up) | product/landing page, local pack |
| Navigational | specific site or page | site page |

State which format the SERP actually rewards: long-form guide, listicle,
comparison table, landing page, FAQ, video, or local pack. The brief's shape
follows the SERP, not the writer's preference.

## Step 4: apply the page-type template

Pick the template matching the page type, then adapt per competitor gaps and
intent. Not every section applies to every page.

### Service page

| Section | Purpose | Format |
|---|---|---|
| What is [service] | Define clearly | Definition box, 80-120 words |
| Who needs it | Qualify | Bullet scenarios |
| How it works | Reduce friction | Numbered steps |
| Costs/pricing | Answer the #1 question | Table or range if variable |
| Outcomes/results | Prove value | Stats, case snippets, before/after |
| Why choose [brand] | Differentiate | 3-5 bullets with specifics |
| FAQ | PAA traffic | 5-8 questions, 40-60 words each, FS target |
| CTA | Convert | Clear action, reduced risk |

Schema: Service + LocalBusiness when location-specific. Never add FAQPage for
Google visibility (rich results retired 2026-05-07; no AI benefit confirmed).

### Blog post

| Section | Purpose | Format |
|---|---|---|
| Direct answer | Win the snippet | 40-60 words, FS target |
| Background | Context | 1-2 paragraphs |
| 3-5 H2 subtopics | Cover PAA/gaps | Mix paragraphs, lists, tables |
| Common mistakes | Unique value | Numbered list with explanations |
| FAQ | Long-tail | 5 questions from gap analysis |
| CTA | Convert | Contextual link, not hard sell |

Schema: Article. Keyword: H1, first 100 words, URL slug, meta title, one image
alt.

### Case study

Outcome summary first (bold stat), client situation, the challenge, approach,
the result with specific figures, 3-5 takeaways, related-services CTA. The
outcome or matter type is the keyword.

### Category / hub page

Overview of scope, then one H2 or H3 per relevant sub-page with description
and internal link, who we help, process, FAQ, CTA. **Every sub-page that
exists on the site must appear; invent none, leave none out.**

### Landing page

Hero (offer + CTA), problem statement, solution benefits (3-5 bullets), social
proof, 3-step how-it-works, objection handling, final CTA. Schema: WebPage.

### FAQ page

8-15 questions grouped by subtopic, 40-60 words each, FS target on every
answer. Schema: WebPage only. QAPage only when users can submit answers to a
single genuine question.

### Location page

What we do in [city], hyper-local areas/landmarks served, service areas, why
local matters, local team bios, local reviews, 5 location-specific questions,
local phone/address/booking CTA. Schema: Service + LocalBusiness.

### About page

Who we are, story/founding, team bios with credentials, values, awards with
dates, media mentions, contact CTA. Schema: Organization + Person per member.

### Homepage

Hero value prop + CTA, services overview (card grid to service pages), 3-5
differentiators, social proof, service area, GEO FAQ (4-6 broad business
questions), repeated primary action. Schema: Organization + WebSite + Service.

## Critical rules

### Website Relevance Rule

Every suggested heading, subtopic, keyword, and FAQ must be something the
target site can credibly cover from its actual services or products. If the
site doesn't offer it, remove it, even if competitors cover it.

### Site Structure Coverage Rule

For hubs, overviews, categories, and "types of" pages: the outline must
reference every relevant existing sub-page in the sitemap (each as its own
section with an internal link). For non-hub pages, only suggest relevant
links; never force every category in.

### Output language rules

Never name researcher, framework, or tool names in the output (no "this
method", no SaaS tool names, no named formulas). They are internal thinking
tools. Write for a business owner or content writer, not an SEO academic.

## Keyword density and placement

No fixed density targets. Density checks are optional readability/stuffing
heuristics only; first 1-2 mentions establish context and diminish after that.

**Primary keyword must appear in:** title tag near the front, H1 near the
front, URL slug, meta description, first paragraph (first 100 words), and at
least one image alt text.

**It does NOT need to appear in:** every H2/H3, or every paragraph.

**Secondary keywords:** 5-8 closely related terms in the body; 10-15 broader
semantic terms. Synonyms are fine and do not count toward density.

**Per-section guidance** in the outline: which keyword goes in the heading,
and whether the body uses the primary keyword or a variation. Spread the
primary keyword evenly; don't front-load or cluster it.

## Meta tag rules

- **Title**: 50-60 chars, primary keyword first, brand last with the site's
  existing separator (pipe or dash), lead with outcomes/numbers where possible.
- **Meta description**: 130-150 chars, active voice, expand the title with
  specifics, end with a call to action. No brand at the end (it's in the
  title), no quotes (Google truncates at quotes).

## Information gain (non-negotiable)

Every brief names exactly what new value this piece adds that no current
ranking page provides. It must be specific: proprietary data, original
research, case studies with real outcomes, expert quotes, first-hand
experience, or an original synthesis. "More detail" or "better formatting" is
not information gain.

## E-E-A-T requirements

List the exact trust signals the piece needs: author credentials and a bio
relevant to the topic, expert quotes or citations, dated studies or stats,
last-updated date. Critical for YMYL: health, finance, legal, safety.

## Internal linking

3-5 specific link opportunities with anchor text and target URL, from the real
site structure. Say whether the page is the hub (links out to cluster pages)
or a spoke (links to the pillar).

## Output contract

Use this exact structure:

```markdown
## Content Brief: [Primary Keyword]

### Search Intent
[intent type, SERP format rewarded, target audience and knowledge level]

### Competitor Analysis
| # | URL | Key H2 Sections | Est. Words | Score | Main Gap |
|---|-----|-----------------|------------|-------|----------|

### Content Gaps and Opportunities
[bullets: topic gaps, depth gaps, quality gaps with specifics]

### Winning Outline
**H1:**, **URL Slug:**, **Target Word Count:** (~[X], competitor average)
[full H2/H3 outline with word count per section, format notes,
FS-target marks, per-section keyword guidance]

### Recommended Meta Tags
[title <=60, description <=150]

### Unique Angle and Information Gain
[specific paragraph]

### E-E-A-T Requirements
[exact trust signals]

### Internal Linking Opportunities
[3-5 with anchor text and URL]
```

### Outline-only mode

For "just an outline": skip the competitor table, gaps, information gain, and
E-E-A-T sections. Output Search Intent (one line), H1, slug, target word
count, and the full H2/H3 outline with word counts, format notes, FS targets,
keyword guidance, and a 1-2 sentence writing note per section.

## Errors

| Scenario | Action |
|---|---|
| Target URL unreachable | Report it. Never guess page content |
| No competitors left after filtering | Broaden to partial matches; note the thin landscape in the brief |
| Sitemap not found | Proceed without site structure; say internal-link suggestions are incomplete |
| Page type not specified | Auto-detect from intent and SERP format; state the detected type |
| Target word count not specified | Use competitor average; note it |

#!/usr/bin/env python3
"""Brief context collector: per-page structure for competitor analysis.
Standard library only."""

import html as htmlmod
import json
import re
import sys
import urllib.error
import urllib.parse
import urllib.request

TIMEOUT = 15
UA = ("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
      "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0 Safari/537.36 "
      "codex-seo-content-brief/1.0")


def fetch(url):
    req = urllib.request.Request(url, headers={"User-Agent": UA})
    try:
        resp = urllib.request.urlopen(req, timeout=TIMEOUT)
        return resp.status, resp.geturl(), resp.read().decode("utf-8", "replace")
    except urllib.error.HTTPError as e:
        return e.code, url, ""
    except Exception as e:
        return "ERR:" + str(e), url, ""


def extract(raw, url):
    page = {"url": url}
    html = raw or ""
    if not html:
        page["error"] = "no HTML body"
        return page

    def m(p):
        return re.findall(p, html, re.I)

    title = (m(r"<title[^>]*>([^<]+)</title>") or [""])[0]
    desc = (m(r'<meta[^>]+name=["\']description["\'][^>]+content=["\']([^"\']+)["\']') or [""])[0]
    h2 = [htmlmod.unescape(re.sub(r"<[^>]+>", "", h)).strip() for h in m(r"<h2[^>]*>(.*?)</h2>")]
    h3 = [htmlmod.unescape(re.sub(r"<[^>]+>", "", h)).strip() for h in m(r"<h3[^>]*>(.*?)</h3>")]

    text = re.sub(r"(?is)<script.*?</script>|<style.*?</style>|<pre.*?</pre>|<code.*?</code>|<[^>]+>", " ", html)
    text = htmlmod.unescape(re.sub(r"\s+", " ", text)).strip()

    # sitemap support: /sitemap.xml gives <loc> list
    if "sitemap" in url.lower():
        locs = re.findall(r"<loc>([^<]+)</loc>", html)
        page["sitemap_urls"] = locs[:200]
        page["sitemap_count"] = len(locs)
        return page

    canon = m(r'<link[^>]+rel=["\']canonical["\'][^>]+href=["\']([^"\']+)["\']')
    internal = len(re.findall(r'<a\s[^>]*href=["\']/?[^"\']+["\']', html))
    page.update({
        "title": htmlmod.unescape(title)[:120],
        "meta_description": htmlmod.unescape(desc)[:200],
        "words": len(text.split()),
        "h2": h2[:15],
        "h3": h3[:15],
        "canonical": canon[0] if canon else None,
        "links": internal,
        "excerpt": text[:220],
    })
    return page


def main():
    args = sys.argv[1:]
    want_json = "--json" in args
    args = [a for a in args if a != "--json"]
    if len(args) < 1:
        print("usage: python3 brief_context.py <site-or-sitemap-url> [competitor-url ...] [--json]")
        sys.exit(1)
    out = []
    for u in args:
        if not u.startswith("http"):
            u = "https://" + u
        status, final, raw = fetch(u)
        page = extract(raw, final or u)
        page["status"] = status
        out.append(page)
    if want_json:
        print(json.dumps(out, indent=2))
    else:
        for p in out:
            u = p["url"]
            if "sitemap" in u.lower() and "sitemap_count" in p:
                print("sitemap %s: %d URLs listed" % (u, p["sitemap_count"]))
                continue
            print("%s [%s] %d words" % (u, p.get("status"), p.get("words", 0)))
            print("  title: %s" % (p.get("title") or "-")[:110])
            print("  desc : %s" % (p.get("meta_description") or "-")[:110])
            print("  h2   : %s" % (" | ".join(p.get("h2", [])[:6]) or "-"))
            print("  expr : %s" % (p.get("excerpt") or "-")[:150])


if __name__ == "__main__":
    main()

mkdir -p ~/.codex/skills/codex-seo-content-brief/scripts
# save the two files above at:
#   ~/.codex/skills/codex-seo-content-brief/SKILL.md
#   ~/.codex/skills/codex-seo-content-brief/scripts/brief_context.py
python3 ~/.codex/skills/codex-seo-content-brief/scripts/brief_context.py https://example.com/sitemap.xml https://example.com

sitemap https://auspia.ai/sitemap.xml: 966 URLs listed
https://auspia.ai/blog/codex-seo-technical-audit [200] 2409 words
  title: How to Audit Technical SEO with Codex (Full SKILL.md Include
  desc : How to perform a technical SEO audit with Codex: the underlying how-...
  h2   : What you get from this article | Why technical SEO still matters in ...

## Content Brief: technical seo audit

### Search Intent
Informational. SERP rewards long-form guides with checklists and CWV tables.
Audience: mid-career SEOs and site owners; they know the terms, they want the sequence.

### Competitor Analysis
| # | URL | Key H2 Sections | Est. Words | Score | Main Gap |
| 1 | example.com/blog/technical-audit | x, y, z | 2,800 | 32/40 | No AI-crawler filtering, no automation |
| 2 | seo-tools.com/guides | ... | 3,400 | 30/40 | Generic advice, no real scan output |

### Winning Outline
**H1:** Technical SEO Audit: How to Run One in 9 Steps
**URL Slug:** /technical-seo-audit-checklist
**Target Word Count:** ~2,800 (competitor average ~2,800)

## Step 1: Crawlability (450 words, checklist format, FS target)
Keyword: primary in H1/URL only. Body: secondary terms.
...

Read the two code fences marked "The full SKILL.md" and "The context collector script" above.
1. Create ~/.codex/skills/codex-seo-content-brief/SKILL.md
2. Create ~/.codex/skills/codex-seo-content-brief/scripts/brief_context.py
3. Run: python3 ~/.codex/skills/codex-seo-content-brief/scripts/brief_context.py https://example.com/sitemap.xml https://example.com
4. If that works, take my keyword or existing URL and produce a full brief with the competitor table, winning outline, and information-gain section.
Do not install or modify any other files.