Agent skill · writing content · wshobson
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.
Why this skill is useful
Provides specific guidelines and validation rules for creating HADS documents that optimize AI readability and token efficiency, which the AI wouldn't generate reliably on its own.
What it needs
About 4k tokens when loaded. Last updated 2026-08-05. 38,570 stars on the source repository.
What this skill does
HADS Claude Skill Version 1.0.0 · Human-AI Document Standard · 2026 · HADS 1.0.0 --- AI READING INSTRUCTION This skill teaches Claude how to read, generate, and validate HADS documents. Read all [SPEC] blocks before responding to any HADS-related request. Read [NOTE] blocks if you need context on intent or edge cases. --- 1. WHAT IS HADS [SPEC] HADS = Human-AI Document Standard Convention for Markdown technical documentation Four block types: [SPEC], [NOTE], [BUG], [?] Every HADS document requires: H1 title, version declaration, AI manifest AI manifest appears before first content section, tells AI what to read/skip File extension: .md — standard Markdown, no tooling required --- 2. BLOCK TYPES [SPEC] Block tag rules: Bold, on its own line: [SPEC] Content follows immediately (no blank line between tag and content) Multiple blocks of different types allowed per section Titled BUG blocks allowed: [BUG] Short description No nesting of blocks inside blocks --- 3. REQUIRED DOCUMENT STRUCTURE [SPEC] Required elements in order: 1. H1 title 2. Version X.Y.Z in header (first 20 lines) 3. AI manifest section before first content section 4. Content sections (H2), subsections (H3) --- 4. HOW CLAUDE READS HADS [SPEC] When encountering a HADS document: 1. Find and read the AI manifest first 2. Read all [SPEC] blocks — these are ground truth 3. Read all [BUG] blocks — always, before generating any code or config 4. Read [NOTE] blocks only if [SPEC] is insufficient to answer the query 5. Treat [?] content as hypothesis — note uncertainty in response Token optimization: for large documents, scan section headings first, then read only [SPEC] and [BUG] blocks in relevant sections. --- 5. HOW CLAUDE GENERATES HADS [SPEC] When asked to write documentation in HADS format: 1. Start with header block (title, version, metadata) 2. Add AI manifest — always include, never skip 3. Organize content into numbered H2 sections 4. For each fact: write as [SPEC] — terse, bullet or table or code 5. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills wshobson/hads