How I Built an SEO Review Agent for My Substack Posts

A one-command system that checks metadata, image alt text, internal links, and search intent without rewriting my voice.

I used to think SEO was a separate thing from writing.

I would finish a post, feel good about the argument, then remember there was still another layer I had ignored: the SEO title, subtitle, slug, internal links, tags, and image alt text.

And honestly, I kept avoiding it because most SEO advice made the writing worse.

• The title became flatter.

• The headings became too obvious.

• The intro started sounding like it was answering a search query instead of talking to a real person.

This explains what I’ve been seeing here on Substack, especially with so many great writers who have strong storytelling skills—but when I look at the posts themselves, it’s clear they don’t really care about SEO.

No clear search title. No keyword direction. Weak internal links. Images without useful alt text. Slug URLs that are partially cut off, like they didn’t even bother to look at them.

And I get why this happens.

Most writers do not want to write for SEO. I do not either. I want the post to sound like me first. I want the argument to work for the reader already in front of me.

But once you publish something on the internet, discoverability becomes part of the job whether you care about SEO or not.

That doesn’t mean every writer needs to become an SEO expert. I also don’t think SEO should take over the writing process.

The goal is smaller than that.

I want great writing to be easier to find without losing its soul to keyword-stuffed optimization.

Imagine you have a Substack post that sounds like you. The story is there. The argument works. You are almost ready to publish. But you still want the post to be easier to find, easier to understand from search, and better connected to the rest of your archive.

If that’s you, this post is for you.

Does SEO Still Matter When AI Search Is Growing?

Now, the obvious question is whether SEO still matters now that AI search is growing.

I understand why people question it. If you’ve been in the AI rabbit hole like me, you already know that AI search is growing. Google is adding AI answers. More people are asking Claude, ChatGPT, Perplexity, and Gemini the questions they used to type into Google.

But I don’t think SEO becomes irrelevant. What I understand from this shift is the way people discover writing is getting more complicated.

Graphite looked at search traffic across 40,000 large US sites and found that "SEO traffic is down slightly (-2.5%), not dramatically." Semrush makes a similar point from the AI-search side: "Traditional rankings still matter," but AI visibility is becoming another layer to pay attention to.

So no, SEO is not the whole game anymore, but it’s still part of the game. You still need to help readers, search engines, and AI systems understand what your post is about.

We can talk about GEO (Generative Engine Optimization) separately in a later post. For now, I want to focus on SEO because good SEO is still a useful foundation for everything else.

And in my own newsletter, it is not theoretical.

In April, Google accounted for around 60% of my Substack traffic (over 86,000 visits in total) and roughly 30% of my subscription revenue. That was enough data for me to stop treating Google as a tiny side channel and start treating it as a new priority.

People are still searching. I still search. And for my newsletter, search is still bringing in real paying readers. Ever since I started optimizing my posts for SEO, Google traffic has been increasing.

So the question became:

How do I improve the SEO layer around a finished draft without turning the post into generic search content?

That is why I built an SEO review agent.

Its job is not to write the post for me. It is not allowed to rewrite the essay by default. It only reviews the finished draft and gives me the parts I usually forget or rush: better metadata, image alt text, slug URLs, internal link suggestions, search intent notes, competitive research analysis, and a list of what not to touch.

That last part matters more than I expected.

Because good SEO should help the right reader find the post. It should not sand down the voice that made the post worth finding.

The Mistake I Kept Making With SEO

My mistake was not that I ignored SEO. I knew SEO was important.

The mistake was that I tried to do the important parts manually, usually after I had already spent most of my energy writing the post.

I would finish a draft, then try to think about keywords, titles, slug, headings, internal links, and image alt text in the last mile before publishing.

And honestly, I did not always do enough research.

I might have a rough sense of the topic, but I would not always check what people were actually searching for. I would not always look at the search results to see what kinds of posts already ranked. I would not always compare my angle against the articles I was competing with.

That matters because SEO is not only about adding a keyword somewhere.

It asks questions like:

1. What would someone search before this post becomes useful to them?

2. Which keywords have enough intent to matter?

3. What does the search result page already reward?

4. Are competitors writing tutorials, comparisons, list posts, or opinion pieces?

5. Does my heading structure make the post easy to understand?

Those are valuable questions.

They are also the exact questions I do not want to spend most of my writing time thinking about.

I would rather spend the deep work on the idea, the story, and the argument. But if I leave the research layer until the end, I either rush it or skip parts of it.

That was the real gap.

Instead of asking AI to write the post for me, I’m asking it to handle the research-heavy SEO review I was doing manually.

The Review I Wanted Before Publishing

What I wanted was simple.

After I finished a draft, I wanted one review that could tell me:

1. What search angle actually fits this post.

2. Which keywords are worth caring about.

3. What the current search results seem to reward.

4. Whether my title, subtitle, slug, and headings make the post easier to find.

5. Which internal links and image alt text I should add.

That would give me the part I kept skipping manually.

I would still write the post myself. I would still decide what to apply. But I would not have to do the whole research process from scratch every time.

That’s the agent’s job: handle the research‑heavy review, then give me one ranked report I can apply manually inside Substack

That is the review I wanted.

Now I will show you how I built it.

What We Are Building: SEO Review Agent

The SEO review process starts from a command, but the command is just the trigger.

The folder is the system.

The folder looks like this:

seo-review-system/
  README.md
  .claude/
    commands/
      seo-review.md
    agents/
      seo-draft-extractor.md
      seo-search-intent-researcher.md
      seo-competitive-researcher.md
      seo-voice-guard.md
      seo-onpage-writer.md
      seo-internal-link-finder.md
      seo-final-synthesizer.md
  seo-reviews/
      writer-context/
        voice-guide.md
        reader-profile.md
        seo-rules.md
      archive-index.csv

From the outside, the workflow still looks simple.

You run one command:

/seo-review [Substack draft link or local draft file]

Behind that command, the folder gives the agent everything it needs:

1. The finished draft.

2. The writer’s voice and reader context.

3. The writer’s SEO rules.

4. The archive for internal links.

5. The seven sub-agents that run review process.

6. The report destination.

This is the process I’ve been optimizing for months. Before I publish a new post, I run this to ensure it follows the right SEO framework without affecting my rhythm and voice. I’ve also been fixing my past posts that didn’t follow the right SEO framework.

If you follow this process, once you finish the SEO agent review, you’ll receive a 15–20 page SEO report that you can use to improve both your existing posts and your drafts.

What You Need Before This Works

This whole process is meant to run inside Claude Code, where the AI agent can read files, use local instructions, deploy sub-agents, call research tools, and save a final report.

I will share the starter folder, the command file, and 7 sub-agents reviewer files separately.

Before continuing, here’s what you need to prepare in advance:

1. Claude Code. The system needs a coding-agent environment that can work inside a folder and read local files.

2. Tavily or another research tool. This handles search intent, competitive research, and current results. Without it, the workflow can still review structure and voice, but the research layer becomes weaker.

3. A finished draft. The workflow starts after the post is written. It can use a Substack share draft link, a published URL, a local markdown file, or pasted draft text. Make sure your draft already includes images so you’ll receive image‑alt‑text suggestions in the report.

4. Writer context files. You need to fill in their voice-guide.md, reader-profile.md, and seo-rules.md so the system knows what to preserve. But if you follow my context-folder guide, you only need seo-rules.md here.

5. An archive index. Readers need a simple map of their existing posts so the internal link finder can recommend useful links.

6. Full post files when possible. The index helps with quick matching, but full posts help the system understand related ideas, voice patterns, and duplicate framing risks.

7. The command and sub-agents. These do not live inside the source-material folder. They live in the coding-agent setup and call into the folder. Read my post on how to structure your Claude Code agent.

8. A reports folder. The system needs a clear place to save the final SEO review before you can apply changes manually.

The command and sub-agents are the reusable parts. The writer context and archive are the personalization layer. We need all of them to make this works.

Let’s dive in so I can explain how to prepare each one to you.

What Each Folder Does

The secret recipe comes from this folder; it’s not from the command, skill, or even sub-agents.

Because the folder holds all of the context together.

When I first started thinking about this, I was tempted to make the command or skill do everything. Give it a draft link, let it search around, let it inspect the post, let it make suggestions, and hope the final report made sense.

That works for one review.

It does not work as well as a repeatable system.

The problem is that SEO review depends on source material the agent cannot guess. It needs to know how you sound, who you write for, what you have already published, what links are real, and what SEO moves you actually want to allow.

If that context only lives in your head, the agent won’t be able to do its job.

So I separated the system into folders. Each folder answers a different question before the agent starts giving advice.

drafts/

This folder answers one simple question:

What post are we reviewing?

If you’re working in a local markdown file, save the finished draft in your writing-drafts folder (or whichever folder you prefer).

Do not put raw notes, half-written ideas, research dumps, or alternate versions in here unless you want the agent to get confused about which thing is the actual post.

In my current setup, the main input is usually a Substack share draft link instead of a local file. Why? Because I want to include all the images for my post so the review system can suggest how to properly improve my image alt text.

That means the drafts/ folder can stay empty for that run.

But I still keep the folder because it gives me a fallback.

The important rule is simple: The draft should already be written.

This system starts after the writing is mostly done. It is reviewing the publishing layer around the post, not helping me think through the blank page.

writer-context/

This is the folder that makes the review feel like it belongs to you.

It answers two questions:

1. What should the agent preserve?

2. Who is the post really for?

This is the most important folder for writers.

Most SEO tools are good at telling you how to become more searchable. They are not as good at knowing which parts of your writing should stay weird, specific, personal, or imperfect.

That is what writer-context/ is for.

In the starter version, I would include three files:

seo-reviews/
  writer-context/
    voice-guide.md
    reader-profile.md
    seo-rules.md

The first two files should be personal to your publication.

The third file can be mostly the same for everyone.

Let me show you what I mean.

1. voice-guide.md

This file tells the agent how your writing should sound and what it should protect.

This does not need to be fancy. In fact, I think it works better when it is plain.

Here is a version I would use for this newsletter: