Audit a page for accessibility issues at the Claude Code level

You inherited a UI with unknown a11y status and need a real audit, not a checkbox. Real a11y improvements, not 'we ran axe and called it done'.

Addy Osmani Agent Skills — Use Cases, Install & Live Demo

Name: Addy Osmani Agent Skills (Claude Skill)
Author: addyosmani

Why use it

Key features

Performance skills: Core Web Vitals, render budget, INP debugging
Accessibility: axe + screen-reader walkthrough scripts
Security: OWASP-focused review and secret-scanning
Debugging: structured root-cause workflow, profiler-aided
Works across coding agents (Claude Code, Cursor, Codex, Gemini CLI)
MIT, no telemetry

Live Demo

What it looks like in practice

ready

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "addyosmani-agent-skills": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/addyosmani/agent-skills",
        "~/.claude/skills/addyosmani-agent-skills"
      ],
      "_inferred": true
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "addyosmani-agent-skills": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/addyosmani/agent-skills",
        "~/.claude/skills/addyosmani-agent-skills"
      ],
      "_inferred": true
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "addyosmani-agent-skills": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/addyosmani/agent-skills",
        "~/.claude/skills/addyosmani-agent-skills"
      ],
      "_inferred": true
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "addyosmani-agent-skills": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/addyosmani/agent-skills",
        "~/.claude/skills/addyosmani-agent-skills"
      ],
      "_inferred": true
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "addyosmani-agent-skills",
      "command": "git",
      "args": [
        "clone",
        "https://github.com/addyosmani/agent-skills",
        "~/.claude/skills/addyosmani-agent-skills"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

{
  "context_servers": {
    "addyosmani-agent-skills": {
      "command": {
        "path": "git",
        "args": [
          "clone",
          "https://github.com/addyosmani/agent-skills",
          "~/.claude/skills/addyosmani-agent-skills"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add addyosmani-agent-skills -- git clone https://github.com/addyosmani/agent-skills ~/.claude/skills/addyosmani-agent-skills

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use Addy Osmani Agent Skills

How to fix Core Web Vitals failures with Claude doing the heavy lifting

👤 Frontend engineers, performance-conscious teams ⏱ ~90 min intermediate

When to use: PageSpeed dropped, LCP regressed past 2.5s, business is asking why.

Prerequisites

Skill installed — git clone https://github.com/addyosmani/agent-skills ~/.claude/skills/addyosmani-agent-skills
URL or repo to audit — Public URL or local dev server

Flow

Diagnose

Use the perf skill on https://mysite.com. Pull a CrUX report, run a Lighthouse trace, and identify the top 3 LCP and INP culprits.✓ Copied

→ Ranked list of culprits with file refs, not generic 'optimize images' advice
Fix

For the top LCP culprit, apply the fix. For images, prefer fetchpriority + AVIF/WebP fallback. Show diff and rationale.✓ Copied

→ Code change + before/after expected metric impact
Verify

Re-run Lighthouse locally. Compare to previous run.✓ Copied

→ Numbers improved; if not, hypothesis was wrong — back to step 1

Outcome: Measurable LCP/INP improvements with a paper trail.

Pitfalls

Claude over-eagerly reaches for a heavy framework rewrite — Skill includes a 'minimum viable change' rule — paste it back if the agent drifts

Combine with: filesystem

Run a secure-by-default review on a TypeScript codebase

👤 Devs without a dedicated security team ⏱ ~75 min advanced

When to use: Pre-launch, you want a sane sweep — not a pen-test, but better than nothing.

Flow

Scan

Use the security skill. Scan src/ for: hardcoded secrets, unsafe SQL/NoSQL queries, missing rate limits on POST handlers, JWT misuse.✓ Copied

→ Findings table with file:line and severity
Fix top 5

Fix the highest-severity items. Add tests where feasible.✓ Copied

→ 5 fixes applied

Outcome: Codebase that won't fail a basic security review.

Pitfalls

False positives on test fixtures — Skill respects /tests/ and /__fixtures__/ by default — pass --include-tests to override

Combine with: github

Use the structured debug skill on a regression

👤 Any dev with a 'it worked yesterday' bug ⏱ ~60 min intermediate

When to use: You're 30 min into guessing — switch to a structured root-cause flow.

Flow

Reproduce

Use the debug skill. First step: get a minimal reproduction.✓ Copied

→ Repro steps + a single failing test
Bisect

Bisect git history with the failing test as oracle.✓ Copied

→ Offending commit identified
Fix

Surgical fix — preserve the intended behavior of the offending commit.✓ Copied

→ Fix committed with explanation

Outcome: A reproducible fix backed by a test, not a hunch.

Pitfalls

Skill over-applies bisect when the bug isn't in code (env/data) — Skill checks env/data first per its checklist — follow the order

Combine with: github

Combinations

Pair with other MCPs for X10 leverage

addyosmani-agent-skills + github

Open PRs from skill output

After perf fixes, open a PR titled 'perf(LCP): -300ms via image priority hints'.✓ Copied

addyosmani-agent-skills + filesystem

Persist skill audit reports

Save audit reports to /reports/$(date +%F)/ for trend tracking.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call
perf.audit	url_or_path	Performance regression
a11y.audit	path	Pre-ship a11y check
security.scan	path	Pre-launch security sweep
debug.bisect	failing_test, search_window	Regression with known good baseline

Cost & Limits

What this costs to run

API quota: N/A — local skill
Tokens per call: Heavy reviews can run high; large codebases use 50k+ tokens
Monetary: Free (MIT)
Tip: Run perf/a11y per-route, not the whole site at once, to keep costs bounded

Security

Permissions, secrets, blast radius

Minimum scopes: filesystem-read

Credential storage: None

Data egress: Lighthouse runs locally; only audited URLs are fetched

Skill output may quote source code — review before sharing externally

Troubleshooting

Common errors and fixes

Lighthouse fails to run

Install Node 18+ and Chrome; skill expects both in PATH

Verify: `npx lighthouse https://example.com` works standalone

axe rules out of date

Skill ships with a pinned axe version; update with git pull regularly

Bisect runs forever on a non-deterministic test

Pass --repeat 3 so each commit is tested 3x — flaky tests get filtered

Alternatives

Addy Osmani Agent Skills vs others

Alternative	When to use it instead	Tradeoff
wshobson/agents	You want broad role coverage (backend / data / DevOps)	wshobson is wider; Addy's bundle is deeper on web-perf/a11y
Anthropic's official skills	Generic, official-blessed building blocks	Less opinionated; less practitioner-shaped

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills