seo-audit

Today is ${today}.

${var} — the target sites, comma-separated (an origin, not a page: https://www.example.com). Each site is audited whole and independently. A bare host gets https:// prepended. A path in ${var} (…/docs) still works — its origin is what gets crawled.

Empty ${var} → there is nothing to audit. This skill has no built-in default site (it ships general-purpose). Log SEO_NO_TARGET, send no notification, and exit clean — a daily "set a target" ping would just get muted. Set the target once in the dashboard (the skill's var) and it runs from the next tick.

What this does

Discovers every page a site publishes, audits all of them, compares the result against the previous run, and reports. The heavy lifting (discovery, fetching, parsing, checking) happens in scripts/seo-audit.mjs, which returns machine-readable findings so you reason over facts instead of eyeballing HTML.

Discovery is sitemap-first: robots.txt → sitemap.xml (following sitemap indexes), honouring the robots * Disallow rules, falling back to a one-hop crawl of the homepage's internal links when a site has no sitemap. That is the same list Google works from, so auditing it is auditing what actually ranks.

Auditing the whole site — not three sample templates — is what makes the cross-page checks possible: duplicate titles, duplicate meta descriptions, canonicals pointing away from their own page, and pages linked but missing from the sitemap. None of those are visible from inside a single page, and all of them are ways a site quietly loses search traffic.

This is on-page and technical SEO only — no keyword research, rank tracking, or backlink analysis. If a finding would need those, say so rather than guessing.

Capability notes (read before editing this skill)

This skill is mode: read-only, and that is load-bearing:

• The auditor is Node, not Python, because Bash(node:*) is in the read-only capability base while Bash(python3:*) is write-tier only (scripts/skill_mode.sh). Porting it back to Python would force mode: write.
• It is dependency-free stdlib Node, matching every other helper in scripts/. There is no install step. If you find yourself wanting a package, you are about to break the thing that makes this skill cheap and safe.
• You have no Write or Edit tool. Every file this skill produces is written with a shell redirection (>/>>) from an allowed command. The workflow's read-only guard reverts writes to code/config paths but preserves memory/ and output/, which is exactly where this skill writes.
• The guard also appends the ### seo-audit run-log entry from your final output, so put the log detail there (step 8), never a second self-written entry.

PAGESPEED_API_KEY is optional. When set, the script folds in Core Web Vitals — it reads the env var itself, so never pass the key as a command-line argument; the workflow's permission analyzer blocks $SECRET expansions on the Bash line. It prefers real-user field data (Chrome UX Report p75 — LCP, INP since it replaced FID in 2024, and CLS — the metrics Google's page-experience signal actually uses), preferring page-level then origin-level, and falls back to the lab Lighthouse score only when a URL has too little traffic for field data (the finding says which). In site mode it samples the entry page only (PageSpeed is slow and quota-limited; per-page Lighthouse runs would dominate the runtime). When unset, Core Web Vitals are simply absent. That is a degraded run, not a failed one — don't mention the missing key in the notification.

Workflow

1. Resolve the targets. Split ${var} on commas and trim. No confirmation step — this runs unattended, so treat ${var} as final. If ${var} is empty, there is no site to audit: log SEO_NO_TARGET (Step 8), send no notification, and exit. Do not invent a default origin.

2. Audit each site:

   node scripts/seo-audit.mjs --site <origin> --format json
   

   Useful flags: --max N (page cap, default 50) and --concurrency N (default 4 — politeness as much as speed). Add --check-links on the first site only; it probes up to 40 links and is the slow part. In site mode links are deduped across every page first, so a footer link is checked once for the whole site rather than once per page.

   A site where no page could be fetched returns "ok": false and exits 1. Record it and keep going — one dead site must not abort the others. Individual pages that fail are reported inside the run as the pages_fetched finding.

3. Read the findings, don't re-derive them. The report has two levels:

   • pages[] — one per URL, each with its own score, summary, and findings (same check / status / message / detail shape as before).
   • site_findings[] — the cross-page checks: pages_fetched, duplicate_titles, duplicate_descriptions, canonical_targets, sitemap_coverage.

   The headline score is the mean page score, and discovery records how the URLs were found (sitemap or crawl), how many existed, how many were audited, and whether the --max cap truncated the run.

4. Diff against the previous run. Every run writes its own timestamped snapshot (step 5), so the baseline is the newest snapshot that already exists — i.e. the previous run's, since this run hasn't written its own yet. Filenames sort chronologically, so:

   PREV=$(ls -1 memory/seo-audit/*.json 2>/dev/null | sort | tail -1)
   

   $PREV is the baseline (empty on the very first run). Match pages by URL, per site, and compare:

   • New fails — a check that was pass/warn yesterday and is fail today.
   • Site score movement — any change of 3+ points, either direction.
   • New / removed pages — URLs in today's sitemap that weren't in yesterday's, and vice versa. A page vanishing from the sitemap is a real finding; so is a new page shipping with no meta description.
   • New cross-page problems — a title or description that became a duplicate, a canonical that started pointing elsewhere.
   • Newly broken links — URLs in broken_links that were not there before.
   • Fixed — a check that was fail/warn yesterday and is pass today. Report these too; a skill that only ever delivers bad news gets muted.

   Compare like with like: a page-level score change is only meaningful against the same URL, and the site score is only meaningful when discovery.audited is roughly the same on both sides. If the page count moved a lot, say so instead of attributing the score change to the site's quality.

   If there is no previous file (first run), skip the diff and say so once.

   Three rules that stop the diff from lying. Each is here because the diff already got it wrong once:

   • Never claim a fix across an auditor version boundary. Compare auditor_version in both files. If they differ, the two runs used different rulers: report the movement but label it (auditor v1→v2 — may be the tool, not the site) and do not put it under "Fixed". A previous run announced a site had "resolved" a broken link that was only ever a bug in this script.
   • response_time never counts as fixed or regressed. It is a single sample over a network and swings hundreds of ms run to run. 866ms → 147ms is weather, not work. Still report it as a finding; just keep it out of the movement section unless it stays over threshold for 3+ consecutive runs.
   • Attribute a fix only to something a human could have changed. Markup, copy, links, headers. If you cannot name the edit that caused it, it is noise — leave it out.

5. Write this run's state before notifying, so the next diff has a baseline even if the notification step fails. One new file per run, named by a UTC timestamp — never overwrite a date-named file. This is what makes a manual re-run (or a second scheduled run) safe: it can't clobber or fail to update an earlier run's snapshot, and the diff in step 4 always picks up the newest one. Shell redirection, not the Write tool. Loop the script over every origin in ${var} and fold the per-site JSON into one snapshot — redirect the script's own output, never retype it:

   mkdir -p memory/seo-audit
   export STAMP=$(date -u +%Y-%m-%dT%H-%M-%SZ)   # e.g. 2026-07-24T13-00-07Z
   i=0; files=""
   for site in <each trimmed origin from ${var}>; do
     i=$((i+1))
     node scripts/seo-audit.mjs --site "$site" > "/tmp/seo-$i.json"
     files="$files /tmp/seo-$i.json"
   done
   node -e 'const fs=require("fs"); const sites=process.argv.slice(1).map(f=>JSON.parse(fs.readFileSync(f)));
     console.log(JSON.stringify({date:"${today}",run:process.env.STAMP,sites},null,2))' $files \
     > "memory/seo-audit/${STAMP}.json"
   

   Redirect the script's own JSON; never retype it. A hand-copied 20-page report is where transcription errors and invented numbers come from — and it is the file the next diff trusts.

   Snapshots accumulate one per run (older date-named files stay valid — they still sort before any timestamped one). This skill is read-only and has no rm, so it cannot prune them itself; if the directory ever grows unwieldy, clear out old snapshots out-of-band (a write-mode maintenance step or a manual sweep). The newest file is all the diff ever needs.

6. Update the remediation doc, memory/seo-audit/FIXES.md. This is the durable half of the skill: the notification is a daily nudge that scrolls away, this is the standing work list someone can open and act on. Rewrite it in full each run (shell redirection — no Write tool), preserving history from the previous copy.

   Structure, highest-impact first (site names below are placeholders — use the real hosts from ${var}):

   ---
   title: "SEO Fixes"
   description: "Standing list of open SEO fixes, refreshed by seo-audit each run."
   ---
   
   # SEO fixes
   _Updated ${today} · auditor v<n> · example.com 94 (18 pages)_
   
   ## example.com — open
   
   ### 1. /docs — meta description is 512 chars (impact: high)
   - **Page:** https://www.example.com/docs → `<head>`
   - **Now:** `"How the product works: ..."` (512 chars)
   - **Target:** 120–160 chars
   - **Fix:**
     ```html
     <meta name="description" content="…the drafted replacement…">
   

   • Why: Google truncates around 160; the rest is wasted and the snippet reads as cut off.
   • First seen: 2026-07-21 · Open for: 3 runs

   2. site-wide — 18 pages have an image with no alt text (impact: medium)

   • Pages: all 18 (/, /docs, /blog/*, …) — one shared component
   • Fix: …

   example.com — recently fixed

   • 2026-07-24 — /blog: alt text added to all 4 images (was open 3 runs)

   
   Rules that keep it useful rather than decorative:
   - **One section per site**, sites ordered by how much work is open.
   - **Group by cause, not by page.** With 18 pages audited, the same warning on
     every one of them is *one* fix in a shared layout component, not 18
     entries — write it once, list the affected pages, and say where the shared
     markup lives if you can tell. Per-page entries are for per-page copy
     (a specific title, a specific meta description).
   - **Draft the actual replacement text**, don't describe it. A title or meta
     description the operator can paste is worth ten "consider shortening".
     Write it in the site's voice and state its character count. For a
     grouped finding, draft the one-line component change instead.
   - **Carry `First seen` and `Open for` forward** from the previous copy. Aging
     is the signal — a finding open for 20 runs is either important or should be
     consciously dropped.
   - **Write clean UTF-8; never carry mojibake forward.** If the previous copy
     shows `·` where a `·` belongs, or `â`/`â€"` where a `—`/`→` belongs, that is
     corruption from an earlier run — **fix it, don't reproduce it.** When in
     doubt, use plain ASCII separators (` - `, ` | `) rather than a middot. The
     file is rewritten in full each run, so one clean rewrite ends the cycle.
   - **Move resolved items to `Recently fixed` with the date**, and keep the last
     ~10. Delete older ones; this is a work list, not an archive.
   - **Only genuine, actionable findings.** Same bar as the diff: if a human
     can't act on it, it doesn't belong here.
   - If everything is clear, say so in one line and keep the `Recently fixed`
     section. Don't invent work.
   
   

7. Notify — every day, even when nothing changed (as long as a target was set). This skill is deliberately not silent-on-no-signal; the daily score line is the point. Keep the unchanged case to a few lines and expand only when something moved:

   SEO — example.com 94 (18 pages) · blog.example.com 92 (11 pages)
   
   Regressed
   · example.com /docs — meta description removed (was 148 chars, now absent)
     <meta name="description" content="How the product works: architecture,
     the self-healing loop, persistent memory.">  (118 chars)
   
   Weakest pages
   · example.com /pricing 84 · /contact 88 — both short on body copy
   
   Top open fix
   · example.com /docs title 63 chars → trim to ≤60:
     "Docs: Skills, Memory, Self-Healing, Chains"  (42 chars)
   
   11 other open fixes · full list in [FIXES.md](…)
   

   With two sites and ~30 pages the score line is the headline, not a list of pages: one line per site, then only what moved. Name the site on every page reference (example.com /docs) — a bare /docs is ambiguous once more than one site is audited. Include the "weakest pages" line only when a page sits clearly below its site's average.

   Send it with ./notify -f <file>.md (multi-line always goes through -f).

   Write that body under /tmp/, never memory/ or output/. Those two are preserved by the read-only guard and committed by the post-run step, so a scratch notify body written there ships as junk on main, not a cosmetic slip. This skill has no rm, so it cannot clean up after itself; the fix is to never write it there:

   cat > /tmp/seo-notify.md <<'NOTIFY'
   <the digest markdown>
   NOTIFY
   ./notify -f /tmp/seo-notify.md
   

   The only files this skill is meant to persist are the Step 5 snapshot (memory/seo-audit/<STAMP>.json) and the Step 6 memory/seo-audit/FIXES.md.

   Any file you point at must be a clickable link, never a bare path. Telegram delivery runs parse_mode=HTML and scripts/notify_format.py converts [text](url) into <a href="url">text</a> — but a bare memory/seo-audit/FIXES.md passes through as dead plain text that nobody can open from their phone. Build the URL from the run's own environment so it stays correct in any fork:

   FIXES_URL="${GITHUB_SERVER_URL:-https://github.com}/${GITHUB_REPOSITORY}/blob/main/memory/seo-audit/FIXES.md"
   

   then write the pointer as [FIXES.md]($FIXES_URL). Same rule for the audited pages — [docs](https://www.example.com/docs) rather than a naked path.

   Detail rules — the difference between a message that gets acted on and one that gets skimmed:

   • Show the current value and the replacement, both with character counts. Never write "consider shortening" when you can write the shorter string.
   • One concrete fix in the message, the highest-impact open item. The rest lives in FIXES.md; the notification points there with a count. A wall of five findings every morning gets muted.
   • Name the page and the element, not just the check (docs → <head> meta description, not meta_description).
   • Say what the reader loses, in plain terms — "Google cuts the snippet at ~160 chars" beats "suboptimal length".
   • references/checklist.md has the target and a copy-paste pattern for every check.

8. Log it. End your final output with the log record (the guard writes it to memory/logs/${today}.md under ### seo-audit; don't append it yourself): the per-URL scores, what regressed, what was fixed, and any URL that failed to fetch. If ${var} was empty, log a single SEO_NO_TARGET line and nothing else.

Prioritizing what to report

Order fixes by impact, not by the order they appear in the findings:

• Fix first (fail): a page that failed to fetch, a page set to noindex that should rank (the indexable check — a page in the sitemap that is also noindex is a self-contradiction and a silent, total loss of that page), missing title, missing meta description, no H1, no viewport, not HTTPS, broken links, failing Core Web Vitals.
• Then (warn): duplicate titles or descriptions, canonicals pointing elsewhere, sitemap URLs that noindex/redirect (sitemap_health), pages linked but missing from the sitemap, mixed (http) content on an https page, images missing width/height, incomplete Article schema, length tuning, multiple H1s, missing alt text, no canonical, thin content, incomplete Open Graph.
• Nice to have (info): legacy image formats (WebP/AVIF), structured-data opportunities, social cards.

A cross-page finding usually outranks a single page's warning: one duplicate title costs two pages at once, and a canonical pointing away can remove a page from search entirely. Likewise weight by reach — the same warning on 18 of 18 pages is a bigger deal than a worse warning on one blog post.

Cap the notification at the top 5 items. Everything else lives in the JSON and the log — a daily message nobody finishes reading is a muted message.

Interpreting the score

The score is a rough health signal (pass = full credit, warn = half, fail = none; info is not scored), impact-weighted — a missing <title>, a noindex, or no HTTPS costs far more than a missing twitter:card (weights live in WEIGHTS in the auditor). It is not a Google ranking. Treat it as a before/after yardstick, not a promise about SERP position. Never claim a change guarantees higher rankings — outcomes depend on competition, content quality, and off-page factors this skill doesn't measure.

Limits

• One site per script run. The workflow above loops over ${var}.
• Discovery is only as good as the sitemap. A page absent from sitemap.xml and unlinked from the pages that are in it will not be audited. The sitemap_coverage finding catches the linked-but-unlisted case; nothing catches a page that is both unlisted and unlinked.
• --max truncates the tail. The cap keeps the homepage and shallow pages and drops the deepest paths (usually dated posts). When discovery.truncated is true, say so — a score over 50 of 200 pages is not the site's score.
• sitemap_coverage is skipped entirely on a truncated or crawl-discovered run; it would otherwise report the skill's own cap as missing pages.
• Sees the initial HTML response, not JavaScript-rendered content — the scanner reads raw markup. For heavy SPAs, findings reflect the pre-hydration DOM and Google may render more; flag server-side rendering or prerendering if key content is missing from the raw HTML. Worth stating the first time a target looks SPA-shaped, then not repeating it daily.
• On-page and technical only. No keyword research, rank tracking, or backlinks.
• Never edit the audited site. This skill reports; a human decides what ships.