Skip to main content

​
What are Agent Skills?

Web Quality Skills follows the Agent Skills specification - a standard format for packaging instructions that AI coding agents can load and execute. Think of skills as specialized instruction sets that teach agents how to perform specific tasks.
Agent Skills are not traditional code libraries. They are instruction files that AI agents read to understand how to perform specialized tasks like auditing web quality, optimizing performance, or improving accessibility.

​
Skill Structure

Each skill follows a consistent directory structure designed for progressive disclosure: 
skill-name/
├── SKILL.md              # Main instruction file (< 500 lines)
├── scripts/              # Automation scripts (optional)
│   ├── analyze.sh
│   └── audit.sh
└── references/           # Detailed documentation (optional)
    ├── DETAILED_GUIDE.md
    └── EXAMPLES.md

​
SKILL.md: The Core File

Every skill centers around a SKILL.md file with YAML frontmatter: 
---
name: skill-name
description: One sentence describing when to use this skill. Include trigger phrases.
license: MIT
metadata:
  author: web-quality-skills
  version: "1.0"
---

# Skill title

Brief description of what the skill does.

## How it works

Numbered steps explaining the process.

## Guidelines

Categorized rules with clear formatting.

## Examples

Practical code examples with before/after.

## References

Links to additional documentation files.
The frontmatter provides machine-readable metadata that agents use to:
  • Identify the skill by name
  • Understand when to activate it (via the description)
  • Track versions and authorship
  • Manage licensing

​
Scripts Directory

The scripts/ directory contains executable automation scripts that:
  • Use #!/bin/bash shebang
  • Follow fail-fast behavior with set -e
  • Write status to stderr, results to stdout
  • Output machine-readable data (typically JSON)
#!/bin/bash
set -e

cleanup() {
  rm -f "$TEMP_FILE"
}
trap cleanup EXIT

TEMP_FILE=$(mktemp)

echo "Analyzing..." >&2
# ... analysis logic ...

echo '{"score": 85, "issues": []}'

​
References Directory

The references/ directory contains detailed documentation:
  • Individual files focused on single topics (< 200 lines each)
  • Loadable independently by agents
  • Include practical examples
  • Link to authoritative sources
Example from Web Quality Skills: 
core-web-vitals/
└── references/
    ├── LCP.md          # Detailed LCP optimization guide
    ├── INP.md          # Interaction to Next Paint specifics
    └── CLS.md          # Layout Shift prevention techniques

​
Progressive Disclosure Pattern

Web Quality Skills uses progressive disclosure to manage complexity:
1

Keep SKILL.md Under 500 Lines

The main instruction file must be concise. This ensures agents can:
  • Load skills quickly without consuming too much context
  • Understand the core functionality at a glance
  • Decide whether to load additional references
2

Move Details to References

Detailed explanations, edge cases, and extensive examples go in references/:
  • Each reference file under 200 lines when possible
  • Focused on a single topic
  • Agents load them only when needed
3

Use Scripts for Automation

Complex operations that would require many instructions are better as scripts:
  • Script execution output is compact
  • Reduces token usage in agent conversations
  • Provides consistent, repeatable results

​
How Skills Load into AI Agents

# Using add-skill tool
npx add-skill addyosmani/web-quality-skills

# Manual installation
cp -r skills/* ~/.claude/skills/

​
Real Examples from Web Quality Skills

​
Example 1: Core Web Vitals Skill

skills/core-web-vitals/
├── SKILL.md                # 442 lines - comprehensive but under 500
├── scripts/
│   └── measure-cwv.sh     # Automated CWV measurement
└── references/
    ├── LCP.md             # Deep dive on Largest Contentful Paint
    ├── INP.md             # Interaction to Next Paint details
    └── CLS.md             # Cumulative Layout Shift patterns
Main SKILL.md includes:
  • Three metrics overview table
  • Common issues and quick fixes for each metric
  • Optimization checklists
  • Debugging code snippets
  • Framework-specific patterns
References contain:
  • Extensive optimization strategies
  • Edge case handling
  • Performance profiling techniques
  • Advanced debugging approaches

​
Example 2: Web Quality Audit Skill

skills/web-quality-audit/
├── SKILL.md                # 171 lines - orchestration layer
├── scripts/
│   └── full-audit.sh      # Runs comprehensive audit
└── references/
    ├── performance.md     # Links to performance skill
    ├── accessibility.md   # Links to accessibility skill
    └── seo.md            # Links to SEO skill
This skill demonstrates orchestration:
  • Main file provides high-level audit structure
  • References other skills for deep-dives
  • Includes severity levels and prioritization
  • Provides output format templates

​
Naming Conventions

Consistent naming helps agents discover and load skills correctly.
ElementConventionExamples
Skill directorykebab-casecore-web-vitals, best-practices
Main fileUPPERCASESKILL.md (exact)
Scriptskebab-case.shanalyze-performance.sh, audit.sh
ReferencesUPPERCASE.mdLCP.md, WCAG.md, FAQ.md

​
Content Guidelines

When authoring skills, follow these patterns:

​
Guidelines Format

* **Guideline title.** Concise explanation with specific values or thresholds.
Example: 
* **Images have dimensions.** Set explicit `width` and `height` attributes on `<img>` to prevent layout shifts. Use CSS `aspect-ratio` as a fallback.

​
Code Examples Format

Always show problem and solution: 
<img src="hero.jpg">

​
Thresholds Format

Use tables for clarity:
MetricGoodNeeds improvementPoor
LCP≤ 2.5s2.5s – 4.0s> 4.0s
INP≤ 200ms200ms – 500ms> 500ms
CLS≤ 0.10.1 – 0.25> 0.25

​
Framework Agnostic Design

Web Quality Skills work across all frameworks: 
## Framework-specific notes

**React/Next.js:** Use `next/image`, `React.lazy()`, `Suspense`
**Vue/Nuxt:** Use `nuxt/image`, async components, `v-once`
**Svelte/SvelteKit:** Use `{#await}`, `svelte:image`
**Astro:** Use `<Image>`, partial hydration
**Static HTML:** Use native lazy loading, `<picture>`
  • Show vanilla HTML/CSS/JS first
  • Add framework notes in separate sections
  • Never require a specific framework
  • Use standard web APIs when possible

Build docs developers (and LLMs) love

Get started for freeTalk to us