Skip to content
BranchesTags

Latest commit

 

History

2 Commits

Folders and files

NameName
Last commit message
Last commit date
skills
skills
 
 
README.md
README.md
 
 
install.bat
install.bat
 
 
install.sh
install.sh
 
 

Repository files navigation

SEO AI Team

A complete SEO audit system powered by Claude Code. Run full technical SEO audits and Search & AI Retrieval audits for any client — producing professional deliverables including scorecards, ICE-scored implementation specs, content briefs, and technical findings reports. Everything is designed to paste directly into Notion.

Built by The AI Impact

What You Can Do After Setup

  • Run a complete SEO Audit covering technical health, on-page optimization, content quality, and AI retrieval readiness
  • Run a Search & AI Retrieval Audit with live SERP data, AI Overview detection, and competitive gap analysis
  • Onboard clients professionally with intake forms, data request checklists, and a structured kickoff agenda
  • Hand implementation specs directly to your developer — every fix includes exact copy or code, nothing to interpret

The Skills

Four skills work together as a complete SEO team. Each one hands off to the next.

/client-onboarding  ──►  /product-marketing-context  ──►  /seo-audit-report
                                                      ──►  /search-retrieval-audit

/client-onboarding

Generates three client-ready documents before your kickoff call:

  • Intake Form — 8 universal questions + service-specific add-ons (under 14 total so clients actually fill it out)
  • Data Request Checklist — every export the client needs to provide, with step-by-step instructions
  • Kickoff Call Agenda — 30-minute structured agenda with real conversation prompts

Supports 6 engagement types: SEO Audit, Search & AI Retrieval, CRO Audit, Content Strategy, Paid Ads, Email Sequence.

/product-marketing-context

Creates .claude/product-marketing-context.md — a shared context document that every other skill reads automatically. Run it once per client after your kickoff call. Covers 14 sections: product overview, target audience, personas, pain points, competitive landscape, differentiation, objections, switching dynamics, customer language, brand voice, proof points, goals, revenue driver pages, and constraints.

All downstream skills read this file before asking questions — so you never repeat yourself.

/seo-audit-report

Runs a full 9-phase SEO audit pipeline. Produces 4 deliverables:

  • SEO Analysis — 7-dimension scorecard (Crawlability, Technical Performance, On-Page, Content/E-E-A-T, Structured Answer Readiness, Entity Clarity, Internal Architecture)
  • Implementation Specs — 5-7 ICE-scored specs with exact copy, JSON-LD blocks, and precise technical fixes
  • Technical Findings — per-page detail for every audited URL
  • Content Briefs — for keyword gaps where no content currently exists
  • Screenshots — desktop and mobile full-page captures via Playwright

Uses Playwright for live page analysis and the free Google PageSpeed API for Core Web Vitals.

/search-retrieval-audit

Runs a full 10-phase Search & AI Retrieval audit. Produces 4 deliverables:

  • Search Retrieval Analysis — 7-dimension scorecard including Query Coverage, AI Overview Alignment, and Competitive Gap
  • Implementation Specs — 5-7 ICE-scored specs with exact content to publish
  • Query Coverage Map — full table of every query checked, with ranking position, snippet ownership, and AIO citation state
  • Content Briefs — for new pages to fill coverage gaps

Requires SerpApi for live Google SERP data including AI Overview detection.

How the Skills Work Together

Before kickoff call
  └─ /client-onboarding
       └─ Intake Form → send to client
       └─ Data Request Checklist → send to client
       └─ Kickoff Call Agenda → use on the call

After kickoff call
  └─ /product-marketing-context
       └─ Creates .claude/product-marketing-context.md
       └─ All future skills read this automatically

Run the audits (any order, same day or different days)
  └─ /seo-audit-report
       └─ {Client}-SEO-Analysis.md
       └─ {Client}-Implementation-Specs.md
       └─ {Client}-Technical-Findings.md
       └─ {Client}-Content-Briefs.md
       └─ Screenshots

  └─ /search-retrieval-audit
       └─ {Client}-Search-Retrieval-Analysis.md
       └─ {Client}-Implementation-Specs.md
       └─ {Client}-Query-Coverage-Map.md
       └─ {Client}-Content-Briefs.md

Tip: If you run both audits for the same client, tell Claude at the start of the search retrieval audit that the SEO audit has already run. The skill will cross-reference the findings instead of duplicating work.

What the Skills Produce

SEO Audit (/seo-audit-report)

Deliverable What's in it
SEO Analysis 7-dimension scorecard, overall score /10, prioritized recommendations
Implementation Specs 5-7 specs, each with ICE score, exact fix (copy/code/config), and expected impact
Technical Findings Per-page tables: crawlability, indexation, CWV, mobile, HTTPS, URL structure, on-page
Content Briefs Target keyword, heading structure, key points, schema, internal linking targets
Screenshots Desktop (1280px) + mobile (390px) full-page captures

Search & AI Retrieval Audit (/search-retrieval-audit)

Deliverable What's in it
Search Retrieval Analysis 7-dimension scorecard, Business Impact Summary, competitive matrix
Implementation Specs 5-7 specs with exact content (not descriptions — the actual words)
Query Coverage Map Every query: ranking position, snippet owner, AIO citation state
Content Briefs New page briefs for query clusters with no existing content

Installation

Step 1 — Clone this repo

git clone https://github.com/stevenflanagan1/seo-ai-team.git
cd seo-ai-team

Step 2 — Run the installer

Mac / Linux:

chmod +x install.sh
./install.sh

Windows (WSL): Double-click install.bat — or open WSL and run ./install.sh from the repo folder.

Manual install:

mkdir -p ~/.claude/skills/client-onboarding/references
mkdir -p ~/.claude/skills/product-marketing-context
mkdir -p ~/.claude/skills/seo-audit-report
mkdir -p ~/.claude/skills/search-retrieval-audit

cp skills/client-onboarding/SKILL.md ~/.claude/skills/client-onboarding/SKILL.md
cp skills/client-onboarding/references/* ~/.claude/skills/client-onboarding/references/
cp skills/product-marketing-context/SKILL.md ~/.claude/skills/product-marketing-context/SKILL.md
cp skills/seo-audit-report/SKILL.md ~/.claude/skills/seo-audit-report/SKILL.md
cp skills/search-retrieval-audit/SKILL.md ~/.claude/skills/search-retrieval-audit/SKILL.md

Step 3 — Configure MCP Servers

Add these to ~/.claude/settings.json under "mcpServers":

Playwright — Required for screenshots and live page analysis:

"playwright": {
  "command": "npx",
  "args": ["@playwright/mcp@latest"]
}

SerpApi — Required for the Search & AI Retrieval Audit. Get your key at serpapi.com (free plan: 250 searches/month):

"serpapi": {
  "type": "http",
  "url": "https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp"
}

Critical: Use "type": "http" for SerpApi — not "type": "sse". Using the wrong protocol is the most common setup error and silently breaks the connection.

Full settings.json example:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    },
    "serpapi": {
      "type": "http",
      "url": "https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp"
    }
  }
}

Gamma (optional) — generates client presentation slide decks. Enable it in your Claude settings under Integrations.

Step 4 — Verify

Open a new Claude Code session and type /client-onboarding. If Claude asks for your client's name, everything is working.

Client Project Setup

Each client gets their own folder. This is important — the product marketing context file is stored inside the client folder, and all skills read it automatically when you run Claude Code from that folder.

Recommended structure:

Clients/
  acme-corp/
    .claude/
      product-marketing-context.md   ← created by /product-marketing-context
    Acme-SEO-Audit-2026-03-01/       ← deliverables land here
    Acme-Search-Retrieval-Audit-2026-03-05/

To start a new client:

  1. Create a folder with the client's name
  2. Open Claude Code from inside that folder
  3. Run /client-onboarding before the kickoff call
  4. Run /product-marketing-context after the kickoff call
  5. Run /seo-audit-report and/or /search-retrieval-audit

Running the Workflow

Step 1 — Client Onboarding (/client-onboarding)

Run before your kickoff call.

What it asks:

  • Client name
  • Which service(s) — SEO Audit, Search & AI Retrieval, CRO, Content Strategy, Paid Ads, or Email
  • Any context you already have (optional)

What it produces:

  • {Client}-Intake-Form.md — ready to paste into Typeform, Google Forms, or Notion
  • {Client}-Data-Request-Checklist.md — step-by-step export instructions for every platform
  • {Client}-Kickoff-Call-Agenda.md — 30-minute structured agenda with conversation prompts

Step 2 — Product Context (/product-marketing-context)

Run after your kickoff call, once you have the intake responses and your notes.

What it asks: 14 sections of positioning and messaging information. The most valuable: customer language (verbatim phrases), top objections, key proof points, and revenue driver pages.

What it produces: .claude/product-marketing-context.md inside your client folder. Every skill reads this file before asking questions.

Step 3 — SEO Audit (/seo-audit-report)

Run any time after the product context is set up.

What it asks:

  • URL(s) to audit
  • Site type — SaaS, E-commerce, Blog, or Local Business
  • SEO goal
  • Target keywords (5-10)

Optional: GSC CSV export, monthly organic traffic, audit scope (Focused / Standard / Comprehensive), Gamma slide deck.

MCP tools used:

  • Playwright — screenshots, source inspection, heading/schema/link extraction
  • Google PageSpeed API (free, no key needed) — Core Web Vitals
  • Gamma — client presentation (optional)

What it produces: SEO Analysis, Implementation Specs, Technical Findings, Content Briefs, Screenshots.

Step 4 — Search & AI Retrieval Audit (/search-retrieval-audit)

Run same day as SEO audit or separately.

What it asks:

  • URL(s) — 1-5 priority pages
  • Business description and target audience
  • Seed keywords (5-10)
  • Competitors (1-3 domains)

Optional: GSC CSV (strongly recommended — enables Zero-Click Risk detection), audit scope (Test / Standard / Deep).

Audit scope tiers:

Scope Queries API Calls When to use
Test 40-60 ~50 Validation / free plan
Standard 80-120 ~100 Typical paid engagement
Deep 150-200 ~180 Complex products

For Standard or Deep scope (80+ queries): Use the included serp-batch-runner.py script. Running 80+ queries through the MCP tool fills Claude's context window. The batch script calls the REST API directly, saves results to a JSON file, and resumes automatically if interrupted.

# Edit the config at the top of the file first
python3 skills/search-retrieval-audit/serp-batch-runner.py

What it produces: Search Retrieval Analysis, Implementation Specs, Query Coverage Map, Content Briefs.

Using Your Deliverables

All files paste directly into Notion. Copy the full markdown and paste into a Notion page. Headings, tables, and bullet lists all render cleanly.

ICE scores tell you what to fix first. All implementation specs are sorted by ICE score — Impact × Confidence × Ease, max 125. Start with specs that have high Impact (4-5) combined with high Ease (4-5).

Implementation Specs are ready to hand off. Every spec contains the exact fix — exact copy, exact JSON-LD, or exact redirect rule. No interpretation needed.

Content Briefs are ready to write against. Each brief includes the target keyword, heading structure, key points, schema to implement, and internal linking targets.

What to Run After the Audit

Once audit deliverables are in your client's hands, these skills extend the work:

  • /schema-markup — implement the JSON-LD schema blocks from your SEO audit specs
  • /copywriting or /content-strategy — turn the content briefs from either audit into published content
  • /programmatic-seo — if the query coverage map reveals a large gap that could be filled with templated pages at scale
  • /cro-audit-report — after SEO and search visibility are addressed, layer in conversion optimization

Common Issues

SerpApi connection failed — Check that your config uses "type": "http" and not "type": "sse". Restart Claude Code after making changes to settings.json.

PageSpeed API rate limit — The free Google PageSpeed API occasionally rate-limits without warning. The audit skips Core Web Vitals for that page and logs it in assumptions. Not a blocker.

PowerShell execution blocked on Windows — Right-click the file → Properties → check the Unblock checkbox at the bottom → Apply.

"No product context found" — Run /product-marketing-context first from inside the client's project folder. Make sure Claude Code is running from that folder.

Skill not recognised — Check that the file exists at exactly ~/.claude/skills/{skill-name}/SKILL.md. The folder name must match the skill name exactly. The file must be named SKILL.md.

Cookie banner blocks page capture — Claude takes a snapshot first to identify the dismiss button before clicking. If it can't be dismissed after one attempt, it proceeds with the banner visible.

Prerequisites

  • Claude Code — claude.ai/code
  • Node.js — required for Playwright MCP. Run npx --version to confirm. Install from nodejs.org if missing.
  • SerpApi account — required for /search-retrieval-audit. Free plan includes 250 searches/month. Sign up at serpapi.com.
  • Python 3 — required only if using the serp-batch-runner.py script for Standard/Deep scope audits.

System Versions

  • SEO Audit: v1.1.0
  • Search & AI Retrieval Audit: v1.0.0
  • Client Onboarding: v1.0.0
  • Product Marketing Context: v1.0.0

License

MIT

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

4 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages