Hads Skill for Claude
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.
Install
one command, takes just this skill from the repositorynpx skills add https://github.com/wshobson/agents --skill hadsThe instruction itself
11 sections, as written by the authorHADS 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]
**[SPEC]** Authoritative fact. Terse. Bullet lists, tables, code. AI reads always.
**[NOTE]** Human context, history, examples. AI may skip.
**[BUG]** Verified failure + fix. Required fields: symptom, cause, fix. Always read.
**[?]** Unverified / inferred. Lower confidence. Always flagged.
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]
# Document Title
**Version X.Y.Z** · Author · Date · [metadata]
---
## AI READING INSTRUCTION
Read `[SPEC]` and `[BUG]` blocks for authoritative facts.
Read `[NOTE]` only if additional context is needed.
`[?]` blocks are unverified — treat with lower confidence.
---
## 1. First Section
**[SPEC]**
...
Required elements in order:
- H1 title
Version X.Y.Zin header (first 20 lines)- AI manifest section before first content section
- Content sections (H2), subsections (H3)
4. HOW CLAUDE READS HADS
[SPEC]
When encountering a HADS document:
- Find and read the AI manifest first
- Read all
[SPEC]blocks — these are ground truth - Read all
[BUG]blocks — always, before generating any code or config - Read
[NOTE]blocks only if[SPEC]is insufficient to answer the query - 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:
- Start with header block (title, version, metadata)
- Add AI manifest — always include, never skip
- Organize content into numbered H2 sections
- For each fact: write as
[SPEC]— terse, bullet or table or code - For each "why" or context: write as
[NOTE] - For each known failure mode with confirmed fix: write as
[BUG] - For each unverified claim: write as
[?] - End with changelog section
Content rules for [SPEC]:
- Prefer bullet lists over prose
- Prefer tables for multi-field facts
- Prefer code blocks for syntax, formats, examples
- Maximum 2 sentences of prose — if more needed, move to
[NOTE]
Content rules for [BUG]:
- Always include: symptom, cause, fix
- Optional: affected versions, workaround
- Title on same line:
[BUG] Short description
[NOTE]
When converting existing documentation to HADS: extract facts into [SPEC], move narrative and history to [NOTE], surface all known issues as [BUG]. Do not duplicate content between block types.
6. VALIDATION RULES
[SPEC]
A valid HADS document must have:
- H1 title
Version X.Y.Zin first 20 lines- AI manifest before first content section
- All block tags bold:
[SPEC]not[SPEC]not *[SPEC]* [BUG]blocks contain at minimum symptom + fix
Validator: *(planned — not yet included in this release)*
7. EXAMPLE INTERACTIONS
[SPEC]
User: *"Write HADS documentation for this REST API"*
→ Generate full HADS document: header, manifest, sections with [SPEC]/[NOTE]/[BUG] blocks
User: *"Convert this README to HADS format"*
→ Restructure existing content into HADS blocks, preserve all facts, add manifest
User: *"Is this document valid HADS?"*
→ Check: H1 title, version, manifest, block tag formatting, BUG block completeness
User: *"Summarize this HADS document"*
→ Read only [SPEC] and [BUG] blocks, return structured summary
User: *"What does this API do?"* (HADS doc provided)
→ Read manifest, read [SPEC] blocks in relevant sections, answer directly
8. DESIGN INTENT
[NOTE]
HADS exists because AI models increasingly read documentation before humans do. The format optimizes for this reality without sacrificing human readability.
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.
When generating HADS, think of [SPEC] as the API surface and [NOTE] as the comments. [BUG] blocks are the most valuable content — they represent hard-won knowledge that saves others from hitting the same wall.
9. QUICK REFERENCE
[SPEC]
Tag | Bold format | Reader | Required content
----------|----------------|---------|------------------
[SPEC] | **[SPEC]** | AI | Facts, terse
[NOTE] | **[NOTE]** | Human | Context, narrative
[BUG] | **[BUG] ...** | Both | Symptom + fix
[?] | **[?]** | Both | Unverified claims
Manifest minimum:
## AI READING INSTRUCTION
Read `[SPEC]` and `[BUG]` blocks for authoritative facts.
Read `[NOTE]` only if additional context is needed.
`[?]` blocks are unverified.
Other skills for the same job
different authors, same section of the catalogue
Convert Markdown files to HTML similar to `marked.js`, `pandoc`, `gomarkdown/markdown`, or similar tools; or writing custom script to convert markdown to html and/or working on web template systems like `jekyll/jekyll`, `gohugoio/hugo`, or similar web templating systems that utilize markdown documents, converting them to html. Use when asked to "convert markdown to html", "transform md to html", "render markdown", "generate html from markdown", or when working with .md files and/or web a templating system that converts markdown to HTML output. Supports CLI and Node.js workflows with GFM, CommonMark, and standard Markdown flavors.
Write and maintain technical documentation. Trigger with "write docs for", "document this", "create a README", "write a runbook", "onboarding guide", or when the user needs help with any form of technical writing — API docs, architecture docs, or operational runbooks.
Translate visa application documents (images) to English and create a bilingual PDF with original and translation
Write, review, and edit documentation files with consistent structure, tone, and technical accuracy. Use when creating docs, reviewing markdown files, writing READMEs, updating `/docs` directories, or when user says "write documentation", "review this doc", "improve this README", "create a guide", or "edit markdown". Do NOT use for code comments, inline JSDoc, or API reference generation.
Real-time Constitution compliance checker for devflow documents. Blocks partial implementations and hardcoded secrets during file editing.
Write self-documenting code with minimal, evergreen comments that explain complex logic without describing recent changes or temporary fixes. Use this skill when writing code comments, documentation strings, explaining complex algorithms, clarifying business logic, or deciding whether code needs comments. Apply when working with any source code files where comments or documentation might be added, ensuring comments remain relevant, helpful, and focused on explaining why rather than what the code does, while preferring clear code structure and naming over excessive commenting.
Draft a structured investment committee memo for PE deal approval. Synthesizes due diligence findings, financial analysis, and deal terms into a professional IC-ready document. Use when preparing for investment committee, writing up a deal, or creating a formal recommendation. Triggers on "write IC memo", "investment committee memo", "deal write-up", "prepare IC materials", or "recommendation memo".
Create or update an operational runbook for a recurring task or procedure. Use when documenting a task that on-call or ops needs to run repeatably, turning tribal knowledge into exact step-by-step commands, adding troubleshooting and rollback steps to an existing procedure, or writing escalation paths for when things go wrong.
How to use it
Take wshobson/hads from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.