An SEO Content Workflow in Claude Code: Brief, Draft, On-Page Check

The SEO content workflow that holds up in Claude Code treats an article the way a developer treats a feature: a repository, a rules file, research you can read back, a brief that is approved before drafting, a draft, a review pass, and a deterministic check before shipping. Every step writes a file. This guide sets that up in eight steps with one CLAUDE.md, two MCP servers, one skill, one agent, and one script.

It is a mechanics guide, not a strategy guide. Which keywords to chase is your call; what Google says about AI-assisted content is in Does AI-written content rank in 2026?, and the wider set of marketing workflows is in the pillar, Claude Code for marketers.

Step 1: A content repo with a CLAUDE.md

Create a folder, run git init, and give it three directories: research/, briefs/, and content/. Then write CLAUDE.md at the root. Claude Code reads it at the start of every session, so it is where the rules live instead of in your head. Keep it short and specific:

# Content repo rules
 
## Audience and voice
- Readers: marketing leads at B2B SaaS companies, 50-500 employees.
- Apply the `acme-voice` skill to every draft.
- American spelling. No exclamation marks. No "in today's fast-paced world".
 
## Files
- research/<slug>.md  -> SERP notes (step 3)
- briefs/<slug>.md    -> approved brief (step 4); never draft without one
- content/<slug>.md   -> the article, with frontmatter: title, description, slug, date
 
## On-page rules (checked by scripts/onpage-check.mjs)
- Title 50-60 characters, includes the target query.
- Meta description 120-155 characters, one sentence, includes the query.
- Exactly one H1 (the title). H2/H3 only below it; no skipped levels.
- At least 3 internal links to existing routes; list candidates in the brief.
- Every image has alt text. Every statistic has a source URL on the same line.
 
## Never
- Invent statistics, quotes, or customer names.
- Cite a page you have not fetched in this session.
- Summarize what you did; return the file.

The character limits are house rules, not Google's; pick yours and keep them in one place. The reasoning behind a lean CLAUDE.md is in CLAUDE.md best practices. The voice skill it references is the one built in Build a brand-voice skill for Claude.

Step 2: Connect Exa and Firecrawl

Claude's training data is not the SERP. Two MCP servers give it the live web: Exa for search and Firecrawl for turning any URL into clean Markdown.

# search: works keyless at reduced rate limits; add a key later
claude mcp add --transport http exa https://mcp.exa.ai/mcp
 
# fetch: hosted server, key as a bearer header (never in the URL)
claude mcp add --transport http firecrawl https://mcp.firecrawl.dev/v2/mcp \
  --header "Authorization: Bearer <your-firecrawl-key>"

Add --scope project to either command to write it to .mcp.json so teammates get the same servers when they clone the repo; keep the key in an environment variable rather than committing it. Exa's server exposes web_search_exa and web_fetch_exa by default, so for light research Exa alone is enough; Firecrawl earns its place on JavaScript-heavy pages and whole-site crawls. If you prefer Tavily for search, Exa vs Tavily has the comparison, and Claude Code MCP setup covers scopes and troubleshooting.

Step 3: Research the SERP

Start Claude Code from the repo root and give it one prompt. This is the one full prompt in the guide, and the shape matters more than the wording:

Target query: "ai content brief template"
Slug: ai-content-brief-template
 
1. Use Exa to search the target query and two close variants. Collect the
   top 8 distinct URLs (skip ads, tools pages, and YouTube).
2. Fetch each URL with Firecrawl. For each page record: title, meta
   description, H2s in order, approximate word count, the questions it
   answers, named entities and tools it mentions, and its publish/update
   date if shown.
3. Write research/ai-content-brief-template.md with one section per page,
   then a final section "Gaps" listing questions none of the pages answer
   and claims they make without sources.
Do not draft anything. Return only the file.

Read the research file before you go on. If the gaps section is empty, either the query is saturated or the research was shallow; both are worth knowing before you spend a draft on it. This retrieval-first pattern is the same discipline as grounding in a RAG system: the model writes from what it fetched, not from what it remembers.

Step 4: Generate the brief

Run the seo-content-brief-writer skill on the research file: "Use seo-content-brief-writer on research/ai-content-brief-template.md and write briefs/ai-content-brief-template.md." The output is a brief with search intent, a working title, an outline of H2s and H3s, the entities and questions to cover, internal links to include (from your own route list), a target length, and the gap the piece will own.

Edit it. Cut sections that only exist because a competitor has them, add the angle only you can write, and fix the internal links to real routes. The brief is the contract for every later step, and an approved brief is what separates this workflow from "write me a blog post."

Step 5: Draft from the brief

"Write content/ai-content-brief-template.md following briefs/ai-content-brief-template.md and CLAUDE.md exactly. Frontmatter: title, description, slug, date. Put a source URL on the same line as every statistic. Return only the file." Two habits keep drafts honest: ask for the file, not a chat message, and refuse a draft that cites a page not in the research file. If it needs a fact it does not have, it should say so in a TODO: line rather than guess.

Step 6: Run the content-editor agent

Before any SEO check, delegate a review: "Use the content-editor agent on content/ai-content-brief-template.md against its brief." The content-editor agent reads both files and returns a numbered list: unsupported claims, sentences that break the voice rules, filler, and brief sections the draft skipped. Work the list yourself. An agent that rewrites the whole piece hides what changed; one that lists problems keeps you the author. The brand-check command is the lighter option when you only want the voice pass.

Step 7: On-page checks

Everything here is deterministic, so it belongs in a script, not a prompt. Ask Claude to write scripts/onpage-check.mjs once; it should parse the frontmatter and Markdown and fail on any of these:

Run node scripts/onpage-check.mjs content/ai-content-brief-template.md until it exits clean. If you pay for Surfer or Clearscope, this is where they fit: paste the draft in for term coverage against ranking pages. They score; they do not replace the brief or the editor pass.

Step 8: Export and publish

Commit the research, brief, draft, and any script change in one commit so the trail stays together. Export to whatever your CMS takes: Claude can convert the Markdown to HTML or MDX, or you paste into the editor. After publishing, add the live URL to the brief. When the piece needs a refresh, re-run step 3 to see what the SERP now covers and step 7 to make sure the update did not break anything.

What this workflow does not do

It does not pick keywords, and it does not make thin content rank. Google's own guidance on generative AI content says the tools are "particularly useful when researching a topic, and to add structure to original content," which is the role they play here, and warns that generating many pages without adding value may violate its scaled content abuse policy. The research file and the gaps section are your defense: if the draft has nothing the ranking pages lack, do not publish it. The same logic applies to AI search features; generative engine optimization and answer engine optimization are, at bottom, the same brief with more emphasis on direct answers to the questions in it. If you use Anthropic's marketing plugin, its seo-audit skill is the site-level view that feeds this per-article loop; the plugin guide explains how they chain.