CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

heading-hierarchy

Use when reviewing rendered HTML, interactive components, or design-system patterns related to Use logical heading hierarchy. Check native semantics first, then inspect keyboard behavior, focus flow, accessible names, and screen-reader output where relevant.

Quality

73%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/heading-hierarchy/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

63%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is well-organized with a clean Check/Fix/Explain/Code Review flow and exemplary progressive disclosure, delegating details to a real one-level-deep reference. Its weaknesses are redundancy — the single-h1/no-skipped-levels rule is restated across three sections — and actionability gaps where no concrete tool or command is named for generating a heading outline.

Suggestions

Merge the Quick Reference bullets into the Check section (or vice versa) so each fact appears once, cutting roughly a third of the body.

Name a concrete tool or command for the heading outline, e.g. "Run axe DevTools or Lighthouse's heading-structure audit" or a one-line DOM snippet like `document.querySelectorAll('h1,h2,h3,h4,h5,h6').map((el,i)=>`${' '.repeat(+el.tagName[1]-1)}${el.tagName} ${el.textContent.trim()}`)`.

Add an explicit verification step after Fix, e.g. "Regenerate the heading outline after restructuring to confirm exactly one h1 and no skipped levels."

DimensionReasoningScore

Conciseness

The body restates the same facts three times — Quick Reference's "Use exactly one h1 per page", Check's "Verify pages have exactly one h1, headings follow sequential order without skipping levels", and Fix's "Start with h1 for the page title" — plus an intro sentence repeating the screen-reader rationale. Mostly efficient with short sections, but the triple restatement is more than a minor trim, fitting anchor 3 rather than 4; not 2 because there is no padded explanation of concepts Claude already knows.

3 / 5

Actionability

The checks are directive ("Verify pages have exactly one h1, headings follow sequential order") but key details are missing: "Use accessibility tools to generate a heading outline" names no tool or command (e.g. axe, Lighthouse, a heading-outline snippet), and the Fix section gives structural direction without an example. This matches anchor 3's "some concrete guidance but incomplete"; not 4 because no executable command, tool, or code appears in the body.

3 / 5

Workflow Clarity

The Check → Fix → Explain → Code Review sections give a clear, well-ordered sequence for this simple single-task skill, and Code Review's "note how to verify the fix with browser accessibility tooling" hints at verification. Not 5 because no explicit re-check loop exists (e.g. "regenerate the heading outline after fixing to confirm"); not 3 because the sequence is coherent, well-sectioned, and verification is at least mentioned.

4 / 5

Progressive Disclosure

The body is a lean, well-sectioned overview that delegates detail via a clearly signaled, one-level-deep pointer: "For full implementation details, code examples, and framework-specific guidance, see `references/rule.md`" — and that file exists, is on-topic, and contains no further nested references. This matches anchor 5 exactly: clear overview with well-signaled one-level-deep references.

5 / 5

Total

15

/

20

Passed

Description

71%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description has an explicit "Use when..." trigger clause and lists several concrete inspection actions, but the actions are generic accessibility-review boilerplate misaligned with the heading-hierarchy domain, and the phrasing "related to Use logical heading hierarchy" reads as template substitution rather than natural trigger language. It is serviceable but would benefit from heading-specific capabilities and trigger terms.

Suggestions

Rewrite the 'what' to state heading-specific capabilities, e.g. "Verify each page has exactly one h1, that heading levels never skip (h1→h2→h3), and that headings describe their sections; generate a heading outline to audit structure".

Embed the rule name naturally instead of the awkward "related to Use logical heading hierarchy" — e.g. "Use when reviewing page headings, heading structure, or document outline for accessibility".

Add missing natural trigger terms such as "accessibility", "h1", and "heading levels" so users asking about heading structure or a11y audits match this skill rather than sibling accessibility skills.

DimensionReasoningScore

Specificity

The description lists several concrete actions — "Check native semantics first, then inspect keyboard behavior, focus flow, accessible names, and screen-reader output" — going beyond naming the domain. It falls short of 5 because none of the actions are heading-hierarchy-specific (no "verify a single h1", "check for skipped heading levels"), leaving a real coverage gap; it is above 3 because more than 1-2 specific actions are named.

4 / 5

Completeness

Both parts are explicit: the what ("Check native semantics first, then inspect keyboard behavior, focus flow, accessible names, and screen-reader output") and the when ("Use when reviewing rendered HTML, interactive components, or design-system patterns related to Use logical heading hierarchy"). Not 5 because the 'what' is generic inspection boilerplate rather than concrete capability statements, and the awkwardly embedded "related to Use logical heading hierarchy" weakens trigger precision; not 3 because both what and when are clearly present.

4 / 5

Trigger Term Quality

Natural terms users would say are present: "rendered HTML", "heading hierarchy", "screen-reader", "design-system patterns". A few common variations are missing ("accessibility", "h1", "heading levels", "document outline"), which fits anchor 4's "good keyword coverage; a few natural terms missing" rather than anchor 5's comprehensive synonym coverage.

4 / 5

Distinctiveness Conflict Risk

The template phrase "reviewing rendered HTML, interactive components, or design-system patterns" would equally match many sibling accessibility skills; only the embedded rule name "Use logical heading hierarchy" distinguishes it. This matches anchor 3 ("somewhat specific but could still overlap with similar skills") — not 4 because the shared boilerplate creates more than minor overlap within a rule family, and not 2 because the rule name does carve out a recognizable niche.

3 / 5

Total

15

/

20

Passed

Validation

93%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

metadata_version

'metadata.version' is missing

Warning

Total

15

/

16

Passed

Repository

thedaviddias/Front-End-Checklist

Path

skills/heading-hierarchy/SKILL.md

Reviewed

Table of Contents

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.