SEO Coach — An AI Coach That Helps You Actually Learn SEO

Not another SEO report. A coach that stays with you on a real site until you can observe, decide, act, and verify for yourself.

🇹🇼 Traditional Chinese → README.zh-TW.md ｜ 🇨🇳 Simplified Chinese → README.zh-CN.md

Current version: 2.5.0｜Release notes → RELEASE-2.5.0.md｜Changelog → CHANGELOG.md
To check whether your copy is current, just ask the coach "is there a new version?" — it compares against GitHub and tells you.

SEO Coach is an open-source AI coaching Skill built from public, verifiable SEO practice and organized as a beginner-first learning system.

It is not an SEO audit, checklist, or answer library. It is a site-based apprenticeship: the coach demonstrates one small step, works through the next one with you, then gradually removes support until you can repeat the judgment on an unfamiliar page.

Why SEO Coach Exists

I have always believed that SEO is a game played well by a small minority.

Useful SEO is not just knowing how to write a title or how long an article should be. The advantage comes from how you observe a search result, judge an opportunity, decide with incomplete information, and find the mechanism when a test fails. Those judgments create competitive advantage, so very few teachers will disclose every private research method, client lesson, and decision framework they actually rely on.

SEO Coach is not designed to pretend that a free Skill can turn you into another SEO master.

It gives you a low-cost but sound beginning: learn the public and verifiable fundamentals, become genuinely interested in SEO, rank your first keyword on your own site, and start developing your own reasoning, observations, and ideas.

Using SEO Coach will not instantly give you the judgment of an experienced SEO master. That gap still comes from years of research, practice, failure, and judgment. It can, however, help you avoid many beginner mistakes and build a strong starting point at very low cost.

That is the difference between SEO Coach and another information product: it does not promise to hand you a secret method. It helps you build the foundation from which your own method can eventually emerge.

Learning SEO Is Not the Same as Reading About SEO

A tutorial does not prove you can make a decision. An audit does not prove you know what to do next.

SEO Coach trains you to complete a real loop:

Goal and safety
  → pre-change baseline
  → crawl and index evidence
  → query, SERP, and page ownership
  → one low-risk reversible change
  → live revalidation
  → evidence-based follow-up
  → keep, revert, or test again
  → repeat on an unfamiliar case

Progress is not measured by modules completed. It is measured by whether you can perform after a demonstration, with guidance, independently, and again later on a different case.

How the Coach Teaches

The coach chooses the next useful step

Beginners are not asked to choose a module, tool, or report they do not yet understand. When your goal is clear, the coach selects the smallest dependency and explains what to inspect, why it matters, and what counts as complete.

Each turn normally teaches one concept and advances one observable check. It does not open with a full-site audit.

Demonstration → guided practice → independence

You are not forced to guess. The coach demonstrates the first case, works through the second with you, and gives you the third to complete independently. If you say “I don’t know” or “show me,” it demonstrates instead of continuing to quiz you.

Evidence before conclusions

The coach separates live observations, official guidance, third-party estimates, learner-authorized data, and what remains unobserved. A healthy result is valid evidence; it will not invent defects to make the session look useful.

Every change is rechecked

You preserve the baseline and rollback path, make one bounded change, reopen the live page, and review GSC or GA4 only after an appropriate time window. An edit is not treated as success until it has been verified.

Three Main Learning Tracks

Zero to a First Verifiable SEO Result

Complete one full project on your own site: goal, baseline, indexing evidence, search opportunity, one reversible change, technical revalidation, delayed review, and an unfamiliar-page capstone.

The outcome is not a report. It is a workflow you can repeat.

Search Opportunity Lab

Learn query selection, search intent, content gaps, site architecture, page ownership, and content briefs.

No Ahrefs, Semrush, or DataForSEO is required for the foundational practice:

Open a new incognito/private window and record query, location, language, device, and date.
The coach demonstrates the first organic result.
You assess the second result together.
You assess the third independently.
Add only two more results if the first three still show mixed intent.
Stop at “insufficient evidence” when the evidence does not support a verdict.

A competitor covering a topic does not mean you should. A competitor omitting it does not make it an opportunity. A verified gap must also fit real demand, your existing pages, your ability to deliver credibly, and business value.

Free tools (keyword expansion, difficulty, SERP, rank checking, traffic estimates, AI visibility) are not dumped on you in round one. They unlock by stage: once you can read the screen, tools enter as a verification layer — you state your judgment first, then open the tool to compare. Where the two disagree is the best teaching material available. Every tool number is labelled a third-party estimate, never presented as internal Google or AI-platform data.

Four-Article SEO Writing Apprenticeship

This is not four AI-written articles. It is a progression that returns research and writing judgment to the learner:

A1: coached demonstration and guided work.
A2: same-pattern practice with less support.
A3: transfer to a different intent or page type.
A4: an unprompted capstone.

Each article retains SERP evidence, a brief, original and revised drafts, feedback, QA, publishing, and observation records. Graduation uses eight evidence gates rather than a single AI score.

What You Can Learn

The coach draws from its technical, content, linking, and measurement library as your situation requires:

Crawling, indexing, robots.txt, sitemaps, canonicals, redirects, HTTPS, and basic structured data.
Titles, headings, descriptions, URLs, images, and page promises.
GSC, GA4, baselines, and before/after evidence.
Candidate queries, intent, SERPs, content gaps, and page mapping.
Content quality, E-E-A-T, internal links, content maintenance, and SEO writing.
Traffic drops, redesigns, new sites, CMS issues, and common SEO myths.
Foundational topical maps, SERP features, AI search readiness, ecommerce, and local SEO.

The 18 modules are an on-demand coaching library, not a syllabus you must complete in order.

Local GSC Search Panel

If an existing GSC API connector is already connected, open assets/gsc-dashboard/index.html and the panel will load the current and optional comparison periods automatically. Without that connector, import CSV, TSV, or JSON manually. The panel computes clicks, impressions, CTR, average position, 1–3 / 4–10 / 11–20 / 21–30 buckets, query movement, anomaly and CTR signals, and transparent rewrite-review candidates directly in the browser. Each query has a current/previous detail view, page breakdown, and matched-rule context; queue status and notes are saved locally.

The panel does not handle login or credentials, open its own network channel, or call Codex CLI/AI; an existing connector owns the connection and the panel only computes and stores the returned data in the browser. One template supports Traditional Chinese, Simplified Chinese, English, Japanese, and Korean; first run follows the browser language and later manual choices stay local. Its rewrite queue is a deterministic, inspectable rule list—not automatic editing—and GSC average position is not a live SERP rank. See references/59-gsc-dashboard.md for the bridge contract, formats, formulas, and limits.

Try It With Prompts Like These

I know nothing about SEO. Teach me using my own website.

I have no paid tools. Walk me through this SERP manually.

This article gets no traffic. Give me the smallest useful check first.

I want to learn SEO systematically. Track my progress until I can work independently.

For public evidence, the coach can demonstrate one safe read-only check. For logged-in GSC, GA4, or CMS evidence, it gives a short pointing card and accepts a screenshot instead of requiring a written report.

Persistent Learning Records

With your consent, the coach can maintain:

seo-progress.md: competence, errors, hint level, and 1/7/30-day retests.
seo-actions.md: actions, completion evidence, and next steps.
seo-strategy-workbook.md: query, SERP, gap, page ownership, and brief practice.
seo-writing-portfolio.md: four-article versions and gate evidence.
seo-ga4-log.md: metrics actually observed, baselines, and interpretation.

When you return, coaching resumes from the last skill gap. Unfinished homework is not a gate to continuing; the coach can shrink or reroute the task.

Who It Is For

Beginners who want a complete SEO decision process.
Site owners who do not know what to inspect, change, or verify first.
People who have consumed courses but never completed an evidence-backed SEO loop.
Learners without paid SEO tools.
Writers who want to produce their own SEO work instead of receiving ghostwritten AI copy.
Small brands, service businesses, publishers, ecommerce teams, and marketers who need a repeatable learning method.

What It Is Not

Not a one-click site audit or health score.
Not a promise of rankings, traffic, or indexing.
Not a done-for-you strategy, article factory, or bulk publisher.
Not a system that treats fixed KD, word count, link count, or plugin scores as truth.
Not permission to present guesses as confirmed observations.

Large migrations, severe traffic loss, mass deindexation, enterprise international SEO, programmatic page generation, and high-risk medical, financial, or legal decisions may require engineers or qualified professionals.

Installation: Give the URL to Your AI Agent

The easiest option is to paste this entire block into the AI agent you already use:

Install this SEO Coach Skill for me. Put the repository's seo-coach folder in the correct skills directory, but do not enable the optional hooks yet. When finished, verify that $seo-coach can be loaded and tell me the actual installation path.

https://github.com/akseolabs-seo/seo-coach

If your AI agent has GitHub and local-file access, it can download, place, and verify the Skill for you. Then start a new conversation and say:

Use SEO Coach to teach me SEO on my own website.

Manual fallback if your AI agent cannot install it

Cleanest option: download seo-coach.skill from Releases. It contains only the files needed at runtime.

Or clone the repository:

git clone https://github.com/akseolabs-seo/seo-coach

Place the seo-coach folder in the appropriate skills directory:

Codex:  ~/.codex/skills/seo-coach
Claude: ~/.claude/skills/seo-coach

The cloned repository also contains maintainer-only evals/ and scripts/. They are not required at runtime — delete them before installing if you prefer, or leave them; either way the Skill behaves the same.

The auto-load router under hooks/ is optional. SEO Coach works without it. To enable it, ask your agent to read hooks/README.md, explain the changes, and request your approval before installation.

Public Sources and Privacy Boundary

All SEO Coach teaching material comes from public, traceable resources curated and reorganized for this Skill, together with SEO theories and viewpoints that can be verified through public sources. These sources include official Google documentation, public courses, public websites/SERPs, and material with clear public attribution or licensing.

It does not contain any private research methods, unpublished tests, client data, private client cases, direct messages, unpublished prompts, private SOPs, or unrelated local projects. This is a deliberate boundary protecting clients, private research assets, and the integrity of the public learning edition.

SEO Coach therefore gives you a strong public foundation and a learning method—not a complete copy of any private methodology. Your own site, observations, experiments, and time are what turn that foundation into independent SEO judgment.

Before each public build, the maintainer edition runs behavioral evaluations, routing fixtures, privacy-leak tests, and package-parity validation. These test whether the Skill behaves like a coach, not merely whether the Markdown parses. Maintainer-only evals/ and scripts/ are intentionally excluded from the public installation.

Repository Structure

seo-coach/
│
│  ── Required at runtime ──
├── SKILL.md                 # Core coaching behavior and routing
├── FAILSAFE.md              # Failure modes and required behavior changes
├── references/              # Apprenticeship tracks, labs, and teaching material
├── assets/gsc-dashboard/    # Openable local GSC analysis panel
├── agents/                  # Agent UI and trigger metadata
├── hooks/                   # Optional auto-load router (works without it)
│
│  ── Documentation ──
├── README.md                # Overview and learning model
├── RELEASE-2.5.0.md         # Public marketing release notes
├── RELEASE-2.0.md           # Major release notes
├── CHANGELOG.md             # Release history
│
│  ── Maintainer only (not needed to install) ──
├── evals/                   # 92 coaching-behavior eval cases and rubric
└── scripts/                 # Validator, eval runner, build, privacy tests

The Point

SEO Coach is not trying to do SEO instead of you or help you memorize more terminology.

Its job is to demonstrate beside you, guide your practice, correct weak judgments, preserve the evidence, and gradually remove support until you can make a reliable decision on the next unfamiliar problem.

Disclaimer

SEO outcomes depend on competition, site history, technical conditions, content quality, and changes in search systems. SEO Coach is an educational tool and does not guarantee rankings, traffic, or indexing. Preserve rollback paths for risky changes and verify the live result.

License

MIT License — free to use, modify, and distribute. Please retain attribution for commercial use.