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: 3.0.0｜What's new in 3.0 → CHANGELOG.md｜Earlier release notes → RELEASE-2.5.0.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. Each practical judgment keeps its limit, next discriminating check, and later transfer case.

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:

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

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.

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.

Local GSC Search Panel

Connect Search Console once, in three steps, and both the browser panel and the coach read the same data: (1) in Google Cloud, enable the Google Search Console API, create a service account and download its JSON key to ~/.seo-coach/gsc-service-account.json; (2) in Search Console → Settings → Users and permissions, add the service account's email as a Restricted user; (3) run node assets/gsc-tools/gsc.mjs check, then node assets/gsc-tools/gsc.mjs serve and open http://127.0.0.1:8791/. The coach walks you through it one step at a time and never asks you to paste the key into the chat (references/65-gsc-api-setup.md). No site yet? Click "Load demo data" and practise on clearly labelled synthetic data.

The panel has 13 tabs (overview, all-sites list, 12-month decay heatmap, new pages, rank tracking, striking distance, cannibalization, language versions, segment trends, indexing checks, change notes, raw data export, and the coach's action queue), a detail drawer for any query or page, previous-period or year-over-year comparison, a brand / non-brand split, markers for Google's announced ranking updates, and a "Copy evidence card" button so you can paste what you see to the coach instead of a screenshot. The key is read only by the local tool (read-only scope, bound to 127.0.0.1); the panel page handles no credentials, calls no AI, and computes everything deterministically in the browser. GSC rows are not written to local storage—only your own notes and settings, which you can export and import. Three languages ship built in (Traditional Chinese, Simplified Chinese, and English); the coach sets the panel language with node assets/gsc-tools/locale.mjs --use and generates any other language once. The action queue lists review candidates, not instructions, and GSC average position is not a live SERP rank. Formulas, the host-connector contract, and limits: references/59-gsc-dashboard.md.

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.

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.

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.

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

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

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/    # Local GSC panel
├── assets/gsc-tools/        # Runtime tools: GSC API connection (gsc.mjs) and panel language (locale.mjs)
├── 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/                   # 104 coaching-behavior eval cases and rubric
└── scripts/                 # Maintainer tools: validator, eval runner, build, panel and 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.