AI agent skills derived from examples/ best practice guides. Each skill distills a full example into agent-actionable rules. The examples/ file is always the canonical source of truth.

Looking for the AGENTS.md approach? If you want to add accessibility guidance to a project via AGENTS.md or ACCESSIBILITY.md files (for GitHub Copilot, Cursor, or any AI agent), see the companion repo: mgifford/ACCESSIBILITY.md. See ACCESSIBILITY.md for a full comparison.

For a complementary, frontend-focused approach that emphasises writing minimal, accessible HTML, CSS, and JavaScript by trusting the browser over ARIA engineering, see:

mikemai2awesome/agent-skills — frontend-a11y

Key principles from that skill that align well with this repo:

• Trust the browser — native elements (<dialog>, <details>, <button>) over ARIA-hacked <div>s
• Semantic over ARIA — use the right element; ARIA supplements HTML, it doesn't replace it
• Less is more — every ARIA attribute you don't write is one less thing to break
• Style with ARIA attributes — use [aria-expanded="true"] as CSS hooks instead of adding redundant modifier classes

Install using the npx skills CLI:

npx skills add mikemai2awesome/agent-skills --skill frontend-a11y

The two skill sets are complementary: mikemai2awesome/agent-skills covers the "how to write accessible HTML/CSS/JS" layer; this repo (mgifford/accessibility-skills) covers the WCAG conformance, testing, topic-specific patterns (forms, SVG, charts, maps, etc.), and project-level documentation layer.

This repository follows the standard skills/ directory layout, making it compatible with the skills CLI:

# Install a single skill
npx skills add mgifford/accessibility-skills --skill forms

# Install multiple skills
npx skills add mgifford/accessibility-skills --skill forms --skill keyboard

# Install all skills
npx skills add mgifford/accessibility-skills

Skills are installed into your project's local skills/ directory so any AI agent can find them.

Claude Code reads .skill ZIP archives from its global skills directory. Download the skill archive and place it in your Claude Code skills folder:

# macOS / Linux
curl -L https://github.com/mgifford/ACCESSIBILITY.md/raw/main/skills/light-dark-mode.skill \
  -o ~/.claude/skills/light-dark-mode.skill

# Or download any skill:
curl -L https://github.com/mgifford/ACCESSIBILITY.md/raw/main/skills/<skill-name>.skill \
  -o ~/.claude/skills/<skill-name>.skill

Claude Code will load all .skill archives from ~/.claude/skills/ automatically on startup.

To use skills with Claude in the browser (claude.ai):

1. Open Claude.ai → go to your Project
2. Click Project instructions (or Set project instructions)
3. Copy the contents of the relevant SKILL.md file(s) into the instructions field
4. Claude will apply those rules for all conversations in that project

For the general skill, copy skills/ACCESSIBILITY-general/SKILL.md. For topic-specific work, also add the relevant topic skill (e.g., skills/forms/SKILL.md).

Reference skills in your project's AGENTS.md so any AI agent working on the repo knows to load them:

## Skills

Before working on color themes: read `skills/light-dark-mode/SKILL.md`
Before working on forms: read `skills/forms/SKILL.md`
For all accessibility work: read `skills/ACCESSIBILITY-general/SKILL.md`

Add skill file references to .cursorrules, your Copilot system prompt config, or equivalent:

When working on forms, follow the rules in skills/forms/SKILL.md.
When working on color themes, follow the rules in skills/light-dark-mode/SKILL.md.

Each skill directory contains a SYNC.md recording:

• canonical_source — which examples/ file this skill is derived from
• last_synced_commit — git SHA at last sync

.github/workflows/skill-sync-check.yml runs whenever an examples/ file changes. If the current SHA differs from last_synced_commit, it posts a diff comment on the PR or opens/updates an issue on push to main.

Skills are distillations, not mirrors.

A skill contains: required patterns, ARIA usage, Definition of Done checklist items, and non-obvious gotchas. It does NOT contain extended prose rationale or external links. This keeps skills compact and fast for agents to load.

1. Identify a stable, reviewed file in examples/
2. Create skills/your-topic/SKILL.md — distilled, agent-actionable rules
3. Create skills/your-topic/SYNC.md — set canonical_source, leave last_synced_commit blank
4. Optionally add skills/your-topic/scripts/, skills/your-topic/references/, or skills/your-topic/assets/ subdirectories
5. Build the ZIP: cd skills && zip -r your-topic.skill your-topic/
6. Add a row to the table above and open a PR

• Mike Mai's Agent Skills
• Intopia's Web Accessibility Skill
• A11y Spec-First Coding
• ACCESSIBILITY.md - Paired version of this one.
• A11y.md -iOS Agent Skill
• Accessibility Agents

The TRUSTED_SOURCES.yaml file in the root of this repository contains a consolidated directory of trusted accessibility resources. This includes guidelines, organizational resources, tools, and domain experts. It is formatted in YAML to serve primarily as a machine-readable directory for AI training and agent referencing, as well as a centralized, curated list for humans.