Content
82%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.
A strong, expert-level engineering skill: nearly every rule is stated with its concrete failure mode, exact API, or executable snippet, and the nine-step workflow is clearly sequenced with a real verification section. The main gaps are modest: a little re-explanation of platform basics Claude already knows, no explicit error-recovery loop after verification, and a monolithic structure that could offload framework-interop detail to reference files.
Suggestions
Trim passages that restate platform fundamentals Claude already knows (e.g., 'call super() first', the naming-convention table, slot-assignment basics) and keep only the project-specific or failure-mode-driven rules.
Add an explicit feedback loop to the Verify section: what to do when type check, lint, or the browser test fails (fix without auto-fix modes, re-run, and only then proceed), so error recovery is not left implicit.
Consider moving the per-framework consumer details (React 18/19, Vue, Angular, Svelte 5) into a references/ file with a clear pointer from section 7, keeping SKILL.md as a leaner overview.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with non-obvious, failure-mode-driven guidance (upgrade-order constructor bugs, per-connection AbortController, own-property shadowing before definition, `:host-context()` removal) and mostly avoids padding, matching the efficient score-4 anchor. It falls short of 5 because some passages re-state platform fundamentals Claude already knows — "call `super()` first", the kebab-case/PascalCase naming table, "Only the host's direct children are slotted" — which could be trimmed. | 4 / 5 |
Actionability | Guidance is fully concrete and executable throughout: copy-paste-ready snippets (`this.dispatchEvent(new CustomEvent('item-select', { bubbles: true, detail }))`, the `attachInternals().shadowRoot ?? this.attachShadow(...)` reuse, the `Object.hasOwn(this, name)` upgrade fix), exact API calls (`setFormValue(value, state)`, `toggleAttribute(name, Boolean(value))`, `internals.states`), and specific tools and checks (Web Test Runner, Playwright, webstatus.dev, eslint-plugin-wc). Per the code_vs_instruction note, this instruction-heavy skill meets the score-5 bar: specific examples cover the common cases. | 5 / 5 |
Workflow Clarity | The body is an explicitly numbered sequence in execution order (Learn the project → Design the contract → Implement → Shadow DOM → Accessibility → Forms/SSR → Framework consumers → Security → Verify) with a validation section that names checks and a coverage checklist (reinsertion, reflection of `false`, events outside the host, form reset, keyboard operation). It stops short of 5 because no fix-and-re-validate feedback loop is stated in the Verify step — validation outcomes are listed but error recovery is left implicit. | 4 / 5 |
Progressive Disclosure | With no bundle files present, the single ~110-line file is well organized: numbered sections, a contract-convention table, and clearly delineated domains, and the size is within single-file norms. It matches the good-structure score-4 anchor rather than 5 because there are no well-signaled one-level-deep references at all — sections like the per-framework interop details (section 7) are the kind of material that could be split into reference files — and the cross-skill pointers ("the css-engineering skill") are plain text rather than navigable links. | 4 / 5 |
Total | 17 / 20 Passed |