Build a Repository of AI Agent Skills That Review Website Quality

## Split the repository into one skill per web quality topic Treat the repository as a collection of self-contained agent capabilities rather than one monolithic instruction file. Separate broad audits from focused skills for performance, accessibility, discoverability, general quality, and user-experience metrics so an agent can load only the capability needed for the task. Keep repository-level documentation, contribution rules, licensing, and agent guidance at the root. Each skill directory owns its main instruction file, automation scripts, and detailed references. Do not hide user-facing guidance, executable helpers, or source material in unrelated directories. Before changing a skill, identify its activation contract, owned files, dependencies, validation path, and relationship to other skills. ## Name skill folders and files, and fill in the SKILL.md header Give every skill a `SKILL.md` file with valid YAML frontmatter containing: - a kebab-case `name`; - a one-sentence `description` that states when to use the skill and includes realistic trigger phrases; - license metadata when required; - stable author and version metadata when the repository tracks them. Use exact naming conventions consistently: - skill directories use kebab-case; - the main instruction file is exactly `SKILL.md`; - script filenames use kebab-case and an appropriate executable extension; - reference filenames use the repository's documented uppercase convention. Keep the package self-contained and ensure every path mentioned by the skill resolves inside the supported repository layout. ## Keep SKILL.md under 500 lines and move details to reference files Keep the main skill under 500 lines. Put activation, the core workflow, critical constraints, and navigation in `SKILL.md`; move detailed explanations, large examples, and specialist material into references. Write specific, executable guidance. Each guideline should have a short title, a direct instruction, and any value or threshold needed to apply it. Prefer instructions that explain what to inspect, what decision to make, and what evidence proves completion. Use scripts for deterministic or repetitive work when their output would otherwise consume reasoning context. Do not duplicate the same procedure across the main skill and multiple references. ## Show before-and-after code and tables of good and poor thresholds Show the problem and the corrected pattern whenever a guideline governs executable behavior. Keep examples small enough to understand in isolation and verify that they actually work. For example, an image-stability guideline should contrast an underspecified image with one that declares dimensions and useful loading metadata: Problem: an image element with only `src="hero.jpg"`. Improved: the same element with `width="1200"`, `height="600"`, `alt="Hero image"`, and `loading="lazy"`. Present comparable quality thresholds in a table with explicit good, intermediate, and poor ranges. State the unit and boundary operators so readers do not have to infer whether a limit is inclusive. ## Write shell scripts that stop on errors and print results as JSON Shell helpers must be fail-fast, machine-readable, and safe to clean up: - declare the intended shell with a shebang; - enable fail-fast behavior such as `set -e`; - send progress and status messages to standard error; - send machine-readable results, such as JSON, to standard output; - create temporary files safely and register cleanup traps; - remain self-contained or document every external dependency and prerequisite. Keep human diagnostics out of the machine-readable stream. Exercise success, failure, malformed-input, and cleanup behavior before treating a helper as reusable automation. ## Keep each reference file on one topic and link it from the skill Give each reference one focused topic, practical examples, and links back to authoritative material. Keep individual references under 200 lines when possible so an agent can load them independently without pulling unrelated context. Link every reference from the main skill or a maintained index. Remove stale links and duplicated guidance, and keep the closest authoritative source as the owner of mutable facts. Use references for depth, not as a dumping ground. A reference should help the agent make or execute a distinct decision. ## Check the header, examples, links, and scripts before publishing a skill Before submitting or publishing a skill: 1. Parse and validate the YAML frontmatter. 2. Confirm the description contains usable activation triggers. 3. Run or otherwise verify every executable example. 4. Confirm that every referenced file exists and every internal link resolves. 5. Exercise scripts through their documented interface and verify output-channel behavior. 6. Validate the package against the governing agent-skill specification. Treat a successful syntax check as necessary but insufficient. The activation description, examples, references, and scripts must agree with the behavior the skill promises. ## Rank issues from critical to low and keep advice independent of frameworks Rank findings consistently: 1. **Critical:** security vulnerabilities or complete functional failure. 2. **High:** severe performance failures or major accessibility barriers. 3. **Medium:** meaningful performance, discoverability, or search-quality opportunities. 4. **Low:** code style and minor optimization opportunities. Keep web guidance framework-neutral. Show standard HTML, CSS, and JavaScript first, place framework-specific notes in separate sections, and prefer standard platform APIs unless a framework dependency is essential to the task. Review the highest-impact correctness and access barriers before spending effort on stylistic improvements. ## Update a skill without breaking the phrases that trigger it Preserve backward compatibility when updating skill descriptions and keep established trigger phrases working. Update version metadata with the implementation and document breaking changes in the repository's required change record or commit description. When structure changes, update the main skill, affected references, scripts, examples, and links together. Review the final diff for accidental scope expansion, stale generated material, and duplicated instructions. Rerun the focused validation checklist after every behavioral change. Do not claim an updated skill is ready while its activation path, examples, or referenced assets remain unverified.