{"slug":"hads","title":"hads","summary":"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.","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-09-01T18:59:25.571581Z","repo":{"url":"https://github.com/wshobson/agents","stars":40003,"forks":4267,"license":"MIT","updatedAt":"2026-09-26T19:54:17Z"},"bodyHtml":"<hr>\n<h2>name: hads\ndescription: 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.</h2>\n<h1>HADS Claude Skill</h1>\n<p><strong>Version 1.0.0</strong> · Human-AI Document Standard · 2026 · HADS 1.0.0</p>\n<hr>\n<h2>AI READING INSTRUCTION</h2>\n<p>This skill teaches Claude how to read, generate, and validate HADS documents.\nRead all <code>[SPEC]</code> blocks before responding to any HADS-related request.\nRead <code>[NOTE]</code> blocks if you need context on intent or edge cases.</p>\n<hr>\n<h2>1. WHAT IS HADS</h2>\n<p><strong>[SPEC]</strong></p>\n<ul>\n<li>HADS = Human-AI Document Standard</li>\n<li>Convention for Markdown technical documentation</li>\n<li>Four block types: <code>**[SPEC]**</code>, <code>**[NOTE]**</code>, <code>**[BUG]**</code>, <code>**[?]**</code></li>\n<li>Every HADS document requires: H1 title, version declaration, AI manifest</li>\n<li>AI manifest appears before first content section, tells AI what to read/skip</li>\n<li>File extension: <code>.md</code> — standard Markdown, no tooling required</li>\n</ul>\n<hr>\n<h2>2. BLOCK TYPES</h2>\n<p><strong>[SPEC]</strong></p>\n<pre><code>**[SPEC]**   Authoritative fact. Terse. Bullet lists, tables, code. AI reads always.\n**[NOTE]**   Human context, history, examples. AI may skip.\n**[BUG]**    Verified failure + fix. Required fields: symptom, cause, fix. Always read.\n**[?]**      Unverified / inferred. Lower confidence. Always flagged.\n</code></pre>\n<p>Block tag rules:</p>\n<ul>\n<li>Bold, on its own line: <code>**[SPEC]**</code></li>\n<li>Content follows immediately (no blank line between tag and content)</li>\n<li>Multiple blocks of different types allowed per section</li>\n<li>Titled BUG blocks allowed: <code>**[BUG] Short description**</code></li>\n<li>No nesting of blocks inside blocks</li>\n</ul>\n<hr>\n<h2>3. REQUIRED DOCUMENT STRUCTURE</h2>\n<p><strong>[SPEC]</strong></p>\n<pre><code># Document Title\n**Version X.Y.Z** · Author · Date · [metadata]\n\n---\n\n## AI READING INSTRUCTION\n\nRead `[SPEC]` and `[BUG]` blocks for authoritative facts.\nRead `[NOTE]` only if additional context is needed.\n`[?]` blocks are unverified — treat with lower confidence.\n\n---\n\n## 1. First Section\n\n**[SPEC]**\n...\n</code></pre>\n<p>Required elements in order:</p>\n<ol>\n<li>H1 title</li>\n<li><code>**Version X.Y.Z**</code> in header (first 20 lines)</li>\n<li>AI manifest section before first content section</li>\n<li>Content sections (H2), subsections (H3)</li>\n</ol>\n<hr>\n<h2>4. HOW CLAUDE READS HADS</h2>\n<p><strong>[SPEC]</strong>\nWhen encountering a HADS document:</p>\n<ol>\n<li>Find and read the AI manifest first</li>\n<li>Read all <code>[SPEC]</code> blocks — these are ground truth</li>\n<li>Read all <code>[BUG]</code> blocks — always, before generating any code or config</li>\n<li>Read <code>[NOTE]</code> blocks only if <code>[SPEC]</code> is insufficient to answer the query</li>\n<li>Treat <code>[?]</code> content as hypothesis — note uncertainty in response</li>\n</ol>\n<p>Token optimization: for large documents, scan section headings first, then read only <code>[SPEC]</code> and <code>[BUG]</code> blocks in relevant sections.</p>\n<hr>\n<h2>5. HOW CLAUDE GENERATES HADS</h2>\n<p><strong>[SPEC]</strong>\nWhen asked to write documentation in HADS format:</p>\n<ol>\n<li>Start with header block (title, version, metadata)</li>\n<li>Add AI manifest — always include, never skip</li>\n<li>Organize content into numbered H2 sections</li>\n<li>For each fact: write as <code>[SPEC]</code> — terse, bullet or table or code</li>\n<li>For each \"why\" or context: write as <code>[NOTE]</code></li>\n<li>For each known failure mode with confirmed fix: write as <code>[BUG]</code></li>\n<li>For each unverified claim: write as <code>[?]</code></li>\n<li>End with changelog section</li>\n</ol>\n<p>Content rules for <code>[SPEC]</code>:</p>\n<ul>\n<li>Prefer bullet lists over prose</li>\n<li>Prefer tables for multi-field facts</li>\n<li>Prefer code blocks for syntax, formats, examples</li>\n<li>Maximum 2 sentences of prose — if more needed, move to <code>[NOTE]</code></li>\n</ul>\n<p>Content rules for <code>[BUG]</code>:</p>\n<ul>\n<li>Always include: symptom, cause, fix</li>\n<li>Optional: affected versions, workaround</li>\n<li>Title on same line: <code>**[BUG] Short description**</code></li>\n</ul>\n<p><strong>[NOTE]</strong>\nWhen converting existing documentation to HADS: extract facts into <code>[SPEC]</code>, move narrative and history to <code>[NOTE]</code>, surface all known issues as <code>[BUG]</code>. Do not duplicate content between block types.</p>\n<hr>\n<h2>6. VALIDATION RULES</h2>\n<p><strong>[SPEC]</strong>\nA valid HADS document must have:</p>\n<ul>\n<li>H1 title</li>\n<li><code>**Version X.Y.Z**</code> in first 20 lines</li>\n<li>AI manifest before first content section</li>\n<li>All block tags bold: <code>**[SPEC]**</code> not <code>[SPEC]</code> not <em>[SPEC]</em></li>\n<li><code>[BUG]</code> blocks contain at minimum symptom + fix</li>\n</ul>\n<p>Validator: <em>(planned — not yet included in this release)</em></p>\n<hr>\n<h2>7. EXAMPLE INTERACTIONS</h2>\n<p><strong>[SPEC]</strong></p>\n<p>User: <em>\"Write HADS documentation for this REST API\"</em>\n→ Generate full HADS document: header, manifest, sections with [SPEC]/[NOTE]/[BUG] blocks</p>\n<p>User: <em>\"Convert this README to HADS format\"</em>\n→ Restructure existing content into HADS blocks, preserve all facts, add manifest</p>\n<p>User: <em>\"Is this document valid HADS?\"</em>\n→ Check: H1 title, version, manifest, block tag formatting, BUG block completeness</p>\n<p>User: <em>\"Summarize this HADS document\"</em>\n→ Read only [SPEC] and [BUG] blocks, return structured summary</p>\n<p>User: <em>\"What does this API do?\"</em> (HADS doc provided)\n→ Read manifest, read [SPEC] blocks in relevant sections, answer directly</p>\n<hr>\n<h2>8. DESIGN INTENT</h2>\n<p><strong>[NOTE]</strong>\nHADS exists because AI models increasingly read documentation before humans do. The format optimizes for this reality without sacrificing human readability.</p>\n<p>Key insight: the AI manifest is the core innovation. It lets even small (7B) models know what to read and what to skip — without requiring them to reason about document structure. Explicit is better than implicit for model consumption.</p>\n<p>When generating HADS, think of <code>[SPEC]</code> as the API surface and <code>[NOTE]</code> as the comments. <code>[BUG]</code> blocks are the most valuable content — they represent hard-won knowledge that saves others from hitting the same wall.</p>\n<hr>\n<h2>9. QUICK REFERENCE</h2>\n<p><strong>[SPEC]</strong></p>\n<pre><code>Tag       | Bold format    | Reader  | Required content\n----------|----------------|---------|------------------\n[SPEC]    | **[SPEC]**     | AI      | Facts, terse\n[NOTE]    | **[NOTE]**     | Human   | Context, narrative\n[BUG]     | **[BUG] ...**  | Both    | Symptom + fix\n[?]       | **[?]**        | Both    | Unverified claims\n</code></pre>\n<p>Manifest minimum:</p>\n<pre><code>## AI READING INSTRUCTION\nRead `[SPEC]` and `[BUG]` blocks for authoritative facts.\nRead `[NOTE]` only if additional context is needed.\n`[?]` blocks are unverified.\n</code></pre>\n","files":[{"path":"SKILL.md","sizeBytes":6104,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-01T18:59:53.294473Z","sha256":"5AC684033BA8DB6A000C5CF3786376C1AB157F5DD73539A9924F2D0C4168A817","sizeBytes":2631},"review":null,"source":{"repositoryUrl":"https://github.com/wshobson/agents","path":"plugins/documentation-standards/skills/hads","license":"MIT","commit":"9b15b34b0bfc13a815cbfc2366e14ea549e09422","subtreeSha":"363090672F4C2EE1F8D6AE5B49B4586418F7FC22EBBDF575D8A0689AF54CD5C7","lastSyncedAt":"2026-09-26T23:12:03.520842Z"},"reviewedAt":"2026-09-01T19:01:43.73438Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/wshobson/agents/tree/main/plugins/documentation-standards/skills/hads"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install wshobson-agents@llmmart"},{"target":"git","command":"git clone https://github.com/wshobson/agents.git"}]}