seo-flow

This skill orchestrates the full SEO workflow by running each phase in sequence. You are a guide walking the user through each phase. Do not rush. Requirements come first — most SEO work fails because someone optimized a page before deciding what query it should win, for whom. Each phase must be completed and confirmed before moving to the next.

Example prompts

• "Run the full SEO flow for this site"
• "Walk me through SEO from scratch"
• "Improve my site's search ranking end to end"
• "Full SEO audit and fix"

The Sequence

1. Discover      → Grill out requirements, capture the brief
2. Keywords      → Choose targets, map intent to pages
3. On-page       → Titles, meta, headings, schema, AI-search
4. Technical     → Crawlability, indexing, canonicals, sitemap
5. Performance   → Core Web Vitals (LCP, INP, CLS)
—
6. Audit         → Run separately when there are pages to check

Rules

1. At the start, tell the user what the full sequence looks like (phases 1-5, with audit available separately) and ask if they want to skip any. Common skip patterns:

   • Already know the target keywords → skip Keywords
   • Tuning one existing page, not the site → skip Technical
   • Static site with no measured speed problem → skip Performance
   • Just want a health check → jump straight to Audit

2. Before each phase, announce which phase you are entering and what it produces. Example: "Phase 2: Keywords. I'll research targets and produce .seo/KEYWORDS.md mapping each keyword-cluster to a page. Ready?"

3. During each phase, read the corresponding SKILL.md and follow its full instructions. Do not summarize or abbreviate it. Run it properly.

4. After each phase, summarize what was produced (file name, key decisions, open questions) and ask: "Ready to move to the next phase?" Wait for confirmation.

5. Between phases, check whether the previous output changes the next phase. The Keywords map decides which pages On-page touches; the brief's constraints (static site, no JS, what's editable) narrow every later phase.

6. The user can stop at any point. If they say "that's enough," summarize where they are in the sequence and what the next phase would be on return.

Phase Details

Phase 1: Discover

Read the grill-me skill at ~/.pi/agent/skills/grill-me/SKILL.md and follow it to resolve the requirements. Grill until you have concrete answers to:

• Goal — organic clicks, AI-search citations, a specific query, or local visibility? Pick the primary one.
• Target pages and the topic/query each should win.
• Audience and the job they are trying to do when they search.
• Current state — existing traffic, Search Console access, known problems.
• Constraints — platform/CMS, what is actually editable, whether the site is static or JS-rendered, publishing cadence.
• Competitors — who currently ranks for the targets.

Then write .seo/BRIEF.md:

# SEO Brief

## Goal

[The one primary outcome. Traffic / AI citations / a query / local.]

## Targets

| Page (URL or path) | Topic / query it should win | Intent |
| ------------------ | --------------------------- | ------ |

## Audience

Who searches, and the job they are doing.

## Current state

Traffic, Search Console access, known issues.

## Constraints

Platform, what is editable, static vs JS-rendered, cadence.

## Competitors

Who ranks for the targets today.

## Success metric

The single number that tells us this worked.

Produces: .seo/BRIEF.md. Transition: "The brief is saved. Next is Keywords, where we choose what to target and map intent to pages. Skip if you already know your keywords. Continue?"

Phase 2: Keywords

Read ~/.pi/agent/skills/seo-keywords/SKILL.md and follow it. Produces: .seo/KEYWORDS.md — keyword-cluster → page map with intent and SERP notes. Transition: "Targets are mapped. Next, On-page: titles, meta, headings, and schema for those pages. Continue?"

Phase 3: On-page

Read ~/.pi/agent/skills/seo-onpage/SKILL.md and follow it for each target page. Produces: Edited pages (metadata, headings, intro, internal links, structured data). Transition: "On-page is done. Next, Technical: making sure those pages can be crawled and indexed. Continue?"

Phase 4: Technical

Read ~/.pi/agent/skills/seo-technical/SKILL.md and follow it. Produces: Fixes to robots, sitemap, canonicals, indexability, redirects. Transition: "Technical is clean. Next, Performance: Core Web Vitals. Continue?"

Phase 5: Performance

Read ~/.pi/agent/skills/seo-performance/SKILL.md and follow it. Produces: Core Web Vitals fixes (LCP, INP, CLS). Transition: "The flow is complete. Brief and keyword map are saved under .seo/. When you want a scored review of the live pages, run the audit and I'll check them against the brief."

The flow ends here. Phase 6 is not automatic.

Phase 6: Audit (on request only)

Runs only when the user asks, and only when there are built or live pages to inspect. Read ~/.pi/agent/skills/seo-audit/SKILL.md and follow it. Produces: .seo/AUDIT.md — prioritized, falsifiable action plan.

Artifacts

All flow artifacts live under .seo/ at the project root:

.seo/
├── BRIEF.md      ← Phase 1: goal, targets, audience, constraints
├── KEYWORDS.md   ← Phase 2: keyword-cluster → page map
└── AUDIT.md      ← Phase 6: prioritized findings against the brief

If the User Returns Mid-Flow

Check .seo/ for existing artifacts. If BRIEF.md or KEYWORDS.md exist, read them to see where they left off, and resume from the next incomplete phase.