HADS Documentation Format

HADS Claude Skill

by wshobson · MIT license · ★ 39,857 on GitHub · updated Sep 21

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.

---
name: hads
description: 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.
---

# 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.

---

Overview

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.

Manual install (npx, ZIP)

Claude Codenpx skills add wshobson/agents --skill hads -g -a claude-code

Claude Code (manual)

mkdir -p ~/.claude/skills && curl -sL https://codeload.github.com/wshobson/agents/tar.gz/4236bb91f839 \
  | tar -xz -C ~/.claude/skills --strip-components=4 agents-4236bb91f839/plugins/documentation-standards/skills/hads

Windows (PowerShell)

New-Item -ItemType Directory -Force "$HOME\.claude\skills" | Out-Null; Invoke-WebRequest "https://m.agentalley.io/zip/dde86cdcd09a4d80d843/hads.zip" -OutFile "$env:TEMP\hads.zip"; Expand-Archive "$env:TEMP\hads.zip" -DestinationPath "$HOME\.claude\skills" -Force

Claude.ai / desktopDownload the ZIP and upload it under Settings → Capabilities → Skills.

Codex, Cursor, other agentsPoint them at SKILL.md. The other files are plain text.

Connects with Agent Alley MCP · agentalley.io/mcp

Files included

SKILL.md6.0 KB

Read the files here

wshobson/4236bb91 file

SKILL.md6.0 KB

SKILL.md

Show the full text190 lines

hads/SKILL.md190 lines · 6.0 KB

PreviewCode

Outline

RawView on GitHub

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]

**[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.Z** in 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.Z** in 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.

1	---
2	name: hads
3	description: 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.
4	---
5
6	# HADS Claude Skill
7	Version 1.0.0 · Human-AI Document Standard · 2026 · HADS 1.0.0
8
9	---
10
11	## AI READING INSTRUCTION
12
13	This skill teaches Claude how to read, generate, and validate HADS documents.
14	Read all `[SPEC]` blocks before responding to any HADS-related request.
15	Read `[NOTE]` blocks if you need context on intent or edge cases.
16
17	---
18
19	## 1. WHAT IS HADS
20
21	[SPEC]
22	- HADS = Human-AI Document Standard
23	- Convention for Markdown technical documentation
24	- Four block types: `[SPEC]`, `[NOTE]`, `[BUG]`, `[?]`
25	- Every HADS document requires: H1 title, version declaration, AI manifest
26	- AI manifest appears before first content section, tells AI what to read/skip
27	- File extension: `.md` — standard Markdown, no tooling required
28
29	---
30
31	## 2. BLOCK TYPES
32
33	[SPEC]
34	```
35	[SPEC] Authoritative fact. Terse. Bullet lists, tables, code. AI reads always.
36	[NOTE] Human context, history, examples. AI may skip.
37	[BUG] Verified failure + fix. Required fields: symptom, cause, fix. Always read.
38	[?] Unverified / inferred. Lower confidence. Always flagged.
39	```
40
41	Block tag rules:
42	- Bold, on its own line: `[SPEC]`
43	- Content follows immediately (no blank line between tag and content)
44	- Multiple blocks of different types allowed per section
45	- Titled BUG blocks allowed: `[BUG] Short description`
46	- No nesting of blocks inside blocks
47
48	---
49
50	## 3. REQUIRED DOCUMENT STRUCTURE
51
52	[SPEC]
53	```markdown
54	# Document Title
55	Version X.Y.Z · Author · Date · [metadata]
56
57	---
58
59	## AI READING INSTRUCTION
60
61	Read `[SPEC]` and `[BUG]` blocks for authoritative facts.
62	Read `[NOTE]` only if additional context is needed.
63	`[?]` blocks are unverified — treat with lower confidence.
64
65	---
66
67	## 1. First Section
68
69	[SPEC]
70	...
71	```
72
73	Required elements in order:
74	1. H1 title
75	2. `Version X.Y.Z` in header (first 20 lines)
76	3. AI manifest section before first content section
77	4. Content sections (H2), subsections (H3)
78
79	---
80
81	## 4. HOW CLAUDE READS HADS
82
83	[SPEC]
84	When encountering a HADS document:
85	1. Find and read the AI manifest first
86	2. Read all `[SPEC]` blocks — these are ground truth
87	3. Read all `[BUG]` blocks — always, before generating any code or config
88	4. Read `[NOTE]` blocks only if `[SPEC]` is insufficient to answer the query
89	5. Treat `[?]` content as hypothesis — note uncertainty in response
90
91	Token optimization: for large documents, scan section headings first, then read only `[SPEC]` and `[BUG]` blocks in relevant sections.
92
93	---
94
95	## 5. HOW CLAUDE GENERATES HADS
96
97	[SPEC]
98	When asked to write documentation in HADS format:
99
100	1. Start with header block (title, version, metadata)
101	2. Add AI manifest — always include, never skip
102	3. Organize content into numbered H2 sections
103	4. For each fact: write as `[SPEC]` — terse, bullet or table or code
104	5. For each "why" or context: write as `[NOTE]`
105	6. For each known failure mode with confirmed fix: write as `[BUG]`
106	7. For each unverified claim: write as `[?]`
107	8. End with changelog section
108
109	Content rules for `[SPEC]`:
110	- Prefer bullet lists over prose
111	- Prefer tables for multi-field facts
112	- Prefer code blocks for syntax, formats, examples
113	- Maximum 2 sentences of prose — if more needed, move to `[NOTE]`
114
115	Content rules for `[BUG]`:
116	- Always include: symptom, cause, fix
117	- Optional: affected versions, workaround
118	- Title on same line: `[BUG] Short description`
119
120	[NOTE]
121	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.
122
123	---
124
125	## 6. VALIDATION RULES
126
127	[SPEC]
128	A valid HADS document must have:
129	- H1 title
130	- `Version X.Y.Z` in first 20 lines
131	- AI manifest before first content section
132	- All block tags bold: `[SPEC]` not `[SPEC]` not [SPEC]
133	- `[BUG]` blocks contain at minimum symptom + fix
134
135	Validator: (planned — not yet included in this release)
136
137	---
138
139	## 7. EXAMPLE INTERACTIONS
140
141	[SPEC]
142
143	User: "Write HADS documentation for this REST API"
144	→ Generate full HADS document: header, manifest, sections with [SPEC]/[NOTE]/[BUG] blocks
145
146	User: "Convert this README to HADS format"
147	→ Restructure existing content into HADS blocks, preserve all facts, add manifest
148
149	User: "Is this document valid HADS?"
150	→ Check: H1 title, version, manifest, block tag formatting, BUG block completeness
151
152	User: "Summarize this HADS document"
153	→ Read only [SPEC] and [BUG] blocks, return structured summary
154
155	User: "What does this API do?" (HADS doc provided)
156	→ Read manifest, read [SPEC] blocks in relevant sections, answer directly
157
158	---
159
160	## 8. DESIGN INTENT
161
162	[NOTE]
163	HADS exists because AI models increasingly read documentation before humans do. The format optimizes for this reality without sacrificing human readability.
164
165	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.
166
167	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.
168
169	---
170
171	## 9. QUICK REFERENCE
172
173	[SPEC]
174	```
175	Tag \| Bold format \| Reader \| Required content
176	----------\|----------------\|---------\|------------------
177	[SPEC] \| [SPEC] \| AI \| Facts, terse
178	[NOTE] \| [NOTE] \| Human \| Context, narrative
179	[BUG] \| [BUG] ... \| Both \| Symptom + fix
180	[?] \| [?] \| Both \| Unverified claims
181	```
182
183	Manifest minimum:
184	```markdown
185	## AI READING INSTRUCTION
186	Read `[SPEC]` and `[BUG]` blocks for authoritative facts.
187	Read `[NOTE]` only if additional context is needed.
188	`[?]` blocks are unverified.
189	```
190