claude_mac/skills/validate/SKILL.md

---

name: validate description: | Web standards audit — W3C HTML validity (validator.nu), W3C CSS validity (jigsaw.w3.org/css-validator), WCAG 2.1 accessibility (axe-core, pa11y, WAVE API). Dedicated to syntactic and accessibility conformance. Produces .claude/audits/VALIDATE.md. Dispatches the validator-analyzer agent with a STRICT scope filter — no meta/OG/JSON-LD/CWV/security-header noise. Trigger: "validate", "validation", "w3c", "html validity", "css validity", "wcag", "accessibility", "a11y audit", "axe", "pa11y", "wave", "validator.w3.org", "nu validator", "validation html", "accessibilité", "audit a11y", "audit wcag", "normes w3c", "conformité web", "validité html css". For security hardening (CSP, HSTS, 404) → use /harden. For SEO/indexability (meta, sitemap, JSON-LD) → use /seo. For AI engines (llms.txt, QAPage, entity SEO) → use /geo. argument-hint: [URL] [--fix] [--local|--full] [--no-external] allowed-tools:

• Read
• Edit
• Write
• Bash
• Grep
• Glob
• Agent
• WebFetch

---

/validate — web standards audit (W3C + WCAG)

This skill orchestrates a narrow-scope standards audit :

• W3C HTML validity — validator.nu API (FULL) or html-validate / vnu.jar (LOCAL) or static fallback.
• W3C CSS validity — jigsaw.w3.org/css-validator API (FULL) or stylelint / css-tree (LOCAL) or static fallback.
• WCAG 2.1 accessibility — pa11y / @axe-core/cli / WAVE API (FULL) or axe against built HTML (LOCAL) or static checklist.

Scope boundary :

• In : HTML syntactic validity (DOCTYPE, required attrs, tag nesting, ID uniqueness, heading hierarchy), CSS syntactic validity (parsing errors, unknown properties, at-rule misuse), WCAG 2.1 A / AA / AAA violations (ARIA, landmarks, contrast, keyboard, SR affordances, alt text).
• Out : meta tags (title/description/OG), JSON-LD / Schema.org, sitemap.xml, robots.txt, llms.txt, security headers (HSTS/CSP), cookie flags, Core Web Vitals, image compression, hreflang, i18n routing, generic code linting (ESLint, Prettier), TypeScript type errors.

If a finding appears in an out-of-scope area (e.g. missing meta description), the agent drops it silently — /validate stays focused.

Relation to other skills

• /onboard runs an initial a11y audit at project setup (axe or static checklist → .onboard-audit/a11y.md). /validate is the on-demand equivalent, re-runnable anytime against the current codebase, and also covers HTML/CSS validity (which /onboard does not).
• /harden audits security posture (headers, TLS, redirects). /validate audits conformance. They share no findings.
• /seo and /geo audit indexability. They may flag the same HTML features (alt attrs, heading structure) but from a ranking perspective. /validate flags from a standards perspective (WCAG SC number, W3C rule id). Findings may overlap — both reports are still valid.

---

STEP 0 — Collect context

Parse arguments

• If $ARGUMENTS contains https?://<url> → TARGET_URL.
• Extract DOMAIN from TARGET_URL : DOMAIN=${TARGET_URL#http*://}; DOMAIN=${DOMAIN%%/*}.
• If $ARGUMENTS contains --fix → MODE=fix. Else MODE=audit.
• If --local → DEPTH=LOCAL. If --full → DEPTH=FULL.
• If URL present and no depth flag → default DEPTH=FULL.
• If no URL and no depth flag → default DEPTH=LOCAL.
• If --no-external → EXTERNAL=off. Else on.
• EXTERNAL auto-off in LOCAL mode (no URL to scan remotely).

Detect HTML / CSS files

HTML_COUNT=$(find . -name "*.html" \
  -not -path "*/node_modules/*" \
  -not -path "*/dist/*" \
  -not -path "*/.next/*" \
  -not -path "*/.validate-cache/*" 2>/dev/null | wc -l)

CSS_COUNT=$(find . -name "*.css" \
  -not -path "*/node_modules/*" \
  -not -path "*/dist/*" \
  -not -path "*/.next/*" 2>/dev/null | wc -l)

If both counts are 0 and no URL provided → abort with :

⚠️  No HTML or CSS files found and no URL provided. /validate needs
   either local files or a live URL. Re-run with --full <url>.

Detect framework

FRAMEWORK="static"
[ -f astro.config.mjs ] || [ -f astro.config.ts ] && FRAMEWORK="astro"
[ -f next.config.js ] || [ -f next.config.mjs ] || [ -f next.config.ts ] && FRAMEWORK="next"
[ -f vite.config.js ] || [ -f vite.config.ts ] && FRAMEWORK="vite"
[ -f svelte.config.js ] && FRAMEWORK="svelte"
[ -f nuxt.config.js ] || [ -f nuxt.config.ts ] && FRAMEWORK="nuxt"
[ -f vue.config.js ] && FRAMEWORK="vue"

For JS frameworks, HTML validity must target built output. Check for build dir :

BUILD_DIR=""
for d in dist _site build out public; do
  [ -d "$d" ] && BUILD_DIR="$d" && break
done

If framework is JS-based and BUILD_DIR is empty, warn :

⚠️  Framework detected : <name>. No build output found.
   HTML validity on JSX/TSX source is not meaningful.
   Options :
     1. Run `npm run build` then re-run /validate
     2. Use --full <url> to audit production
     3. Continue with partial LOCAL audit (CSS + static WCAG only)

Detect LOCAL tooling

HAS_HTML_VALIDATE=$(npx --no-install html-validate --version >/dev/null 2>&1 && echo yes || echo no)
HAS_STYLELINT=$(npx --no-install stylelint --version >/dev/null 2>&1 && echo yes || echo no)
HAS_AXE=$(npx --no-install @axe-core/cli --version >/dev/null 2>&1 && echo yes || echo no)
HAS_PA11Y=$(npx --no-install pa11y --version >/dev/null 2>&1 && echo yes || echo no)
HAS_VNU=$([ -f /usr/share/vnu/vnu.jar ] || [ -f /opt/vnu/vnu.jar ] && echo yes || echo no)

Missing tools are NOT blockers — agent falls back to remote APIs (FULL) or static checks.

Display collected context

VALIDATE — context
URL          : <url or — (local mode)>
Domain       : <domain or —>
Depth        : LOCAL | FULL
Mode         : audit | fix
External     : on | off (auto-off in LOCAL)
HTML files   : <N>
CSS files    : <N>
Framework    : <astro | next | vite | svelte | nuxt | vue | static>
Build dir    : <dist/ | _site/ | ... | — none found>
Local tools  : html-validate=<y/n>, stylelint=<y/n>, axe=<y/n>, pa11y=<y/n>, vnu=<y/n>

If MODE=fix, warn :

⚠️  Fixes proposés comme diffs. Appliqués seulement après confirmation.

---

STEP 1 — Dispatch validator-analyzer

Spawn a single validator-analyzer subagent with explicit scope and collected context :

Agent(
  subagent_type="validator-analyzer",
  description="validate — W3C HTML + CSS + WCAG audit",
  prompt="""
  Dispatched from /validate. STRICT SCOPE — W3C HTML validity + W3C
  CSS validity + WCAG 2.1 accessibility ONLY.

  CONTEXT:
    TARGET_URL       : <url or "none — LOCAL mode">
    DOMAIN           : <domain or —>
    DEPTH            : <LOCAL | FULL>
    MODE             : <audit | fix>
    EXTERNAL         : <on | off>
    HTML_FILES       : <count>
    CSS_FILES        : <count>
    FRAMEWORK        : <name>
    BUILD_DIR        : <path or "none">
    LOCAL_TOOLS      : html-validate=<y/n>, stylelint=<y/n>, axe=<y/n>, pa11y=<y/n>, vnu=<y/n>

  Execute your spec at $HOME/.claude/agents/validator-analyzer.md
  starting at STEP 1 (skip STEP 0 — context is above).

  OUT OF SCOPE — DROP silently if encountered :
    - meta tags (title/description/OG/Twitter/canonical)
    - JSON-LD / Schema.org / microdata
    - sitemap.xml, robots.txt, llms.txt
    - AI crawler directives
    - security headers (HSTS/CSP/X-Frame-Options/cookie flags)
    - Core Web Vitals, perf budgets
    - hreflang, i18n routing
    - image compression, video formats
    - generic code linting (ESLint, Prettier, TS errors)

  Mode behavior :
    - MODE=audit : NO file modifications. Report-only. Propose fixes
      as diffs in the report (```diff blocks), do NOT apply.
    - MODE=fix   : Report issues, then produce Fix bundle (§5) with
      concrete diffs for auto-fixable items. STOP and emit
      "READY TO APPLY — awaiting dispatcher confirmation" at the end
      of §5. Do NOT apply any Edit/Write — the dispatcher handles STEP 3.

  Output: write <PROJECT_ROOT>/.claude/audits/VALIDATE.md (run `mkdir -p .claude/audits` first) per the structure in your
  spec (sections 0-8, score XX/100).
  """
)

---

STEP 2 — Verify output

test -s .claude/audits/VALIDATE.md && wc -l .claude/audits/VALIDATE.md || echo "MISSING .claude/audits/VALIDATE.md"

If missing or empty :

⚠️  validator-analyzer did not produce .claude/audits/VALIDATE.md. Options :
  A) Retry with same scope
  B) Downgrade to LOCAL and retry (if FULL failed on network)
  C) Abort

Extract the score and critical-alert count from .claude/audits/VALIDATE.md for the console summary :

grep -oE '\*\*Score\*\*\s+:\s+[0-9]+ / 100' .claude/audits/VALIDATE.md | head -1
grep -c '^### \[Critique\]' .claude/audits/VALIDATE.md

---

STEP 3 — Apply fixes (MODE=fix only)

Skip this step if MODE=audit.

If .claude/audits/VALIDATE.md ends with READY TO APPLY — awaiting dispatcher confirmation :

1. Parse the ## 5. Fix bundle section.
2. Group by file. For each group, show the combined diff to the user.
3. Ask :

VALIDATE — fix bundle ready

Files to modify (N) :
  - src/Layout.astro       (3 fixes : lang attr, alt="", heading renumber)
  - src/styles/main.css    (1 fix : invalid property removed)
  - src/pages/contact.html (2 fixes : unclosed tag, duplicate id)

Critical : X | Haute : Y | Moyenne : Z | Basse : W

Options :
  A) Apply all
  B) Review each diff before applying
  C) Apply only Critique + Haute
  D) Abort — keep .claude/audits/VALIDATE.md as audit report

4. On A : apply each bundle via Edit (targeted old_string / new_string). Never use Write on shared templates (risk of overwriting /seo or /geo content — meta tags, JSON-LD).
5. On B : for each diff, show and ask yes/no/skip.
6. On C : filter to Critique + Haute, then behave as A.
7. On D : stop, leave .claude/audits/VALIDATE.md untouched.

After applying, append a ## 8. Changes applied section with commit-ready summary lines :

## 8. Changes applied

Date : <ISO-8601>
Files modified : <N>
Fixes applied : <N>

### src/Layout.astro
- [Haute][HTML] Added `lang="en"` to `<html>` (WCAG 3.1.1, W3C required attr)
- [Haute][WCAG AA] Added `alt=""` to decorative icon at line 42
- [Moyenne][HTML] Renumbered h3 → h2 (heading hierarchy, line 67)

### src/styles/main.css
- [Moyenne][CSS] Removed invalid property `bakground` → `background` at line 23

Verification :
- Re-run /validate → expected score bump <before> → <after>
- Tests to run : a11y regression (pa11y-ci), visual snapshot

Never apply fixes without explicit confirmation. Never use --no-verify on git hooks.

---

STEP 4 — Console summary

VALIDATE AUDIT COMPLETE
URL              : <url or static>
Depth            : LOCAL | FULL
Mode             : audit | fix
Score            : XX / 100  (<before> → <after> if fix applied)
Report           : .claude/audits/VALIDATE.md

BREAKDOWN :
  W3C HTML         : <N errors / M warnings>
  W3C CSS          : <N errors / M warnings>
  WCAG 2.1         : <N A> / <M AA> / <K AAA> violations, <L incomplete>

TOP 3 ACTIONS (by severity × user impact) :
  1. [Critique] <title> — <file:line>
  2. [Haute]    <title>
  3. [Haute]    <title>

NEXT STEPS :
  • /validate <url> --fix         → apply recommended fixes
  • /validate <url> --full        → re-run with live URL + remote APIs
  • /validate --no-external       → skip third-party APIs (faster, LOCAL-like)
  • /harden / /seo / /geo         → complementary audits (other scopes)

Install for better LOCAL coverage :
  npm i -D html-validate stylelint @axe-core/cli pa11y

---

Rules

• Scope is non-negotiable. If you find yourself reporting meta tags, sitemap, CSP, or JSON-LD, you drifted. Drop it. /harden, /seo, /geo own those respectively.
• Single agent dispatch. Only validator-analyzer. No parallel fan-out.
• Never apply fixes without user confirmation, even in --fix. The fix mode prepares the bundle; the dispatcher confirms (A/B/C/D).
• LOCAL vs FULL is about data sources, not scope. Both cover the same 3 axes. LOCAL may be degraded if local tools missing (agent falls back to static checks — flagged "STATIC MODE" in report).
• Framework awareness. For SPA/JS frameworks, validate built output (dist/, _site/, build/, out/), not JSX/TSX source. Warn if no build dir present.
• Respect CLAUDE.md architecture rules. Public websites must ship WCAG 2.1 AA per France RGAA 4.1 when in scope. Flag AA violations as Haute, A violations as Critique.
• External validators are authoritative on live URLs. validator.nu and jigsaw are the W3C backends. If a local tool disagrees with them, trust the W3C backend; flag the divergence as a finding.
• One report file. .claude/audits/VALIDATE.md. On re-run, move previous content to a ## Historique section, do not overwrite silently.
• Cache dir. .validate-cache/ (gitignored) stores raw tool outputs for debugging. Do not commit.
• Conservative auto-fix. Only structural/syntactic fixes with no ambiguity. Content decisions (alt text, labels, contrast choices) always go to §6 User actions — never auto-applied.