hads

Use when writing technical documentation that needs to be readable by both humans and AI models, converting existing docs to HADS format, validating a HADS document, or optimizing documentation for token-efficient AI consumption.

Quality

79%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./plugins/documentation-standards/skills/hads/SKILL.md

Quality

Content

75%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 well-structured, mostly lean instruction skill that teaches a custom documentation standard through concrete tag formats, templates, and sequenced read/generate workflows. The main gaps are the not-yet-included validator and the absence of an explicit validation checkpoint inside the generation workflow.

Suggestions

Add an explicit 'validate the generated document' step at the end of the Section 5 generation workflow that references the Section 6 checklist, creating a generate -> validate -> fix -> re-validate feedback loop.

Either ship a validation script in ./scripts/ (and reference it) or remove the 'Validator: planned' line to avoid promising tooling that is absent from the bundle.

Tighten the Section 8 DESIGN INTENT NOTE to bullet form so it matches the conciseness of the SPEC blocks elsewhere.

Dimension	Reasoning	Score
Conciseness	The body is lean, relying on terse SPEC blocks, bullets, tables, and code fences, and avoids explaining general concepts Claude already knows; minor over-explanation in the NOTE 'DESIGN INTENT' section ('HADS exists because AI models increasingly read documentation before humans do') could be trimmed, placing it just below the fully lean anchor-5.	4 / 5
Actionability	Gives concrete, executable guidance — exact tag formats like '[SPEC]', a full required-structure markdown template, ordered generation steps, and a validation checklist — but the validator is explicitly 'planned — not yet included', leaving a minor gap versus copy-paste-ready completeness.	4 / 5
Workflow Clarity	Both the reading (5-step) and generation (8-step) workflows are clearly numbered and sequenced, and validation rules are enumerated; the generation flow lacks an explicit 'validate the output' checkpoint wired into the steps, a minor validation gap that keeps it below anchor-5 rather than triggering the destructive/batch cap of 3 since doc generation is not inherently destructive.	4 / 5
Progressive Disclosure	No bundle files exist (references/scripts/assets absent) and the single ~185-line SKILL.md is well-organized into nine numbered sections with a quick reference, so content is appropriately placed with clear navigation; it exceeds the under-50-line simple-skill exception and has no external references to signal, sitting just below anchor-5.	4 / 5
	Total	16 / 20 Passed

Description

83%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.

A strong, third-person description with an explicit 'Use when' trigger and four concrete capabilities anchored on the distinctive HADS term. It is comprehensive on completeness and distinctiveness, with only minor wording tightness and a few missing synonyms keeping specificity and trigger quality just off the top anchor.

Dimension	Reasoning	Score
Specificity	Lists several concrete actions — 'writing technical documentation that needs to be readable by both humans and AI models', 'converting existing docs to HADS format', 'validating a HADS document', 'optimizing documentation for token-efficient AI consumption' — covering the skill's main tasks with only minor gaps; the first clause is slightly wordy relative to the terse anchor-5 examples, so it sits just below comprehensive.	4 / 5
Completeness	Opens with an explicit 'Use when' trigger clause enumerating four concrete scenarios, and the same clauses state what the skill does, clearly answering both what and when with concrete trigger phrases as in the anchor-5 example.	5 / 5
Trigger Term Quality	Includes natural phrases users would say ('technical documentation', 'converting existing docs', 'validating a HADS document') plus the distinctive 'HADS' term, but 'optimizing documentation for token-efficient AI consumption' leans technical and a few common synonyms are missing.	4 / 5
Distinctiveness Conflict Risk	The 'HADS format' identifier gives it a clear niche with distinct triggers and minimal conflict risk, but 'writing technical documentation that needs to be readable by both humans and AI models' is broad enough to overlap slightly with general documentation skills.	4 / 5
	Total	17 / 20 Passed

Validation

100%

Warnings & errors only

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

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: wshobson/agents
Path: plugins/documentation-standards/skills/hads/SKILL.md
Commit: 4236bb9

Reviewed: 6 days ago

Table of Contents

Discovery Implementation Validation

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.