How Skills Work

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.

Why YAML frontmatter?

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)

Script Structure
Why Scripts?

#!/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:

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

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

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

CLI Tools
claude.ai
OpenCode

# 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.

Element	Convention	Examples
Skill directory	kebab-case	`core-web-vitals`, `best-practices`
Main file	UPPERCASE	`SKILL.md` (exact)
Scripts	kebab-case.sh	`analyze-performance.sh`, `audit.sh`
References	UPPERCASE.md	`LCP.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:

Bad Example
Good Example

<img src="hero.jpg">

<img src="hero.jpg" 
     width="1200" 
     height="600" 
     alt="Hero image" 
     loading="lazy">

Thresholds Format

Use tables for clarity:

Metric	Good	Needs improvement	Poor
LCP	≤ 2.5s	2.5s – 4.0s	> 4.0s
INP	≤ 200ms	200ms – 500ms	> 500ms
CLS	≤ 0.1	0.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

Get Started

Core Concepts

Guides

What are Agent Skills?

Skill Structure

SKILL.md: The Core File

Scripts Directory

References Directory

Progressive Disclosure Pattern

How Skills Load into AI Agents

Real Examples from Web Quality Skills

Example 1: Core Web Vitals Skill

Example 2: Web Quality Audit Skill

Naming Conventions

Content Guidelines

Guidelines Format

Code Examples Format

Thresholds Format

Framework Agnostic Design

​What are Agent Skills?

​Skill Structure

​SKILL.md: The Core File

​Scripts Directory

​References Directory

​Progressive Disclosure Pattern

​How Skills Load into AI Agents

​Real Examples from Web Quality Skills

​Example 1: Core Web Vitals Skill

​Example 2: Web Quality Audit Skill

​Naming Conventions

​Content Guidelines

​Guidelines Format

​Code Examples Format

​Thresholds Format

​Framework Agnostic Design

What are Agent Skills?

Skill Structure

SKILL.md: The Core File

Scripts Directory

References Directory

Progressive Disclosure Pattern

How Skills Load into AI Agents

Real Examples from Web Quality Skills

Example 1: Core Web Vitals Skill

Example 2: Web Quality Audit Skill

Naming Conventions

Content Guidelines

Guidelines Format

Code Examples Format

Thresholds Format

Framework Agnostic Design