Installing Web Quality Skills

Web Quality Skills are Agent Skills that work with AI coding agents like OpenCode, Claude Code, Cursor, and Codex. Follow the installation method for your agent below.

What are Agent Skills? Agent Skills are specialized instruction sets that extend your AI coding agent’s capabilities. Web Quality Skills teach agents to audit and optimize web projects based on Lighthouse and Core Web Vitals.

Quick Installation

The fastest way to install Web Quality Skills is using the add-skill CLI tool:

Run the add-skill command

Open your terminal and run:

npx skills add addyosmani/web-quality-skills

npx add-skill addyosmani/web-quality-skills

This command automatically installs all six Web Quality Skills to your agent’s skills directory.

Verify installation

Confirm the skills were installed successfully:

ls ~/.claude/skills/
# or for other agents:
ls ~/.opencode/skills/
ls ~/.cursor/skills/

You should see six skill directories:

web-quality-audit/
performance/
core-web-vitals/
accessibility/
seo/
best-practices/

Start using skills

Skills activate automatically when your request matches their description. Try:

Audit this page for web quality issues

Your AI agent will now use the Web Quality Skills to analyze your code!

Installation by Agent

OpenCode
Claude Desktop
claude.ai (Web)
Cursor
Codex

OpenCode Installation

OpenCode automatically loads skills from ~/.opencode/skills/.

Install with add-skill

npx add-skill addyosmani/web-quality-skills

The tool automatically detects OpenCode and installs to the correct directory.

Restart OpenCode

Restart your OpenCode session to load the new skills:

# In VS Code
Cmd+Shift+P → "Reload Window"

Verify

Ask OpenCode:

What skills do you have available?

OpenCode should list the six Web Quality Skills.

OpenCode supports parallel skill execution, so you can run multiple audits simultaneously (e.g., “Check both performance and accessibility”).

Claude Desktop Installation

Claude Desktop loads skills from ~/.claude/skills/.

Install with add-skill

npx add-skill addyosmani/web-quality-skills

Restart Claude Desktop

Restart the Claude Desktop app to load the skills.

Test the skills

In a new conversation, try:

Review the accessibility of this HTML page

Claude will use the accessibility skill to provide a comprehensive audit.

claude.ai Web Installation

For the claude.ai web interface, skills need to be added to Projects or pasted into conversations.

Download the skills

Clone the repository:

git clone https://github.com/addyosmani/web-quality-skills.git
cd web-quality-skills

Add to Project Knowledge

Create a new Claude Project
Go to Project Settings → Knowledge
Upload the skills/ directory

All six skills will be available in that project.

Or paste into conversation

Alternatively, copy the contents of a specific SKILL.md file and paste it into your conversation:

# Example: Copy the performance skill
cat skills/performance/SKILL.md | pbcopy

Then paste in your conversation before asking for an audit.

Pasting skills into conversations consumes more context tokens. For repeated use, add skills to Project Knowledge instead.

Cursor Installation

Cursor loads skills from ~/.cursor/skills/.

Install with add-skill

npx add-skill addyosmani/web-quality-skills

Configure Cursor

Ensure Cursor’s agent mode is enabled:

Open Cursor Settings
Navigate to Features → Agent
Enable “Agent Mode”

Test the skills

Open a web project and use Cursor’s chat:

Audit this component for Core Web Vitals issues

Codex Installation

Install with add-skill

npx add-skill addyosmani/web-quality-skills

The tool detects Codex and installs to ~/.codex/skills/.

Restart Codex

Restart your Codex instance to load the new skills.

Invoke skills

Skills activate automatically based on your prompts:

Optimize the performance of this page

Manual Installation

If you prefer to install manually or the add-skill tool isn’t working:

Clone the repository

git clone https://github.com/addyosmani/web-quality-skills.git
cd web-quality-skills

Copy skills to your agent's directory

cp -r skills/* ~/.claude/skills/

cp -r skills/* ~/.opencode/skills/

cp -r skills/* ~/.cursor/skills/

cp -r skills/* ~/.codex/skills/

Verify directory structure

Confirm the skills directory contains:

~/.claude/skills/
├── web-quality-audit/
│   ├── SKILL.md
│   ├── scripts/
│   └── references/
├── performance/
│   ├── SKILL.md
│   └── ...
├── core-web-vitals/
├── accessibility/
├── seo/
└── best-practices/

Restart your agent

Restart your AI coding agent to load the skills.

Configuration

Customizing Skill Behavior

You can customize how skills behave by editing the SKILL.md files:

Adjust trigger phrases

Edit the description field in the YAML frontmatter to change when skills activate:

---
name: performance
description: Optimize web performance. Use when asked to "speed up", "optimize performance", or "make faster"
---

Add your own trigger phrases to match your team’s vocabulary.

Modify thresholds

Change performance budgets or scoring thresholds in the skill content:

## Performance budget

| Resource | Budget |
|----------|--------|
| JavaScript | < 500 KB | <!-- Changed from 300 KB -->

Add framework-specific patterns

Add custom optimization patterns for your framework in the relevant sections:

### Remix
// Use Remix's built-in optimizations
export const links = () => [
  { rel: "preload", href: "/hero.jpg", as: "image" }
]

Advanced Configuration

# Create ~/.claude/skills.config.yaml
skills:
  priority:
    - web-quality-audit  # Always try this first
    - performance
    - accessibility
  disabled:
    - seo  # Disable if not needed

# Add to SKILL.md frontmatter
metadata:
  author: your-team
  version: "1.1"
  custom_thresholds:
    lcp_target: 2000  # 2s instead of 2.5s
    cls_target: 0.05  # Stricter than default

Verifying Installation

After installation, verify that skills are working correctly:

Check skills are loaded

Ask your agent:

What Web Quality Skills do you have available?

Expected response should list:

web-quality-audit
performance
core-web-vitals
accessibility
seo
best-practices

Run a test audit

Create a simple HTML file and ask for an audit:

<!-- test.html -->
<!DOCTYPE html>
<html>
  <head>
    <title>Test Page</title>
  </head>
  <body>
    <img src="photo.jpg">
    <h1>Hello World</h1>
  </body>
</html>

Then ask:

Audit test.html for web quality issues

Verify output format

The agent should return structured findings with:

✅ Issue categorization (Critical, High, Medium, Low)
✅ Specific file locations (e.g., test.html:7)
✅ Impact explanations
✅ Concrete fix recommendations with code examples

If you see this format, skills are working correctly!

Troubleshooting

Skills not being invoked

Problem: Agent doesn’t use skills even when prompted.Solutions:

Verify skills are in the correct directory for your agent
Check YAML frontmatter is valid (no syntax errors)
Restart your agent to reload skills
Use more specific trigger phrases (e.g., “Run a Lighthouse audit”)
Explicitly name the skill: “Use the performance skill to analyze this page”

Permission errors during installation

Problem: Permission denied when copying to skills directory.Solutions:

# Option 1: Use sudo (be careful)
sudo cp -r skills/* ~/.claude/skills/

# Option 2: Fix directory permissions
mkdir -p ~/.claude/skills
chmod 755 ~/.claude/skills

# Option 3: Use user-specific directory
export CLAUDE_SKILLS_DIR=~/my-skills
cp -r skills/* $CLAUDE_SKILLS_DIR/

Skills directory not found

Problem: Agent’s skills directory doesn’t exist.Solution:

# Create the directory first
mkdir -p ~/.claude/skills
# Or for other agents:
mkdir -p ~/.opencode/skills
mkdir -p ~/.cursor/skills

add-skill command not found

Problem: add-skill CLI tool not working.Solutions:

Ensure Node.js is installed: node --version (need 18+)
Use npx instead: npx add-skill ...
Install globally: npm install -g add-skill
Fall back to manual installation (see above)

Skills causing errors

Problem: Agent shows errors when trying to use skills.Solutions:

Check SKILL.md files have proper YAML frontmatter
Validate markdown syntax

Remove and reinstall skills:

rm -rf ~/.claude/skills/
npx add-skill addyosmani/web-quality-skills

Report issues at GitHub Issues

Updating Skills

To update to the latest version of Web Quality Skills:

# Using add-skill (recommended)
npx add-skill addyosmani/web-quality-skills --force

# Pull latest changes
cd web-quality-skills
git pull origin main

# Copy updated skills
cp -r skills/* ~/.claude/skills/

Skills follow semantic versioning. Check the metadata.version field in each SKILL.md to see the current version.

Next Steps

Quick Start Guide

Run your first web quality audit

Skills Overview

Learn about each skill in detail

Core Web Vitals

Deep dive into LCP, INP, and CLS optimization

Examples

See real-world optimization examples

Get Started

Core Concepts

Guides

Installation

Installing Web Quality Skills

Quick Installation

Installation by Agent

OpenCode Installation

Claude Desktop Installation

claude.ai Web Installation

Cursor Installation

Codex Installation

Manual Installation

Configuration

Customizing Skill Behavior

Advanced Configuration

Verifying Installation

Troubleshooting

Updating Skills

Next Steps

Quick Start Guide

Skills Overview

Core Web Vitals

Examples

​Installing Web Quality Skills

​Quick Installation

​Installation by Agent

​OpenCode Installation

​Claude Desktop Installation

​claude.ai Web Installation

​Cursor Installation

​Codex Installation

​Manual Installation

​Configuration

​Customizing Skill Behavior

​Advanced Configuration

​Verifying Installation

​Troubleshooting

​Updating Skills

​Next Steps

Quick Start Guide

Skills Overview

Core Web Vitals

Examples

Installing Web Quality Skills

Quick Installation

Installation by Agent

OpenCode Installation

Claude Desktop Installation

claude.ai Web Installation

Cursor Installation

Codex Installation

Manual Installation

Configuration

Customizing Skill Behavior

Advanced Configuration

Verifying Installation

Troubleshooting

Updating Skills

Next Steps