Audit your site
This page shows you how to review a site built with Unblock before launch, with the four audit skills and their checklists.
Prerequisites
- An AI client connected over MCP: MCP Bridge.
- The Unblock skills installed: Agent skills.
- A browser tool, such as Chrome DevTools MCP. Without one, the checks that need it are reported as not checked.
The four audits
| Skill | Reviews | Needs a browser tool for |
|---|---|---|
unblock-audit-accessibility | The pages against WCAG 2.2 AA: structure, images, links and controls, keyboard and focus, contrast, zoom, motion, forms | The keyboard, contrast and layout checks |
unblock-audit-performance | LCP, INP and CLS from a trace, then the cause of each problem: images, fonts, CSS, scripts, layout shifts | Any measure |
unblock-audit-seo | Indexing, titles and descriptions, headings, links, images, structured data, sharing, languages | The <head> of each page, robots.txt and the sitemap; a web fetch tool works too |
unblock-audit-code | The HTML, the design tokens, the CSS selectors, the scripts, the Twig, images, fonts and forms | Console errors and failed requests, optional |
Each audit agrees on the scope with you first. The accessibility and performance audits start from the home page, the pages of your main task and one page of each template. The SEO audit covers every page of the sitemap. The code audit covers the site's CSS and every page and template built with Unblock.
The audits review the site as a visitor gets it: on the front end, logged out.
Run an audit
Name the skill, the pages and what you expect:
Use the unblock-audit-accessibility skill.
Audit {the home page, the contact page and one blog post} against WCAG 2.2 AA, on the front end,
logged out. Use the browser tool for keyboard, contrast and zoom.
Compute every contrast ratio, mark each finding as measured, observed or inferred, and change
nothing.
"Is my site accessible?" invites a yes or a no. This prompt sets the scope, the standard and the evidence expected, which keeps the AI from inventing findings or calling the site compliant. The prompts/review.md file of the repository has a prompt for each audit.
They change nothing
The audits review only. They change nothing, whatever your connection allows.
A read-only connection is enough for every audit, so use one when you can: with OAuth, you pick Read only when you approve the client. See OAuth.
The agent fixes the findings only when you ask, on a connection that can write. It goes through the other skills: unblock-design-system for the tokens, unblock-content for the text, unblock-build-page for the blocks. Then it checks each fix again and updates the report.
Read the report
Each report starts with a verdict: the main problems, the pages checked, and what could not be checked. Then come the findings, the most severe first:
- Severity: Critical, High, Medium or Low.
- Where: the pages, the component by its name, the selector.
- Evidence: what was found, and how it's known.
- Fix: what to change, and where.
- Recheck: how to confirm the fix.
The accessibility audit adds the WCAG success criterion of each finding, the performance audit the metric and its measure.
Evidence
| Level | Means |
|---|---|
| Measured | A tool returned it: a contrast computed from the styles, a trace, a status code |
| Observed | Seen in the markup, the CSS, the accessibility tree or a screenshot |
| Inferred | Read in the code, not confirmed in a browser |
A check that needs a browser tool, run without one, is "not checked". The code alone makes it "inferred" at most.
The audits never call a site "WCAG compliant", never state a contrast ratio they didn't compute, never guess the LCP element without a trace, and never promise a ranking.
Where the cause lives
Each finding says where its cause lives: your Unblock content, which the agent can fix over MCP, or the theme, another plugin, WordPress or the hosting. A finding outside Unblock is listed as out of scope, with who can fix it.
The audits report one finding per cause. A raw value used in ten selectors is one finding, with the ten selectors listed.
Needs a person
The report ends with the checks only a person can do, such as:
- The main task done with a screen reader, from the home page to its action.
- Captions on videos, and a transcript for audio.
- Search Console set up, with the sitemap sent.
- The field data of real visits, once the site has traffic.
- Someone who didn't build the site finding a component by its name and changing a color from the tokens alone.
Checklists
Each audit runs a checklist, which you can also go through yourself:
| Checklist | File |
|---|---|
| Accessibility | skills/unblock-audit-accessibility/references/checklist.md |
| Performance | skills/unblock-audit-performance/references/checklist.md |
| SEO | skills/unblock-audit-seo/references/checklist.md |
| Code | skills/unblock-audit-code/references/checklist.md |
Each item says how it can be checked:
- [code] from the rendered HTML and the CSS.
- [browser] with a browser tool.
- [human] by a person.
Before launch
The checklists/pre-launch.md file covers the whole site before it goes live: content, accessibility, performance, search, forms and email, code, and the site itself. It's shorter than the audits, which go deeper. Run it on the live site, logged out:
Go through checklists/pre-launch.md on the live site, logged out.
Check the [code] and [browser] items yourself and give me the result of each one.
List the [human] items for me to do. Change nothing.
It catches what a build leaves behind: [To confirm: …], [Assumption] and [Invented] markers, placeholder images, test pages, plugins not approved in brief.md, and font faces the design doesn't use.
When to audit
On a new site, the audits come after the pages: the brief, the design system, each page, then the audits. Run them in a new session, not the one that designed the site.
Taking a score for a verdict. A Lighthouse score of 100 isn't WCAG conformance. An SEO plugin's score says nothing of an Unblock page: Yoast's is the one its editor saved, with none for a page never opened there, and the analyses of Rank Math and All in One SEO find no words in Unblock blocks. Read the findings and the checks left to a person.
Next steps
- Agent skills: install the skills and see the order of work
- MCP Bridge: connect a client with read-only access
- SEO: what Yoast SEO, Rank Math, SEOPress and All in One SEO read of your pages