suede-seo-audit

Files (7)

• CARD.md
• SKILL.md
• openai.yaml · agents/
• google-search-guidance.md · references/
• keyword-research.md · references/
• lane-checklists.md · references/
• schema-templates.md · references/

SKILL.md (first lines)

# Suede AI SEO Audit Skills

## Compatibility

Live audits need web/browser access; supplied-source audits remain available offline. Bundled dependency-free source-review CLI requires Node.js 22 or later.

For a concrete input, expected handoff, and failure check, read
[the worked handoff](references/worked-handoff.md).

A deep, scored audit of how search engines and answer engines reach,
understand, and present a page. Every finding cites what was fetched, every
fix is written out literally, and every fix names the KPI it should move.

## Gate policy: advisory, not blocking

Every check, grade, and ship gate here is a recommendation to the user, not a
control on the agent. A failed gate changes what you report, never what you
do. Single exception: an extremely risky finding (data loss, credential
exposure, legal or rights violations, payment mistakes, irreversible public
damage) pauses for the user's choice.

## Where this audit stops

| Question | Owner |
|---|---|
| Is this page technically sound, well-structured, eligible, and trustworthy? Graded, with fixes. | **this skill** |
| Is this page ready to promote today? One fast A-F read including design and CTA. | `suede-visibility-grader` |
| Do ChatGPT, Perplexity, Claude, Copilot and AI Overviews cite and recommend us, and how do we measure it? | `suede-ai-seo` |
| The page is found but does not convert. | `suede-site-alchemy` |
| Hundreds of templated pages. | `suede-programmatic-seo` |

Lane 6 applies the extractability standard that `suede-ai-seo` owns. Cite it;
do not redefine it here.

## Offline source tools (Node 22+)

This folder includes a standalone CLI and self-contained modules. No install,
API key, network request, Search Console connection, or provider call is needed.
Run from this skill folder; output goes into a **new** directory:

```bash
node scripts/seo-review.mjs audit --input scripts/fixtures/pages.json --out reports/baseline
node scripts/seo-review.mjs audit --input scripts/fixtures/pages.json --merchant --out reports/merchant
node scripts/seo-review.mjs drift --before reports/baseline/metadata-snapshot.json --after reports/merchant/metadata-snapshot.json --out reports/drift
node scripts/seo-review.mjs serp-clusters --input scripts/fixtures/serp.json --context "Synthetic fixture only" --depth 2 --threshold 0.5 --out reports/clusters
node --test scripts/tests/*.test.mjs
```

- Lane 1: validate HTML hreflang codes, self annotations, duplicate/conflicting
  destinations, inspected reciprocal links, canonical and HTML noindex conflicts.
  Uncollected alternates stay **unmeasured**, never broken by assumption.
- Lane 3: audit img source fallbacks, missing/empty alt, intrinsic dimensions,
  width-based srcset/sizes, and lazy/high-priority conflicts. Empty alt needs human
  decorative-purpose review; asset bytes, rendering and CWV remain unmeasured.
- Lane 3: every audit saves a new metadata snapshot. Drift compares fields and
  exact URL identities. Supplied inventories are partial: omitted URLs are
  **not-observed**, never proof of deletion or a live 404.
- Lane 5: `--merchant` explicitly enables a Product/Offer merchant profile,
  including local graph references, active prices/currency, availability,
  supplied identifiers and variant relationships. Never invent prices, ratings,
  shipping or return policies. This is source review, not eligibility certification.
- Lane 0/9: cluster supplied organic-result exports by same-depth document URL
  overlap. Require collection context; deterministic complete-link grouping avoids
  transitive chains. Demand and current rankings stay unknown.

Read [offline input formats and limits](references/offline-tools.md) before
supplying your own evidence. These tools add findings to the existing lanes;
they do not replace live verification or change the audit's routing boundaries.

## Current rules

Before applying any Google-specific rule, read
`references/google-search-guidance.md` (verified 2026-10-23). It records what
changed recently and must be re-checked before a ship decision: FAQ rich
results ended in May 2026, several structured data features were retired in
2025, AI Overviews and AI Mode have no extra technical requirements, and
Search Console now has a Search Generative AI performance report.

## 1. Source truth

Never audit from memory. Before any finding, fetch and record exactly:

- HTTP status, every redirect hop, final URL
- `robots.txt` rules for `*`, `Googlebot`, and `Bingbot` (other named crawlers
  only when asked; AI crawler policy belongs to `suede-ai-seo`)
- `<meta name="robots">`, `X-Robots-Tag`, snippet directives
- `<link rel="canonical">` and whether it is self-referencing
- Sitemap presence and whether the URL is listed
- `<title>`, meta description (text and length as a preview diagnostic)
- Open Graph and Twitter/X card tags
- Every JSON-LD block, parsed
- Primary H1 and heading outline
- Raw HTML vs rendered DOM for primary content

If the URL is inaccessible, audit source files and mark live checks
unverified. If content is behind auth or a paywall, say so and limit scope.

## 2. Audit lanes

Run every lane. Mark each checklist item pass, fail, or N/A with location.
Checklists live in `references/`:

| Lane | Checklist |
|---|---|
| 0 Keyword research (optional) | `references/keyword-research.md` |
| 1-4, 6-9 | `references/lane-checklists.md` |
| 5 Schema | `references/schema-templates.md` |

### Lane 0: Keyword research (optional)

Run only when discovery is requested. Produces a keyword and content brief,
not a grade. Numeric demand stays `unknown` unless a dated source supplies it.

### Lane 1: Technical access

Can Google and Bing crawl, render, and index the page? Status, redirects,
canonical, robots, sitemap, rendering, Bing Webmaster Tools and IndexNow
setup, and the Core Web Vitals protocol (LCP 2.5 s, INP 200 ms, CLS 0.1 at
the 75th percentile). Measure CWV with PageSpeed Insights or CrUX field data

From JasonColapietro/suede-creator-skills, MIT.

More from JasonColapietro/suede-creator-skills