Content
77%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a strong, expert-level conversion playbook: fully sequenced with validation feedback loops, concrete commands and config blocks, and hard-won gotchas (var:type, data-lt, oldids) that Claude could not invent. Its main defects are a missing bundle script that the verification step depends on, some duplicated guidance, and no use of reference files for the bulky lookup tables.
Suggestions
Ship `check-anchors.py` with the skill (or move its usage into a `scripts/` file) so the step-7 verification command is actually runnable.
Move the step-6 common-issues table and the ReSpec id-pattern tables into a reference file (e.g. `references/gotchas.md`) and keep a short pointer in SKILL.md, reducing token load when the skill is loaded.
Deduplicate the |var:type| and example-id guidance, which appears in both step 3 and step 6/examples sections.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense operational detail that assumes Claude's competence — e.g. "Bikeshed does NOT support this — it renders the |var:type| text literally", the data-lt semantics difference, and the ReSpec id-pattern table — with no filler explaining what ReSpec or Bikeshed are. Not 5 because the |var:type| issue and example-id guidance are each explained twice (step 3 prose and the step 6 issue table / examples section), and a few table rows restate earlier bullet points. | 4 / 5 |
Actionability | Guidance is largely copy-paste ready: the exact spec-generator curl URL, `bikeshed -f spec`, complete `.pr-preview.json` and workflow YAML blocks, and BAD/GOOD HTML snippets. Not 5 because the critical verification step depends on `python3 <skill-dir>/check-anchors.py`, a script referenced as being in the skill's directory but absent from the bundle, so the shipped skill cannot actually run its own verification flow. | 4 / 5 |
Workflow Clarity | Seven clearly sequenced steps with explicit validation checkpoints and feedback loops: baseline sanity check (`grep -c '<dfn'` "must be more than 0"), iterative fix-until-clean ("fix ALL errors, warnings, and info messages... until the build produces ZERO output"), and verify-and-retry ("must end with OK. For every id or exported term it reports missing, fix index.bs... then rerun"), plus visual comparison and artifact cleanup. This matches the anchor-5 example's validate→fix→retry structure despite involving destructive steps (deleting index.html). | 5 / 5 |
Progressive Disclosure | Section structure is clear (numbered steps, labeled subsections), but the bundle contains no reference files at all while the body twice references `check-anchors.py` "in this skill's directory" — a broken reference — and ~100 lines of lookup material (the issue/fix table, id-pattern tables, and element-conversion rules) are inlined in SKILL.md where a reference file would keep the working overview lean. Above anchor 2 because structure and signaling are present; below anchor 4 because the one reference used is not actually shipped. | 3 / 5 |
Total | 16 / 20 Passed |