agentleFS
mkreindelmkreindel/seo-toolkit-template/.claude/skills/audit/SKILL.md

audit

Skill1 starsChanged 6 months agoApache-2.0View on GitHub

Run a technical SEO audit on a chosen managed site — verifies all 8 non-negotiables, runs Lighthouse mobile, checks Core Web Vitals from GSC field data, validates schema on representative pages, audits foundational infrastructure (GSC, GBP, GA4, GTM, BWT). Logs results to `sites/[name]/site-info.md` under "Technical SEO baseline." Use when the user types `/audit` or after any major site change.

193 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use delight, teach-impeccable and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • HK-hubSkill

    delight

    Add moments of joy, personality, and unexpected touches that make interfaces memorable and enjoyable to use. Elevates functional to delightful. Use when the user asks to add polish, personality, animations, micro-interactions, delight, or make an interface feel fun or memorable.

    Also in 32 projects that use this

  • HK-hubSkill

    teach-impeccable

    One-time setup that gathers design context for your project and saves it to your AI config file. Run once to establish persistent design guidelines.

    Also in 19 projects that use this

  • zwy123zwySkill

    normalize

    将用户随意输入的提示词规范化为结构清晰、便于大模型执行的标准化提示词。适用于需要整理、统一提示词格式时调用。

    Also in 19 projects that use this

  • SkillPilotCHSkill

    level-up

    Eine Automatisierung pro Woche finden, scopen, shippen. Output landet als proposed-Eintrag in cadence.md mit konkreten Implementations-Schritten.

    Also in 12 projects that use this

  • ww-w-aiSkill

    pm-discovery

    PM Agent Team - Automated product discovery, strategy, and PRD generation. Runs PM analysis workflow to produce comprehensive PRD before PDCA Plan phase.

    Also in 3 projects that use this

  • +7 more from HK-hub

The file

Show its rules and text

We split this skill into the rules it gives an agent

17 rules. 0 are common, 3 are distinctive, and 14 are very specific to this project.

  • 0

    Common

    Most of the 174 edited versions we read keep these.

  • 3

    Distinctive

    This author's own choices. Worth a look.

  • 14

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If the invocation contains --cron, this skill runs in cron mode (no user available).

    line 22
  2. Very specific:

    Defaults: when a choice would normally be asked, default to site-info.md / goals.md values.

    line 28
  3. Very specific:

    Audit log: ALWAYS write one line to the audit log on exit — success (shipped), escalation (escalated), idempotent skip (idempotent-skip), …

    line 30
  4. Very specific:

    If quick scope: skip. If full or deep: run via node scripts/lighthouse.mjs --url=[homepage] and --url=[inner page].

    line 57
  5. Very specific:

    If full or deep: run via node scripts/lighthouse.mjs --url=[homepage] and --url=[inner page].

    line 58
  6. Distinctive:

    If GSC API access is configured: pull last 28 days of Core Web Vitals field data → status (Good / Needs improvement / Poor) for mobile + …

    line 68
  7. Distinctive:

    If not configured: prompt user to manually copy the GSC Core Web Vitals dashboard summary.

    line 70
  8. Very specific:

    Run node scripts/validate-schema.mjs --url=[page] on representative pages (homepage + 1 blog + 1 service if applicable):

    line 74
  9. Distinctive:

    Verify each (where verifiable from outside):

    line 82
  10. Very specific:

    Read site-info.md Languages section.

    line 92
  11. Very specific:

    Run node scripts/validate-hreflang.mjs --site=[name].

    line 96
  12. Very specific:

    Run the manual checks from on-page-seo.md Section 17 on representative pages:

    line 129
  13. Very specific:

    Verify the 7 internal-linking patterns from SEO_GUIDE.md Section 5.1 on the right page types.

    line 139
  14. Very specific:

    If full or deep: search the site's top 3 keywords (from site-info.md "Primary money keywords" + keywords.csv top 3) on:

    line 153
  15. Very specific:

    If deep: run on-page-seo.md checklist against top 5 pages (highest GSC clicks).

    line 162
  16. Very specific:

    If deep + Ahrefs/SEMrush API configured: pull

    line 168
  17. Very specific:

    Update sites/[site]/site-info.md under "Technical SEO baseline":

    line 177

“Common” is measured: kept by at least 6 in 10 of the 174 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

/audit — Technical SEO auditor

Walks a single site against the toolkit's technical SEO standards and writes the result.

Inputs

Required:

  • Site — must match a folder under sites/[name]/.

Optional:

  • Audit depth — quick (8 non-negotiables only), full (default — non-negotiables + Lighthouse + schema + infrastructure + AI search visibility), deep (full + competitor comparison + backlink baseline + on-page audit of top 5 pages).

Workflow

Step 0 — Cron-mode detection (if invoked with --cron)

If the invocation contains --cron, this skill runs in cron mode (no user available). Required behavior:

  1. Idempotency check: see this skill's "Routine versioning + idempotency contract" section. If today's output already exists, exit cleanly with exit: "idempotent-skip". Write one line to the audit log via scripts/lib/audit-log.mjs appendRun({ exit: "idempotent-skip", ... }).
  2. Escalation contract: any decision that would normally prompt the user (missing required file, voice anti-AI failure, schema validation failure, keyword cannibalization, etc.) MUST be escalated by writing an item to sites/{site}/_inbox/ via scripts/lib/cron-mode.mjs writeInboxItem(...). After writing, exit cleanly with exit: "escalated". Do NOT use AskUserQuestion in cron mode.
  3. Defaults: when a choice would normally be asked, default to site-info.md / goals.md values. If both are silent on the required choice, escalate per (2).
  4. Audit log: ALWAYS write one line to the audit log on exit — success (shipped), escalation (escalated), idempotent skip (idempotent-skip), or failure (failed).
  5. Backoff: at the start of every cron-mode run, call checkBackoff({ routine }) from scripts/lib/audit-log.mjs. If true, the routine has hit the 3-strike threshold — write _inbox/routine-disabled-{name}.md, run scripts/sync-schedules.mjs --pause-routine={name}, and exit.

Step 1 — Read context (Rule 1)

Same as /blog Step 1, but also fetches the site's homepage HTML and at least one inner page (top blog post + top service page if available).

Step 2 — Audit the 8 non-negotiables (Section 4 of CLAUDE.md)

For each:

#ElementHow
1SitemapHTTP GET [site]/sitemap.xml; parse XML; count URLs
2robots.txtHTTP GET [site]/robots.txt; verify allows crawlers + references sitemap
3CanonicalView source on homepage + 1 inner page; verify <link rel="canonical"> present
4OG imagesView source; verify og:image exists + URL resolves; check 1200×630 dimensions
5Image dimensionsView source on a sample page; verify <img> has width/height
6Semantic HTML5View source on homepage + 1 inner; verify <header>, <nav>, <main>, <footer> present
7Mobile viewportView source; verify <meta name="viewport"...> present
8HTTPSVerify URL scheme + check for mixed content via Lighthouse

Pass / Fail / Warning per item.

Step 3 — Lighthouse audit (mobile)

If quick scope: skip. If full or deep: run via node scripts/lighthouse.mjs --url=[homepage] and --url=[inner page]. Capture: Performance, SEO, Accessibility, Best Practices + Core Web Vitals (LCP, INP, CLS).

Compare against:

  • Floor (per Section 6.2 of SEO_GUIDE.md)
  • Stretch goal (100 across all)

Flag any score below floor.

Step 4 — GSC field data (Core Web Vitals)

If GSC API access is configured: pull last 28 days of Core Web Vitals field data → status (Good / Needs improvement / Poor) for mobile + desktop.

If not configured: prompt user to manually copy the GSC Core Web Vitals dashboard summary.

Step 5 — Schema validation

Run node scripts/validate-schema.mjs --url=[page] on representative pages (homepage + 1 blog + 1 service if applicable):

  • Schema.org Validator
  • Print Rich Results Test deep-link for manual verification

Capture: which schemas are detected, validation status (pass / errors), missing recommended schemas (e.g., LocalBusiness on a local site without it).

Step 6 — Foundational infrastructure (Section 9 of SEO_GUIDE.md)

Verify each (where verifiable from outside):

  • GSC verified (per site-info.md flag)
  • Sitemap submitted to GSC (per flag + sitemap URL responding)
  • GBP claimed (manual check on Google Maps if local)
  • GA4 installed (view-source for gtag.js or GTM container)
  • GTM installed (view-source)
  • BWT verified (per site-info.md flag)

Step 6.5 — Hreflang audit (multilingual sites only)

Read site-info.md Languages section.

  • Multilingual: false → skip; not applicable.
  • Multilingual: true:
    1. Run node scripts/validate-hreflang.mjs --site=[name]. The script walks every URL in the sitemap and checks:
      • Each declared-language counterpart exists (HTTP 200 at the per-language URL pattern from site-info.md).
      • Each page's <link rel="alternate"> cluster: self-reference present, all sibling languages present, x-default present.
      • Reciprocal: every alternate link is mirrored on the target page (EN → ES requires ES → EN).
      • <html lang> matches the served language (the language code in the URL pattern).
      • Schema inLanguage matches <html lang>.
    2. Optional: verify sitemap declares xhtml:link alternates per Google's spec.
    3. Output structured report: total URLs visited, errors (with URL + missing piece), warnings, reciprocal-check pass/fail counts.
    4. Failures are blockers, not opportunities. A multilingual site with broken hreflang is treated as worse-than-monolingual by Google. Block the audit's "passing baseline" status until reciprocal hreflang holds across the site.

Failures recorded under Technical SEO baseline → Hreflang state in site-info.md. Coverage gaps (a page exists in EN but not ES) recorded as Phase-2 backfill items.

Step 6.6 — Bot-readability check (rendering audit)

For sites with rendering: csr or rendering: hybrid in site-info.md, OR any site we haven't verified before, run the bot-UA curl test on the homepage + 1 inner page:

curl -s -A "Mozilla/5.0 (compatible; PerplexityBot/1.0; +https://perplexity.ai/perplexitybot)" \
  https://[domain]/[path] | grep -oE "<h[1-3][ >][^<]+</h[1-3]>" | wc -l

Expected: ≥ 5 H1–H3 elements on a content page; ≥ 1 H1 on every page that should rank.

Repeat for representative bots:

  • PerplexityBot (AI search)
  • GPTBot (OpenAI)
  • ClaudeBot (Anthropic)
  • Googlebot (sanity check; should always pass since Googlebot executes JS)

Compare to the page's view in browser. If the browser shows H1 + content but curl shows 0, the page is invisible to AI search bots — flag as Critical in the priority fix list. Reference: SEO_GUIDE.md Section 1.3 (rendering modes) + Section 3.6 (Google vs LLMs).

Step 6.7 — Manual audit fundamentals (cross-check)

Run the manual checks from on-page-seo.md Section 17 on representative pages:

  1. site: operator on Google — site:[domain] shows indexed pages. Compare count vs sitemap; spot accidentally-indexed staging URLs, parameter URLs, soft-404s.
  2. View source / Ctrl+U on homepage + 1 inner — verify <title>, canonical, OG, hreflang, JSON-LD all present in raw HTML.
  3. Chrome extension SEO META in 1 CLICK (manual; recommend to user) — quick H1/H2/meta sanity check on representative pages.

Discrepancies between automated checks (Steps 2–5) and manual checks (this step) get flagged for human review.

Step 6.8 — Internal linking pattern audit

Verify the 7 internal-linking patterns from SEO_GUIDE.md Section 5.1 on the right page types. Sample 5 routes spanning home + category + subcategory + leaf + blog:

Page typePatterns expected
Home1 (header dropdown), 2 (featured), 3 (footer)
Category landing1, 3, 4 (breadcrumb), 5 (category→sub)
Subcategory1, 3, 4, 5, 6 (related-products)
Product / service leaf1, 3, 4, 6
Blog post1, 3, 4, 7 (blog→transactional bridge)

For each sampled page, report which expected patterns are present and which are missing. Patterns are mostly template-level, so a single missing pattern usually indicates a site-wide template fix.

Step 7 — AI search visibility (Section 9.7)

If full or deep: search the site's top 3 keywords (from site-info.md "Primary money keywords" + keywords.csv top 3) on:

  • Perplexity (via web)
  • Google AI Overviews (via google.com search)
  • Note ChatGPT and Claude as manual-check items

Note whether the site is cited.

Step 8 — On-page audit of top 5 pages (deep scope only)

If deep: run on-page-seo.md checklist against top 5 pages (highest GSC clicks).

Score each page on Tier 1 (16 items) + extended checklist applicable items.

Step 9 — Backlink baseline (deep scope only)

If deep + Ahrefs/SEMrush API configured: pull

  • Total referring domains
  • DR / DA
  • Top 10 anchor texts
  • New / lost links last 28 days
  • Toxic-link flags

Step 10 — Write results to site-info.md

Update sites/[site]/site-info.md under "Technical SEO baseline":

## Technical SEO baseline (audit date: YYYY-MM-DD, depth: [quick/full/deep])

### 8 non-negotiables
- [✅/❌] Sitemap exists at /sitemap.xml — [URL count: N]
- [✅/❌] robots.txt exists, allows crawlers, references sitemap
- [✅/❌] Canonical URLs present on homepage + inner page
- [✅/❌] OG images present and resolve (1200×630)
- [✅/❌] Image dimensions specified
- [✅/❌] Semantic HTML5 used
- [✅/❌] Mobile viewport meta present
- [✅/❌] HTTPS everywhere

### Lighthouse mobile (homepage)
- Performance: [N] (floor: 70, stretch: 100)
- SEO: [N] (floor: 95, stretch: 100)
- Accessibility: [N] (floor: 90, stretch: 100)
- Best Practices: [N] (floor: 95, stretch: 100)
- LCP: [Xs] | INP: [Xms] | CLS: [X]

### Schema (representative pages)
- Detected: [list]
- Validates: [list with errors flagged]
- Missing recommended: [list]

### Foundational infrastructure
- [✅/❌] GSC verified
- [✅/❌] Sitemap submitted
- [✅/❌ or N/A] GBP claimed
- [✅/❌] GA4 installed
- [✅/❌] GTM installed
- [✅/❌] BWT verified

### Hreflang state (multilingual sites only)
- Site is multilingual: ✅/❌ (per `site-info.md` Languages → Multilingual)
- Declared languages: [en, es, ...]
- Total URLs in sitemap: [N]
- Per-language counterpart coverage: [N/N]
- Self-reference present on every page: ✅/❌
- All sibling languages linked on every page: ✅/❌
- `x-default` present on every page: ✅/❌
- Reciprocal hreflang (EN→ES requires ES→EN): [pass/fail count]
- `<html lang>` matches served language: ✅/❌
- Schema `inLanguage` matches `<html lang>`: ✅/❌
- Coverage gaps (pages missing in 1+ languages): [list with URLs + missing language codes]

### AI search visibility (this audit)
- Perplexity: cited ✅/❌ for [keyword]
- Google AI Overviews: ✅/❌ for [keyword]
- ChatGPT: [manual check needed]
- Claude: [manual check needed]

### Bot-readability (rendering audit, if CSR/hybrid)
- PerplexityBot H1 count on homepage: [N]
- PerplexityBot H1–H3 count on inner page: [N]
- GPTBot / ClaudeBot match: ✅/❌
- Browser view matches bot view: ✅/❌
- Verdict: ✅ pass / ❌ invisible to AI search → critical fix

### Internal linking pattern coverage
- Home: patterns 1, 2, 3 → [✅/❌] each
- Category landings: patterns 1, 3, 4, 5 → [✅/❌] each
- Subcategory landings: patterns 1, 3, 4, 5, 6 → [✅/❌] each
- Leaf pages: patterns 1, 3, 4, 6 → [✅/❌] each
- Blog posts: patterns 1, 3, 4, 7 → [✅/❌] each
- Missing patterns (likely template-level fix): [list]

Step 11 — Generate priority fix list

Sort all failures by leverage:

  • Critical — anything blocking indexation (no sitemap, blocked by robots, no canonicals).
  • High — Tier 1 misses, schema errors, Performance < floor, GSC not verified.
  • Medium — non-Tier-1 on-page misses, missing recommended schema, GBP not claimed (if local).
  • Low — opportunities (Lighthouse below 100 but above floor, AI search not citing yet).

Print prioritized fix list to user. Recommend /refresh for Tier 1 fixes on top pages.

Routine versioning + idempotency contract

This skill participates in cruise-control via --cron mode. When invoked by cron:

  1. Stamp routine_version in every output (the notes.md audit entry header, the tech-debt.md items it creates, the audit log line via scripts/lib/audit-log.mjs). Current routine_version: 1.0.
  2. Idempotency: this skill MUST be safe to run twice on the same day on the same site without producing duplicate work. Implementation: check whether notes.md already has today's audit entry for this site; if so, exit cleanly with exit: "idempotent-skip". Do NOT append a second audit entry on the same day.

Reference: docs/specs/2026-05-16-agents-cruise-control-design.md § Operational hardening O3.

Refusal conditions

  • Site folder doesn't exist or site-info.md missing.
  • Live site URL doesn't resolve (homepage 4xx/5xx).

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.