fellowship-dev seo-ops
Run an evidence-first SEO audit, separate machine-observable defects from judgment calls, and turn verified incidents into reusable operational knowledge.
When to Use
- Pre-launch audits and migration checks
- Production SEO health checks and recurring smoke tests
- Duplicate-host, canonical, redirect, sitemap, robots, or hreflang investigations
- Metadata, social preview, structured-data, and internal-link reviews
- Traffic/indexing incidents after a deploy or domain change
When Not to Use
- Keyword-volume, backlink, or competitor-market research as the primary task
- Content writing without an existing audit finding
- Search Console actions when the property owner has not authorized account access
- Interactive or JavaScript-rendered certification without a real browser
Prerequisites
Read the target repo's operational playbook first. Resolve these site-specific inputs there; never add them to this public skill:
| Input | Example shape |
|---|---|
| Canonical origin | https://example.com |
| Alternate hosts | https://www.example.com |
Locales and x-default |
en, es, root fallback |
| Sitemap and robots URLs | /sitemap.xml, /robots.txt |
| Search Console property | URL-prefix or Domain property |
| Last verified date | YYYY-MM-DD |
Verify the local runtime:
python3 --version
curl --version
Audit Modes
| Mode | Scope | Gate |
|---|---|---|
prelaunch |
Canonical host, redirects, robots, sitemap, metadata, locale clusters, structured data, internal links | Block launch on Critical/High defects |
production |
Same checks against the deployed origin plus representative browser rendering | Open/dedupe actionable issues |
incident |
One failing signal and its adjacent boundaries | Do not broaden until the failure is reproduced |
recurring |
Stable critical subset with machine-readable output | Never certify interactive checks from static evidence |
Workflow
Establish the expected topology
Record the canonical origin, alternate hosts, locale routes, sitemap, and expected redirect policy from the repo playbook. If any are unknown, report them as missing operational decisions rather than guessing.
Run the deterministic static audit
python3 skills/ops/seo-ops/scripts/audit.py \ https://example.com \ --compare-origin https://www.example.com \ --max-pages 25 \ --output /tmp/seo-audit.mdUse JSON for automation:
python3 skills/ops/seo-ops/scripts/audit.py \ https://example.com \ --compare-origin https://www.example.com \ --format json > /tmp/seo-audit.jsonThe script checks status/redirect chains, duplicate hosts, canonicals, robots, sitemap discovery, indexability, metadata, headings, hreflang, static JSON-LD, images, and sampled internal links. It does not pretend to measure rankings, field Core Web Vitals, or rendered JavaScript.
Complete the manual control set
Read references/checklist.md. Mark every control
pass,fail,blocked,not-applicable, orneeds-judgment. Attach a URL, header, DOM selector, API response, or screenshot to every failure.Add browser evidence where required
Use Playwright, Navvi, or another real browser to inspect the rendered DOM:
({ canonical: document.querySelector('link[rel="canonical"]')?.href, alternates: [...document.querySelectorAll('link[rel="alternate"][hreflang]')] .map((node) => ({ lang: node.hreflang, href: node.href })), jsonLd: [...document.querySelectorAll('script[type="application/ld+json"]')] .map((node) => node.textContent), lang: document.documentElement.lang, title: document.title, h1: [...document.querySelectorAll('h1')].map((node) => node.textContent?.trim()), })Warning: Static HTML,
curl, or a JavaScript bundle search may diagnose an interactive/rendered problem but cannot certify it as passed.Check canonical-signal agreement
Compare redirect destination, HTML canonical, HTTP
Linkalternates, HTML hreflang, sitemap URLs, structured-data URLs, Open Graph URL, and internal links.Signals Verdict Action All point to one HTTPS origin and equivalent locale paths Pass Record evidence Alternate host serves 200 while canonical host also serves 200 Critical Add one-hop permanent host redirect Canonical conflicts with hreflang or sitemap High Fix the generating source, then re-audit every locale Only cosmetic trailing-slash variation with one-hop redirect Low Standardize when convenient No explicit canonical but every other signal agrees Medium Add self-referencing canonical; do not claim duplicate content without evidence Validate multilingual clusters
Require self-reference, reciprocity, valid language/region codes, canonical URLs, 200 responses, and representative visible translated copy. URL and
<html lang>alone do not prove localization.Classify findings
Severity Meaning Response Critical Search engines/users receive duplicate, blocked, wrong-host, or non-indexable primary content Fix before launch or immediately in production High Strong canonical, hreflang, sitemap, redirect, or rendering conflict Fix this release/week Medium Missing/weak metadata, incomplete structured data, or sampled broken links Prioritize with content owners Low Hygiene or optimization opportunity with no demonstrated indexing impact Backlog Info Observation requiring Search Console, analytics, or human judgment Do not present as a defect Write the report
Start with the outcome, not a score. Include:
- expected topology and audit mode
- Critical/High findings first
- exact evidence and reproduction command
- expected versus actual behavior
- smallest safe fix and rollback
- static/browser/Search Console evidence boundaries
- passed controls worth preserving as regressions
- blocked checks and what access would unblock them
Feed verified learning back into the system
Read references/casebook.md before diagnosing a repeated pattern. After an investigation:
Knowledge Destination Reusable rule, false positive, command, or decision pattern This skill's checklist/casebook via PR Client host, locale, property ID, account, or last verification Target repo playbook Executable production invariant Target repo's Flowchad/e2e flow Framework implementation default Framework/template repo Add only reproduced, source-backed lessons. Include the question/suggestion, evidence, conclusion, reusable rule, and regression check. Never treat an old conversation as evidence by itself.
Decision Boundaries
Read references/questions.md when an investigation starts from a question, suggestion, or disputed recommendation. Add a new answer only after verifying the rule and its exceptions.
| Question | Answer |
|---|---|
Can curl prove canonical and HTTP redirects? |
Yes, for returned headers/HTML |
Can curl prove rendered JSON-LD or locale copy? |
No; use a browser |
Is site: search an index-coverage measurement? |
No; use Search Console |
| Does a Lighthouse SEO score certify technical SEO? | No; it samples a small control subset |
| Should every audit recommend schema? | No; recommend only truthful types supported by page content |
| Should every locale canonicalize to the default language? | No; each genuine locale normally self-canonicalizes |
| Can a redirect rule work on a DNS-only Cloudflare hostname? | No; Cloudflare must receive proxied HTTP traffic |
Error Handling
Blocked or protected target — report the status/protection mechanism. Do not interpret a challenge page as the audited page.
JavaScript-only metadata — capture raw and rendered DOM separately. Report disagreement as a rendering risk, not as two independent defects.
No Search Console access — complete observable checks and mark index coverage, selected canonical, and query performance as blocked.
Rate limiting or unstable responses — lower --max-pages, preserve partial evidence, and do not convert missing samples into failures.
Conflicting tools — prefer primary response/DOM evidence. Record tool versions and explain the conflict.
Critical Rules
- Never mutate DNS, redirects, Search Console, or production code during an audit without explicit authorization.
- Never expose credentials, private Search Console data, or client identifiers in the public skill or reports.
- Never certify interactive/rendered behavior without browser evidence.
- Never turn rules of thumb such as title/description character counts into hard ranking claims.
- Never use an aggregate score to hide a Critical or High defect.
- Always distinguish observed facts, source-backed rules, and recommendations.