Skip to main content

​
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:
1

Run the add-skill command

Open your terminal and run:
npx skills add addyosmani/web-quality-skills
This command automatically installs all six Web Quality Skills to your agent’s skills directory.
2

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/
3

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 Installation

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

Install with add-skill

npx add-skill addyosmani/web-quality-skills
The tool automatically detects OpenCode and installs to the correct directory.
2

Restart OpenCode

Restart your OpenCode session to load the new skills:
# In VS Code
Cmd+Shift+P → "Reload Window"
3

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”).

​
Manual Installation

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

Clone the repository

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

Copy skills to your agent's directory

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

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/
4

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:
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.
Change performance budgets or scoring thresholds in the skill content:
## Performance budget

| Resource | Budget |
|----------|--------|
| JavaScript | < 500 KB | <!-- Changed from 300 KB -->
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

​
Verifying Installation

After installation, verify that skills are working correctly:
1

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
2

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
3

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

Problem: Agent doesn’t use skills even when prompted.Solutions:
  1. Verify skills are in the correct directory for your agent
  2. Check YAML frontmatter is valid (no syntax errors)
  3. Restart your agent to reload skills
  4. Use more specific trigger phrases (e.g., “Run a Lighthouse audit”)
  5. Explicitly name the skill: “Use the performance skill to analyze this page”
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/
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
Problem: add-skill CLI tool not working.Solutions:
  1. Ensure Node.js is installed: node --version (need 18+)
  2. Use npx instead: npx add-skill ...
  3. Install globally: npm install -g add-skill
  4. Fall back to manual installation (see above)
Problem: Agent shows errors when trying to use skills.Solutions:
  1. Check SKILL.md files have proper YAML frontmatter
  2. Validate markdown syntax
  3. Remove and reinstall skills: 
    rm -rf ~/.claude/skills/
npx add-skill addyosmani/web-quality-skills
  4. 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
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

Build docs developers (and LLMs) love

Get started for freeTalk to us