CtrlK
BlogDocsLog inGet started
Tessl Logo

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.

58

Quality

67%

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.

A compact, well-structured overview that points cleanly to a real one-level-deep reference file, but it under-uses that structure: three sections repeat the same rules, and the actionable specifics (tool names, verification commands) live only in the reference. De-duplicating the Check/Fix/Explain sections and naming at least one concrete verification tool in the body would raise both conciseness and actionability.

Suggestions

Merge the overlapping content of Quick Reference, Check, and Fix into a single check/fix section — the same three rules (one h1, no skipped levels, descriptive text) are currently stated three times in slightly different words.

Name a concrete verification tool in the Check section instead of 'accessibility tools' (e.g. 'Generate a heading outline with the HeadingsMap extension or browser DevTools, or navigate headings with the screen reader H key').

Fold the Explain section's rationale into the intro line (it is already nearly verbatim there) to save a section without losing content.

DimensionReasoningScore

Conciseness

The body is short but noticeably redundant: the Check section restates the Quick Reference bullets ('headings follow sequential order without skipping levels (h1 → h2 → h3)' vs 'Never skip heading levels (h1 → h2 → h3, not h1 → h3)'), and the Explain section restates the intro's table-of-contents rationale almost verbatim. Matches 'mostly efficient but includes some unnecessary explanation or could be tightened'. Not 4 because three sections carry substantially the same content; not 2 because there is no padding or explanation of concepts Claude already knows.

3 / 5

Actionability

Guidance is directionally concrete ('Verify pages have exactly one h1', 'headings follow sequential order without skipping levels') but stops short of executable specifics — 'Use accessibility tools to generate a heading outline' names no tool or command, while the concrete options (HeadingsMap extension, screen reader H key, DevTools) exist only in references/rule.md. Matches 'some concrete guidance but incomplete; missing key details'. Not 4 because the body's central instruction defers to unnamed tooling; not 2 because the checks themselves (one h1, sequential order, descriptive text) are specific and actionable.

3 / 5

Workflow Clarity

The Check → Fix → Explain → Code Review sequence is clear and unambiguous for a simple single-purpose review skill, and verification is addressed ('Use accessibility tools to generate a heading outline', 'note how to verify the fix with browser accessibility tooling'). Not 5 because there is no explicit validate-after-fix loop in the body and the role of 'Explain' vs 'Code Review' in the sequence is not sharply delineated; not 3 because the sequence is coherent with verification checkpoints mentioned in both Check and Code Review.

4 / 5

Progressive Disclosure

The body is a lean overview with well-organized sections and a clearly signaled one-level-deep reference: 'For full implementation details, code examples, and framework-specific guidance, see references/rule.md' — the file exists at references/rule.md and contains exactly that (code examples, framework-specific guidance, verification steps). Matches 'clear overview with well-signaled one-level-deep references; content appropriately split; easy navigation'. Not 4 because there are no organization gaps: no inline content that belongs in the reference, and the reference itself is not nested further.

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 and natural 'Use when...' trigger and several concrete actions, but the actions are generic accessibility-review boilerplate rather than heading-hierarchy specifics, creating overlap risk with sibling accessibility skills. Rewriting the what-clause around the actual rule (one h1, no skipped levels, descriptive heading text) would lift it substantially.

Suggestions

Replace the generic inspection list ('keyboard behavior, focus flow, accessible names') with heading-specific actions, e.g. 'Verify pages have exactly one h1, no skipped heading levels, and descriptive heading text; generate a heading outline with browser tooling.'

Add natural trigger synonyms users would say: 'headings', 'heading structure', 'h1', 'skipped heading levels', 'screen reader navigation'.

Restructure so the rule name ('Use logical heading hierarchy') reads as a capability statement rather than being embedded awkwardly inside the 'when' clause.

DimensionReasoningScore

Specificity

The description lists several concrete actions — "Check native semantics first, then inspect keyboard behavior, focus flow, accessible names, and screen-reader output" — which matches the 'lists several specific actions; minor gaps in coverage' anchor. Not 5 because the actions are generic accessibility-review boilerplate and never state the heading-specific checks (one h1, no skipped levels); not 3 because multiple distinct, concrete inspection actions are explicitly named.

4 / 5

Completeness

Both parts are present: an explicit trigger clause ("Use when reviewing rendered HTML, interactive components, or design-system patterns related to...") and a what ("Check native semantics first, then inspect keyboard behavior, focus flow, accessible names, and screen-reader output"). Not 5 because the 'what' describes generic accessibility inspection rather than concretely answering what the skill does for heading hierarchy, and the awkwardly embedded rule name weakens explicitness; not 3 because both what and when are explicitly stated.

4 / 5

Trigger Term Quality

Triggers like "reviewing rendered HTML", "interactive components", "design-system patterns", and "Use logical heading hierarchy" give good keyword coverage a user would plausibly say. Not 5 because common natural variations are missing ("headings", "h1", "skipped heading levels", "accessibility"); not 3 because coverage goes beyond a single keyword with multiple relevant trigger phrases.

4 / 5

Distinctiveness Conflict Risk

The heading-hierarchy niche is named, but the boilerplate about "keyboard behavior, focus flow, accessible names, and screen-reader output" would equally trigger any other accessibility skill (alt text, ARIA, focus order), so it could overlap with similar skills. Not 4 because the overlap is more than minor — the generic inspection list dominates the description; not 2 because the heading-hierarchy scoping 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
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.