feat: improve bikeshed-conversion skill score 84% → 97%

skills/bikeshed-conversion/ID_PATTERNS.md

@@ -0,0 +1,12 @@
+# Common ID Patterns to Preserve
+
+Based on [w3c/hr-time#173](https://github.com/w3c/hr-time/pull/173), these are typical ID patterns that get lost during Bikeshed conversion:
+
+| Type | Pattern | Example |
+|------|---------|---------|
+| Concept definitions | `dfn-{name}` | `id=dfn-wall-clock`, `id=dfn-monotonic-clock`, `id=dfn-duration` |
+| Algorithm definitions | `dfn-{algorithm-name}` | `id=dfn-coarsen-time`, `id=dfn-duration-from` |
+| IDL typedefs | `dom-{typename}` | `id=dom-domhighrestimestamp`, `id=dom-epochtimestamp` |
+| IDL interfaces | `dom-{interface}` | `id=dom-performance` |
+| IDL blocks | `idl-def-{name}` | `id=idl-def-domhighrestimestamp` |
+| Compound concepts | `dfn-{hyphenated}` | `id=dfn-current-high-resolution-time`, `id=dfn-relative-high-resolution-coarse-time` |

skills/bikeshed-conversion/SKILL.md

@@ -1,69 +1,46 @@
 ---
 name: bikeshed-conversion
-description: Guidelines for converting W3C specs to Bikeshed format. Covers anchor ID preservation, dfn handling, and common pitfalls. Read this before any Bikeshed conversion or migration work.
+description: "Convert W3C ReSpec documents to Bikeshed (.bs) format — preserves anchor IDs, handles dfn elements and IDL attributes, resolves cross-spec references, and avoids common formatting pitfalls. Use when doing any respec-to-bikeshed migration, spec format conversion, or .bs markup work."
 ---
 
 # Bikeshed Conversion
 
 ## Preserving Anchor IDs
 
-When converting a spec to Bikeshed, **anchor IDs used by other specifications must be preserved**. Bikeshed auto-generates IDs for `<dfn>` elements based on their text content, but these auto-generated IDs often differ from the IDs that were in the original spec. Other specs link to these IDs, so changing them silently breaks cross-spec references.
+**Always preserve anchor IDs from the original spec.** Bikeshed auto-generates IDs for `<dfn>` elements that often differ from the originals, breaking cross-spec references.
 
-### The Problem
-
-Bikeshed generates IDs like `dfn-wall-clock` from `<dfn>wall clock</dfn>`, but the original spec may have used a different ID or no explicit ID (relying on the HTML spec's own ID generation). When other W3C specs reference anchors like `#dfn-wall-clock`, `#dom-performance`, or `#dfn-coarsen-time`, those links break if the IDs change.
-
-### The Fix
-
-Always add explicit `id` attributes to `<dfn>` elements to preserve the anchors other specs depend on:
+Add explicit `id` attributes to every `<dfn>`:
 
 ```html
-<!-- BAD: Bikeshed auto-generates an ID that may differ from the original -->
+<!-- BAD -->
 <dfn data-export>wall clock</dfn>
 
-<!-- GOOD: Explicit ID preserves the anchor -->
+<!-- GOOD -->
 <dfn data-export id=dfn-wall-clock>wall clock</dfn>
 ```
 
-### Common ID Patterns to Preserve
-
-Based on [w3c/hr-time#173](https://github.com/w3c/hr-time/pull/173), these are typical ID patterns that get lost:
+See [ID_PATTERNS.md](ID_PATTERNS.md) for the full table of ID naming conventions (`dfn-*`, `dom-*`, `idl-def-*`) based on [w3c/hr-time#173](https://github.com/w3c/hr-time/pull/173).
 
-| Type | Pattern | Example |
-|------|---------|---------|
-| Concept definitions | `dfn-{name}` | `id=dfn-wall-clock`, `id=dfn-monotonic-clock`, `id=dfn-duration` |
-| Algorithm definitions | `dfn-{algorithm-name}` | `id=dfn-coarsen-time`, `id=dfn-duration-from` |
-| IDL typedefs | `dom-{typename}` | `id=dom-domhighrestimestamp`, `id=dom-epochtimestamp` |
-| IDL interfaces | `dom-{interface}` | `id=dom-performance` |
-| IDL blocks | `idl-def-{name}` | `id=idl-def-domhighrestimestamp` |
-| Compound concepts | `dfn-{hyphenated}` | `id=dfn-current-high-resolution-time`, `id=dfn-relative-high-resolution-coarse-time` |
+## IDL Attribute Definitions
 
-### IDL Attribute Definitions
-
-When converting `<dfn>` elements inside a `<dl>` that describes IDL interface attributes, add the `attribute` keyword to each `<dfn>` so Bikeshed knows they define IDL attributes (not plain terms). The parent `<dl>` should have `dfn-for` set to the interface name.
+Add the `attribute` keyword to `<dfn>` elements inside IDL `<dl>` blocks so Bikeshed treats them as IDL attributes, not plain terms:
 
 ```html
-<!-- BAD: Bikeshed treats these as plain concept dfns -->
+<!-- BAD -->
 <dl dfn-for="PerformanceEntry" data-export>
   <dt><dfn>duration</dfn></dt>
-  <dd>...</dd>
 </dl>
 
-<!-- GOOD: Bikeshed knows these are IDL attributes -->
+<!-- GOOD -->
 <dl dfn-for="PerformanceEntry" data-export>
   <dt><dfn attribute>duration</dfn></dt>
-  <dd>...</dd>
 </dl>
 ```
 
-Without the `attribute` keyword, Bikeshed won't correctly associate the dfn with the IDL attribute, and cross-references like `{{PerformanceEntry/duration}}` may fail to resolve.
-
-### Checklist
-
-When converting a spec to Bikeshed:
+## Conversion Checklist
 
 1. **Inventory all `<dfn>` elements** in the original spec and note their IDs
 2. **Check for cross-spec references** — search other W3C specs that link to this spec's anchors (use [xref](https://respec.org/xref/) or grep the spec's URL in other repos)
-3. **Add explicit `id` attributes** to every `<dfn>` that had an ID in the original, matching the original ID exactly
-4. **Verify after conversion** — build the Bikeshed output and confirm all anchors from the original spec still resolve
-5. **Check `data-dfn-for` scoping** — Bikeshed uses `data-dfn-for` to scope definitions; make sure scoped dfns also retain their original IDs (e.g., `id="wall-clock-unsafe-current-time"` for `<dfn data-dfn-for="wall clock">unsafe current time</dfn>`)
+3. **Add explicit `id` attributes** to every `<dfn>`, matching the original ID exactly
+4. **Verify after conversion** — build with `bikeshed --die-on=warning` and confirm all anchors resolve. If anchors are missing, check for `Missing dfn` errors and compare generated IDs against originals
+5. **Check `data-dfn-for` scoping** — ensure scoped dfns retain their original IDs