audit · adobe — Claude Code skill: site audit and installation
Audits a website for design, SEO, technical health and AI-search visibility, then turns the findings into a scored report.
Apache-2.0 301 installs ★ 335 updated 2026-11-14
npx skills add adobe/skills --skill audit -a claude-codeWhat audit does
This skill takes one URL and reviews an existing website from three angles: visual design, SEO and technical checks, plus visibility in LLM and AI search. It also measures Core Web Vitals and produces a seven-dimension scorecard with findings tied to measurements, check results or captured observations.
The crawl can cover multiple pages unless --single or --pages <n> changes its scope. --deploy publishes report.html, while --benchmark forces the reference-benchmarking phase. The project needs Node 22+, Playwright with Chromium resolvable, and playwright-cli on PATH; impeccable must be installed alongside stardust. Missing dependencies can reduce the run or prevent the report from rendering.
What it helps with
- audit a live site across design and UX
- spot SEO and technical issues
- measure visibility in AI search
- check Core Web Vitals
- rank findings in an evidence-bound report
Example prompts for the agent
- Run a full audit with
/stardust:audit <url>. - Audit one page only with
/stardust:audit <url> --single. - Set the crawl limit with
/stardust:audit <url> --pages <n>.
How to install audit
1Skills CLI (Vercel)
npx skills add adobe/skills --skill audit -a claude-code2Manually: put the files in place
~/.claude/skills/audit/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/audit/
1Skills CLI (Vercel)
npx skills add adobe/skills --skill audit -a codex2Manually: put the files in place
.agents/skills/audit/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add adobe/skills --skill audit -a cursor2Manually: put the files in place
.cursor/skills/audit/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install adobe/skills plugins/stardust/skills/audit2Manually: put the files in place
.github/skills/audit/SKILL.md1Skills CLI (Vercel)
npx skills add adobe/skills --skill audit -a gemini-cli2Platform CLI
gemini skills install https://github.com/adobe/skills --path plugins/stardust/skills/auditManually: put the files in place
.devin/skills/audit/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add adobe/skills --skill audit -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about audit
How do I install audit in Claude Code?
Run npx skills add adobe/skills --skill audit -a claude-code, then check ~/.claude/skills/audit/SKILL.md.
What does audit do?
It reviews design, SEO, technical health and LLM or AI-search visibility. The output includes Core Web Vitals, a seven-dimension scorecard and findings linked to collected evidence.
What does audit require to run?
You need Node 22+, Playwright with resolvable Chromium and playwright-cli on PATH. The impeccable skill must also be installed alongside stardust.
Source text
SKILL.md · Apache-2.0
---
name: audit
description: Full three-perspective audit of an existing website from one URL — design (tensions + concrete improvement opportunities), SEO/technical, and LLM/AI-search visibility — plus Core Web Vitals, synthesized into a scored, evidence-bound report. Use when the user asks to "audit this site", "site audit", "design audit", "SEO audit", "why is my site underperforming", "LLM visibility", "how does my site look to AI", or invokes `$stardust audit` (`/stardust:audit` in Claude Code) <url>.
license: Apache-2.0
compatibility: Requires Node 22+, Playwright with Chromium resolvable from the project, and the impeccable skill (github.com/pbakaus/impeccable) installed alongside stardust.
---
# stardust:audit
One URL in. One scored, evidence-bound audit out.
`audit` looks at an existing website from three perspectives — design
(brand tensions + concrete improvement opportunities), SEO/technical,
and LLM/AI-search visibility — measures Core Web Vitals, and
synthesizes everything into a seven-dimension scorecard plus a
prioritized findings ledger that tells the owner what to improve to
generate a better business outcome. The report is also the natural
seed for a redesign: its findings feed the stardust `uplift` skill's
improvements list and the stardust `direct` skill's Phase 2.5, and it closes
with uplift-shaped redesign directions so "run `$stardust uplift`" is
the obvious next step.
## Opinionated defaults
- **Multi-page by default** — `$stardust extract <url> --cap 8`
(home + seven IA pillars) unless `--single` or `--pages` overrides.
- **Non-interactive** — the audit never asks questions. Every
assumption it makes instead is recorded in
`audit.json#assumptions` and stated in the report's executive
summary.
- **Evidence-bound** — every claim cites a measurement, a `T-*`
tension id, a check result, or a screenshot observation. A claim
with no citation does not ship.
- **No fabricated data** — a measurement that could not be taken is
reported as `not measured (<reason>)`, never estimated silently.
An estimate, where reasoned, is labeled as one with its basis.
- **Graceful degradation, not failure** — optional capabilities
(refero, marketing-skills, modern-web-guidance, PageSpeed
Insights) are probed once and their absence is recorded, never
fatal. See § Degradation ladder.
## Inputs
- `<url>` — required. The site to audit. A path narrows the crawl to
that subtree (extract's semantics).
- `--pages <n>` — optional. Override the default 8-page extraction
cap (passed through as `--cap <n>`).
- `--single` — optional. One-page audit of the given URL only. The
cross-page checks (duplicate titles, sitemap coverage, CTA
fragmentation across pages) then run on a single page and say so.
- `--deploy` — optional. After the report renders, publish
`report.html` as a single self-contained page via the DA transport
(`../deploy/da-deploy-protocol.md`: source PUT → preview → live)
and print the delivered URL. Transport only — the report never
goes through deploy's section→block conversion, which would
decompose the self-contained file.
- `--benchmark` — optional. Force Phase 5 reference benchmarking:
probe the refero MCP even when the earlier capability probe was
slow or ambiguous. Without this flag Phase 5 fires only when the
probe succeeds quickly.
There are no other flags. Everything else is derived from the
captured surface or governed by the underlying skills' contracts.
## Phase 0 — Setup
1. Run the master skill's setup (`../stardust/SKILL.md` § Setup) —
with one audit-specific carve-out: **impeccable absence is a
degradation here, not the master setup's hard stop.** When the
dep check fails, record `impeccable: unavailable` in
`audit.json#degradations` and continue — Phase 2 runs without the
critique/audit arms (VISION pass + accessibility fold-in still
fire) and Phase 6 skips the report render; the run ends at stop
condition (b) *after* `audit.json` is written.
2. **Extraction freshness check.** If `stardust/current/` holds an
extraction of the **same origin** less than **7 days** old —
origin from `stardust/state.json` (the site record extract
stamped), recency from the newest
`pages/<slug>.json#_provenance.fetchedAt` — reuse it
and record `site.extraction.reused: true`. Otherwise invoke
`$stardust extract <url> --cap 8` (or `--single` / `--pages <n>`
per the inputs). Extract owns the crawl, the screenshots,
`_brand-extraction.json`, `pages/<slug>.json`, `PRODUCT.md` /
`DESIGN.md`, and `brand-review.html` with its Tensions section.
3. **Probe optional capabilities once**, recording each outcome in
the degradation record (`audit.json#degradations`):
- `marketing-skills` plugin (`seo-audit`, `ai-seo` skills present?)
- `modern-web-guidance` (`npx -y modern-web-guidance@latest search
"<query>"` responds?)
- refero MCP (attempt `mcp__refero__refero_search_styles`; treat a
tool-not-found or timeout as unavailable)
- PageSpeed Insights API (network-reachable without a key?)
- rollout project (`stardust/rollout/rollout.json` present?)
If extract fails entirely (site unreachable, bot-management block
past the headed-Chrome fallback), stop and surface extract's error
verbatim — there is nothing to audit. This is the only hard stop
before synthesis; see § Stop conditions.
## Procedure
### Phase 1 — Brand surface & tension analysis
Read `stardust/current/_brand-extraction.json` and
`stardust/current/brand-review.html` § Tensions surfaced (rule
catalog in `../extract/reference/brand-review-template.md`
§ Tensions). Every fired `T-*` tension is candidate evidence for a
finding — carry the ids forward, do not re-derive the detections.
Compute the four brand-expression measurements the report needs.
Each lands in `audit.json#measurements` with `status` + `method` per
`reference/report-format.md`:
- **`brandColorShare`** — brand-color share of painted pixels on the
captured home screenshot. Preferred method: Playwright pixel
sampling (`method: "pixel-sample"`) — load the screenshot, sample a
grid (e.g. every 8th pixel), classify each sample to the nearest
palette entry within a tolerance, and divide brand-hue samples by
painted (non-white/near-white) samples. When sampling is infeasible
in the session, a reasoned estimate from the captured surfaces is
allowed but must ship as `method: "surface-estimate"` with its
basis — never presented as measured.
- **`ctaFragmentation`** — distinct CTA labels per equivalence bucket,
aggregated from `pages/*.json#ctas[].label` (the same buckets that
drive `T-cta-vocab`).
- **`typeScale`** — distinct heading sizes and scale kind/ratio from
`_brand-extraction.json#type.scaleAudit`.
- **`radiusSprawl`** — distinct border-radius values with occurrence
counts from `_brand-extraction.json#motifs.borderRadius`.
### Phase 2 — Design & experience critique
Three passes over the captured home page (screenshot + live URL),
folded into one set of design findings:
1. **impeccable critique + audit.** Invoke impeccable through the
harness's skill-invocation tool using the delegation mechanic in
`../prototype/SKILL.md` § Invoking impeccable (Claude Code form:
`Skill { skill: "impeccable:impeccable", args:
"critique <target>" }`, then `"audit <target>"` for the
accessibility / responsive / performance passes). Normalize its
findings into the audit's finding shape.
2. **VISION pass.** Study the captured screenshots directly
(`stardust/current/assets/screenshots/<slug>.png`) and name what a
design director would: dated patterns the field has moved past,
hierarchy failures, missed opportunities the captured surface
doesn't capitalize on. The claim discipline is absolute — every
observation cites a measurement, a tension id, or a screenshot
region ("`home.png`, hero: three equal-weight CTAs compete").
Adjectives without evidence do not become findings.
3. **Accessibility fold-in.** Contrast computed (WCAG ratios for the
captured palette pairs in the roles they are actually used in),
alt coverage from `pages/*.json#media.images`, landmark presence
and heading order from `pages/*.json#landmarks`, content-free link
labels (reuse `T-link-content-free` when fired).
### Phase 3 — SEO & technical
When the `marketing-skills` plugin is installed, follow
`marketing-skills:seo-audit`'s methodology and normalize its
issue/impact/evidence/fix items into findings. When absent, run the
checks directly — they are all curl/Playwright-derivable:
| area | checks | method |
|---|---|---|
| Crawlability | `robots.txt` present and sane; sitemap declared and valid XML | curl |
| Indexation | canonical present and self-referential; `meta robots` not accidentally `noindex`; http→https single-hop redirect; redirect chains | curl -I |
| Semantics | `main`/`nav`/`footer` landmarks; single `<h1>`; heading hierarchy without skips | pages/*.json + Playwright |
| Metadata | title/description presence + quality per page; duplicates across pages; Open Graph completeness | pages/*.json#metadata |
| Structured data | JSON-LD presence, parse validity, entity types vs page type | Playwright / curl |
Where a failure matches a `rollout:baseline` check id
(`../rollout/reference/checks.md`: `single-h1`, `title-missing`,
`meta-description`, `canonical`, `sitemap`, `jsonld`, `img-alt`,
`landmark-main`, `duplicate-title`), **reuse that id** as the
finding's `evidence.ref` (`check:<id>`) — findings recorded into a
rollout ledger under a known id get picked up by the AEM autofix
registry automatically.
**Core Web Vitals.** Measure LCP / CLS / TBT via Playwright
performance APIs (`PerformanceObserver` for
`largest-contentful-paint` and `layout-shift`, `longtask` entries for
TBT) on two viewports: mobile (375×667, CPU throttled where the
session supports it) and desktop (1440×900). When the PageSpeed
Insights API is network-reachable without a key, prefer it and record
`method: "psi-api"` (it adds field INP); otherwise record
`method: "playwright-lab"` and say in the measurement note that lab
TBT is a proxy for INP. Classify every metric against the Google
thresholds tabled in `reference/scoring.md` § performance.
**Remediation guidance.** When `modern-web-guidance` is installed,
run `npx -y modern-web-guidance@latest search "<specific failure>"`
for each distinct failure class and cite the returned guide ids in
the finding's `guides[]`. When absent, write the generic remediation
and leave `guides: []`.
### Phase 4 — LLM visibility
When `marketing-skills:ai-seo` is installed, follow its methodology.
When absent, assess directly:
- **`llms.txt`** — present at the origin root?
- **Answerability** — does each audited page answer the question a
user would ask of it ("what does this cost", "what is this") in
extractable, well-structured prose — and how early on the page?
- **schema.org coverage** — do the JSON-LD entities cover the
organization plus the page-type entities an answer engine needs
for entity understanding?
- **Heading-as-question coverage** — what share of `h2`/`h3` map to
askable questions or scannable topics rather than slogans?
- **Content depth** — extractable prose word counts on key pages;
specific, citable claims vs thin marketing copy.
- **Key facts in crawlable text** — are pricing, what-it-is, and
who-it's-for stated in crawlable text, or locked in images and
JS-rendered widgets?
- **Citation readability, measured** — run
`skills/deploy/scripts/ai-readability.mjs --origin <site> <sampled paths>` and report the
strict score per page with the top blocks adding rendered-only words; it is the exact
formula of Adobe's AI Content Visibility Checker (`deploy/reference/ai-readability.md`).
Every Phase 4 finding names the concrete fix ("state the three price
points in the pricing table as text; they currently render only
inside the plan-card images"), not a category ("improve content").
### Phase 5 — Reference benchmarking (optional)
Fires when the refero MCP tools are reachable — the Phase 0 probe
attempted `mcp__refero__refero_search_styles`; `--benchmark` forces a
re-probe. Skip gracefully when unavailable
(`benchmarks: { status: "skipped", reason: … }`).
When available: retrieve 2–3 same-vertical reference styles, compare
the audited site's brand expression (Phase 1 measurements) against
what best-in-class in the category does, and cite each reference —
title, URL, one line on what they do better — in the relevant design
findings and in `audit.json#benchmarks.references`.
### Phase 6 — Synthesis & report
1. **Scorecard.** Score the seven dimensions per
`reference/scoring.md` — anchors first, evidence floor enforced,
not-measured dimensions nulled and renormalized. Compute the
weighted overall.
2. **Findings.** Consolidate Phases 1–5 into the prioritized ledger:
P1 (actively losing business or excluding users) / P2 (material
drag) / P3 (polish). Per finding: `dimension`, `evidence`
(measurement / tension / screenshot / check / benchmark citation),
`businessImpact` one-liner, concrete `fix`, `guides[]`.
3. **Uplift directions.** Close with 2–3 redesign directions framed
exactly like uplift's variant role contract
(`../uplift/SKILL.md` § The three-variant role contract):
**A** faithful + fixes (names the findings it resolves), **B** one
captured-but-underused trait amplified, **C** cinematic (motion as
identity, register suggested per
`../prototype/reference/motion-registers.md` § Selection
heuristic). Drop B when the captured surface can't support a
differentiated middle — two strong directions beat three weak
ones.
4. **Write `stardust/audit/<domain-slug>/audit.json`** — schema,
slug convention, and measurement rules in
`reference/report-format.md` Part 1. Provenance `_provenance`
first key.
5. **Render `stardust/audit/<domain-slug>/report.html`** by
delegating to `$impeccable craft` with the brief in
`reference/report-format.md` Part 2 — the same skill-invocation
mechanic as prototype, and the same rule: **never hand-template
the report**. Run the post-render validation checklist; on
failure re-invoke craft with the specific violation. Open the
result with `open stardust/audit/<domain-slug>/report.html`.
6. **Ledger recording (rollout projects only).** When
`stardust/rollout/rollout.json` exists, record each finding into
the delivery ledger via
`node skills/rollout/scripts/findings.mjs record` with source
namespace `audit:` — `--source audit:<dimension>`, `--layer` from
the mapping below, severity carried through, `--fixability`
normalized per `../rollout/reference/audit-sources.md`
§ Recording an external finding. Write each returned id into the
finding's `ledgerId`.
| audit dimension | ledger layer |
|---|---|
| `brand-expression` | `brand-tensions` |
| `visual-hierarchy-craft` | `design-ux` |
| `conversion-focus` | `content-conversion` |
| `accessibility` | `accessibility` |
| `technical-seo` | `seo` (site-wide: `cross-page`) |
| `content-llm-visibility` | `ai-search` |
| `performance` | `seo` |
7. **`--deploy`.** When passed, publish `report.html` via the DA
transport per `../deploy/da-deploy-protocol.md` — PUT the file as
a single source, POST preview, POST live, verify the delivered
URL returns 200 — and print the delivered URL. Transport only;
never run deploy's section→block conversion on the report.
8. **Chat summary.** Short — the work is on disk and openable:
```
audit complete — <url>
Site health: <overall>/100
<dimension>: <score> × 7 (not-measured dimensions listed with reasons)
Findings: <n> P1 · <n> P2 · <n> P3
Top lever: <the single highest-impact P1, one line>
Report: stardust/audit/<domain-slug>/report.html
Data: stardust/audit/<domain-slug>/audit.json
Next: run `$stardust uplift <url>` — the report's closing directions
are its variant briefs.
```
## Degradation ladder
Probed once in Phase 0; every degradation is recorded in
`audit.json#degradations` and rendered in the report's methodology
appendix. None of these stops the audit.
| capability absent | behavior |
|---|---|
| refero MCP | skip Phase 5; `benchmarks.status: "skipped"` with reason |
| marketing-skills | run the Phase 3 / Phase 4 checks directly (tabled above) |
| modern-web-guidance | generic remediation text; `guides: []` |
| PageSpeed Insights | Playwright-only lab metrics; measurement note says lab TBT proxies INP |
| Playwright pixel sampling infeasible | `brandColorShare` ships as `method: "surface-estimate"` with basis |
| rollout project | no ledger recording; `ledgerId: null` on every finding |
## Hard constraints
- **No fabricated data.** A measurement that could not be taken is
`not measured (<reason>)` in both artifacts. Estimates are labeled
with method + basis. This is the same discipline extract enforces
against synthesis (`../extract/SKILL.md` § Failure modes) —
fabricated audit numbers are worse than missing ones because they
are actionable-looking and wrong.
- **Evidence discipline.** Every finding cites observable evidence:
a measurement key, a `T-*` tension id, a screenshot region, a
check id, or a benchmark URL. Uncited claims are cut in synthesis.
- **Report is craft-rendered.** `report.html` is authored by
`$impeccable craft` against the brief in
`reference/report-format.md`, validated afterward — never
hand-templated, never hand-patched.
- **Provenance is mandatory** on both artifacts, per
`../stardust/reference/artifact-map.md` § Provenance shapes.
- **Non-interactive.** No questions in normal flow; assumptions are
stated in the report. The only stops are the two below.
- **Audit does not fix.** Fixes belong to `uplift` (page redesign),
`direct` Phase 2.5 (improvements list), and rollout's optimize
loop (platform autofix). Audit names the fix; it never edits the
site.
## Stop conditions
Stop and surface only if:
(a) **Extract fails entirely** — site unreachable, structure
unparseable, bot-management block past the headed-Chrome
fallback. Surface extract's error verbatim; nothing to audit.
(b) **impeccable unavailable** — Phase 2's critique/audit arms and
Phase 6's report render require it. Per the Phase 0 carve-out,
the run continues in degraded mode (VISION pass, SEO/technical,
LLM visibility, benchmarks all still fire) and writes
`audit.json`; then stop and tell the user the designed report
needs the impeccable plugin — deliver the data, not a
hand-templated substitute.
Everything else degrades per the ladder; the audit never stops for
confirmation in normal flow.
## Outputs
```
stardust/
├── current/ ← from extract (reused when <7 days old)
│ ├── _brand-extraction.json
│ ├── brand-review.html ← Tensions section = Phase 1 input
│ ├── pages/<slug>.json
│ └── assets/screenshots/<slug>.png ← VISION-pass + report evidence figures
└── audit/
└── <domain-slug>/ ← hostname, www-stripped, dots → dashes
├── audit.json ← scorecard, measurements, findings[], provenance
└── report.html ← craft-rendered, self-contained
stardust/rollout/optimize/findings.json ← appended via findings.mjs (rollout projects only)
```
Audit writes no `state.json` entries — extraction state belongs to
`extract`; audit's own artifacts are self-describing via provenance.
Re-running audit against a fresh extraction overwrites
`stardust/audit/<domain-slug>/`; ledger recordings dedupe by the
ledger's own id hash.
## Scope
- Audits and prescribes; never modifies the site or its redesign
artifacts.
- One origin per run. Auditing a competitor set is N runs.
- The natural continuations: `$stardust uplift <url>` (the closing
directions are its variant briefs), the stardust `direct` skill (findings
feed the Phase 2.5 improvements list), rollout's optimize loop
(ledger findings with known check ids autofix on AEM).
## References
- `reference/scoring.md` — the seven dimensions, weights, observable
anchors at 40/70/90, scoring procedure.
- `reference/report-format.md` — `audit.json` schema (Part 1) and
the `report.html` craft brief + post-render validation (Part 2).
- `../extract/SKILL.md` — crawl, capture, brand-surface extraction;
§ Failure modes for the anti-synthesis discipline.
- `../extract/reference/brand-review-template.md` § Tensions — the
`T-*` detector catalog Phase 1 carries forward.
- `../prototype/SKILL.md` § Invoking impeccable — the skill-invocation
delegation mechanic reused for critique (Phase 2) and the report
render (Phase 6).
- `../rollout/reference/audit-sources.md` — the findings-ledger
normalization rules (severity, fixability) Phase 6 applies.
- `../rollout/reference/checks.md` — baseline check ids to reuse so
AEM autofix picks the findings up.
- `../rollout/scripts/findings.mjs` — the ledger writer (`record`).
- `../uplift/SKILL.md` § The three-variant role contract — the frame
for the closing uplift directions.
- `../prototype/reference/motion-registers.md` § Selection heuristic
— register suggestion for direction C.
- `../direct/SKILL.md` § Phase 2.5 — the improvements list audit
findings feed on a subsequent redesign.
- `../deploy/da-deploy-protocol.md` — the DA transport behind
`--deploy` (source PUT → preview → live; no block conversion).
- `../stardust/SKILL.md` § Setup — master-skill setup run in Phase 0.
- `../stardust/reference/artifact-map.md` — provenance shapes.
© adobe · Apache-2.0 · adobe/skills
Similar skills
All skills for Design →audit by other authors comes first.