AgentAlley

Skills · Content & docs

HADS Claude Skill

Unverified●30/40

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.

Originally by wshobson · MIT

Claude Code◐PartialHas SKILL.md but declares no allowed-tools — Claude Code will ask for permission each time
Cursor◐PartialPlain prose you can paste in — but no Cursor rules file
Codex◐PartialPlain prose you can paste in — but no AGENTS.md
Gemini CLI◐PartialPlain prose you can paste in
Copilot◐PartialPlain prose you can paste in — but no Copilot instructions file
npx agentalley add hads

This command does not work yet — the CLI is still being built. Until then, use Raw in the reader below to take the file.

Who is stuck, and on what

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.

The whole source

No sign-in, no blur, nothing truncated
hads/SKILL.md190 lines6.0 KBRawView on GitHub
Frontmatter — 2 properties
namehads
descriptionUse 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.
1---
2name: hads
3description: 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---A5 — No allowed-tools declared — no way to tell what this skill may touch
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 
13This skill teaches Claude how to read, generate, and validate HADS documents.
14Read all `[SPEC]` blocks before responding to any HADS-related request.
15Read `[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 
41Block 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 
61Read `[SPEC]` and `[BUG]` blocks for authoritative facts.
62Read `[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 
73Required elements in order:
741. H1 title
752. `**Version X.Y.Z**` in header (first 20 lines)
763. AI manifest section before first content section
774. Content sections (H2), subsections (H3)
78 
79---
80 
81## 4. HOW CLAUDE READS HADS
82 
83**[SPEC]**
84When encountering a HADS document:
851. Find and read the AI manifest first
862. Read all `[SPEC]` blocks — these are ground truth
873. Read all `[BUG]` blocks — always, before generating any code or config
884. Read `[NOTE]` blocks only if `[SPEC]` is insufficient to answer the query
895. Treat `[?]` content as hypothesis — note uncertainty in response
90 
91Token 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]**
98When asked to write documentation in HADS format:
99 
1001. Start with header block (title, version, metadata)
1012. Add AI manifest — always include, never skip
1023. Organize content into numbered H2 sections
1034. For each fact: write as `[SPEC]` — terse, bullet or table or code
1045. For each "why" or context: write as `[NOTE]`
1056. For each known failure mode with confirmed fix: write as `[BUG]`
1067. For each unverified claim: write as `[?]`
1078. End with changelog section
108 
109Content 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 
115Content 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]**
121When 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]**
128A 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 
135Validator: *(planned — not yet included in this release)*
136 
137---
138 
139## 7. EXAMPLE INTERACTIONS
140 
141**[SPEC]**
142 
143User: *"Write HADS documentation for this REST API"*
144→ Generate full HADS document: header, manifest, sections with [SPEC]/[NOTE]/[BUG] blocks
145 
146User: *"Convert this README to HADS format"*
147→ Restructure existing content into HADS blocks, preserve all facts, add manifest
148 
149User: *"Is this document valid HADS?"*
150→ Check: H1 title, version, manifest, block tag formatting, BUG block completeness
151 
152User: *"Summarize this HADS document"*
153→ Read only [SPEC] and [BUG] blocks, return structured summary
154 
155User: *"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]**
163HADS exists because AI models increasingly read documentation before humans do. The format optimizes for this reality without sacrificing human readability.
164 
165Key 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 
167When 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```
175Tag | 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 
183Manifest minimum:
184```markdown
185## AI READING INSTRUCTION
186Read `[SPEC]` and `[BUG]` blocks for authoritative facts.
187Read `[NOTE]` only if additional context is needed.
188`[?]` blocks are unverified.
189```
190 

Reviews

Installed this one?Write the first review and take the Trailblazer badge.

Reviews only open after a real install, so this is empty — and we leave it empty rather than invent one.

Alternatives

Also in Content & docs
Research Review via External Reviewer Backend (ultra reasoning)Get a deep critical review of research from an external reviewer backend (Codex or manual). Use when user says "review my research", "help me review", "get external review", or wants critical feedback on research ideas, papers, or experimental results.Content & docs · MIT●····●38/40Training CheckPeriodically check WandB metrics during training to catch problems early (NaN, loss divergence, idle GPUs). Avoids wasting GPU hours on broken runs. Use when training is running and you want automated health checks.Content & docs · MIT●····●37/40Changelog AutomationAutomate changelog generation from commits, PRs, and releases following Keep a Changelog format. Use when setting up release workflows, generating release notes, or standardizing commit conventions.Content & docs · MIT◐····●36/40Hermes Tweet> Install and operate Hermes Tweet, a Hermes Agent plugin for X/Twitter research, timeline reading, tweet analysis, and approval-gated private or state-changing operations. Use this skill when installing Hermes Tweet, researching X/Twitter accounts, monitoring launch signals, investigating mentions, auditing giveaways, or preparing gated X operations. Use proactively when a Hermes Agent workflow needs current X/Twitter context. Requires XQUIK_API_KEY for read and action tools.Content & docs · MIT◐····●36/40