Web Standards Agent Skills

Agent skills and tools for standards engineers and AI agents working on Web Standards (WHATWG, W3C, WICG, IETF):

• web-archeologist (skills/web-archeologist/): A protocol to trace spec prose, algorithms, and issues back to their historical "Why"—bridging the gap between modern specification fragments and the 20-year history of GitHub issues, Bugzilla reports, W3C mailing list archives, and IRC/Matrix logs.
• html-spec-review (skills/html-spec-review/): Guidelines, prose style conventions, algorithmic review checklists, source-splitting tools (split_html.py), and static analyzers (check_webidl.py, check_algorithms.py, check_wpt_coverage.py) for authoring and reviewing changes to the WHATWG HTML Standard (whatwg/html).

The Problem

Specification source files (like WHATWG's html/source) are massive (160,000+ lines). Standard git blame often only shows the last editorial cleanup or infrastructure update, hiding the actual normative rationale that might date back to 2006, and editing or reviewing the monolithic source file directly is slow and error-prone.

The "Chain of Evidence" Protocol (web-archeologist)

This skill defines an archeological protocol for:

1. URL/Fragment -> Source Line: Using heuristics to find where a #fragment is actually defined in the source (even if generated by Bikeshed/Wattsi).
2. Deep Blame: Using git log -L to trace the history of a specific line through refactors and moves.
3. Spec Call Graph: Identifying callers and callees of a specific algorithm across standards (via WebDex) and within a spec.
4. Link Extraction: Identifying and categorizing references to:
   • GitHub: PRs and Issues.
   • W3C Bugzilla: Historical bug reports.
   • SVN Revisions: Direct search links for lists.w3.org archives.
   • Browser Bugs: Chromium, WebKit, and Gecko trackers.

HTML Specification Authoring & Review (html-spec-review)

This skill provides:

1. Source Splitting (scripts/split_html.py): Splits whatwg/html's source file at each <h2 tag into manageable section files and concatenates them back before committing.
2. Static Analyzers (scripts/):
   • check_webidl.py: Validates <pre class="idl"> cross-references, optional dictionary defaults, and formatting.
   • check_algorithms.py: Validates variable lifecycle (Let vs. Set), branch scope leaks, unused variables, list iteration syntax, and markup rules.
   • check_wpt_coverage.py: Audits modified specification sinks and thrown DOMExceptions against Web Platform Tests (WPT).
3. Review Checklists: Covers Web IDL, Infra data structures, tree construction & Adoption Agency Algorithm edge cases, cross-spec companion PR contracts, and PR scope discipline.

Usage with Gemini CLI

This repository is optimized for use with the Gemini CLI.

1. As Agent Skills (Recommended)

Link the skills so Gemini can activate them on-demand:

# From within the repository directory
for s in skills/*/; do gemini skills link "$s"; done

Gemini will automatically discover the skills based on the description in each SKILL.md and use the activate_skill tool when relevant to your requests.

2. Manual Context Injection

You can inject a skill into any specific prompt using the @ command:

gemini "Analyze this fragment: https://html.spec.whatwg.org/#main-fetch @skills/web-archeologist/SKILL.md"

3. Persistent Workspace Context

To make a skill available across your entire workspace, import it into your GEMINI.md file:

# My Project Context
...
@/path/to/web-archeologist/skills/web-archeologist/SKILL.md
@/path/to/web-archeologist/skills/html-spec-review/SKILL.md

Usage with Claude Code

Symlink the skill directories into your skills directory, so that edits in this checkout take effect immediately:

# From within the web-archeologist directory
mkdir -p ~/.claude/skills
for s in skills/*/; do ln -sfn "$PWD/$s" ~/.claude/skills/; done

Claude Code discovers the skills from the description in each SKILL.md and invokes them on demand; they can also be run explicitly as /web-archeologist and /html-spec-review. The skill list is built at session startup, so start a new session after linking.

Supported Standards & Engines

• Web Standards: HTML, CSS, DOM, Fetch, URL, etc.
• Chromium: Blink rendering engine (third_party/blink).
• WebKit: WebCore and JavaScriptCore.
• Mozilla: Gecko rendering engine.