Hads

This teaches Claude to read and write HADS, a Markdown convention that separates facts from context using four block types: SPEC for authoritative data, NOTE for human explanation, BUG for known failures with fixes, and a question mark tag for unverified claims. The key trick is an AI manifest at the top of every document that tells models what to read and what to skip, which cuts token usage on large docs. Use it when you're writing technical documentation that AI will consume directly, or when you want to convert existing docs into something more parseable. The BUG block structure is genuinely useful even if you ignore the rest.

skills.sh installs: 6.9K
GitHub stars: 42.4K
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add wshobson/agents --skill hads --agent claude-code

Installs into .claude/skills of the current project.

Files

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.

SKILL.md on GitHub