Skip to content
Get packs

Guide · Agent skill

How to use the HADS Document Standard agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The hads skill teaches Claude a documentation convention called HADS (Human-AI Document Standard). When you ask Claude to write, convert or check technical documentation, it tags content into typed blocks and adds a short manifest that tells AI readers which parts to read first. After this guide you will be able to install the skill, trigger it with plain requests and know what it does and does not do.

HADS Document Standardwshobson/agents · MIT

Quick start

  1. 1Get the skill. Download the ZIP from this page and unzip it so you have a hads folder containing SKILL.md.
  2. 2Place it where Claude can find it. Move the hads folder to ~/.claude/skills/ for personal use or to a project's .claude/skills/ folder.
  3. 3Or upload it in the apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the skill.
  4. 4Ask for a documentation task. Make a plain request such as writing HADS docs, converting a README, or checking a document for validity.
  5. 5Check the output. Confirm the H1 title, version line, AI manifest and bold block tags are present.
  6. 6Maintain the file. Keep [SPEC] terse, move narrative into [NOTE], and flag unverified claims as [?].

What is an agent skill and what does hads make Claude do?

An agent skill is a folder containing a SKILL.md file that gives Claude extra instructions for a specific kind of task. Claude loads the skill when your request matches its description.

HADS is a convention for Markdown technical documentation. With the hads skill, Claude tags each piece of content as one of four block types: [SPEC] for authoritative facts, [NOTE] for human context, [BUG] for known failures with a fix, and [?] for unverified claims. It also adds an AI manifest near the top of the file telling AI readers what to read and what to skip.

  • Every HADS document needs an H1 title, a version declaration in the first 20 lines, and an AI manifest before the first content section.
  • Block tags are bold on their own line, for example **[SPEC]**.
  • The file stays a plain .md file. No special tooling is required.

How do you install the hads skill?

Download the ZIP from this page and unzip it. The skill's only listed file is SKILL.md. Put the unzipped hads folder in one of two places: your personal skills folder, or a project's skills folder.

You can also upload the skill in the Claude apps through Settings → Capabilities → Skills.

  • Personal install: place the folder in ~/.claude/skills/
  • Project install: place the folder in the project's .claude/skills/ folder
  • Claude app install: upload the skill under Settings → Capabilities → Skills
~/.claude/skills/hads/SKILL.md

How do you trigger the hads skill?

You do not need a special command. Ask for a documentation task in natural language. The skill's description covers writing docs that humans and AI models can both read, converting existing docs to HADS, validating a HADS document, and optimizing docs for token-efficient AI use.

Mention HADS or the task type directly so the match is clear.

  • "Write HADS documentation for this REST API."
  • "Convert this README to HADS format."
  • "Is this document valid HADS?"
  • "Summarize this HADS document."
  • "What does this API do?" (with a HADS document attached)

What do the examples produce?

Each request maps to a specific behaviour in the skill. Writing produces a full HADS document with header, manifest and tagged sections. Converting restructures existing content into blocks while keeping its facts and adding a manifest. Checking reviews the H1 title, version, manifest, tag formatting and BUG block completeness.

When summarising or answering questions about a HADS document, Claude reads the manifest, then the [SPEC] and [BUG] blocks in relevant sections, and answers from those.

What does hads need, and what are its safety limits?

The skill lists no requirements. It runs no scripts and uses no network access. It is instructions only, so it changes how Claude structures and reads files rather than running code on your machine.

The skill's validator is marked as planned and is not included in this release. Checks are done by asking Claude, not by an automated tool.

  • Requires: nothing listed
  • Runs scripts: no
  • Uses network: no
  • Validator: planned, not included in this release

What tips help get good results?

Give Claude the full document when you ask for a summary or check, so it can find the manifest and blocks. For large files, ask it to scan headings first, since the skill recommends reading only the relevant sections.

Use the skill when you want a consistent structure. If your team must follow another house style, the HADS tags and layout will conflict with it.

  • Keep [SPEC] blocks terse: bullets, tables or code, with no more than two sentences of prose.
  • Move history and narrative into [NOTE] blocks, and do not repeat content across block types.
  • Write a [BUG] block only when a failure has a confirmed fix, and include symptom, cause and fix.

What people use it for

  • Writing a README or API doc that AI assistants can read efficiently.
  • Converting an existing Markdown documentation set into a consistent HADS structure.
  • Asking Claude to summarise a HADS document by reading only its key blocks.
  • Checking an existing document for the required header, manifest and BUG block completeness.

Frequently asked questions

Is the hads skill free?

The skill is published under the MIT licence, as listed on this page. The source does not mention pricing, so check the repository for any terms that apply to your use.

What do I need to install the hads skill?

The skill lists no requirements. You need a way to load a skill, either by placing the folder in ~/.claude/skills/ or a project's .claude/skills/, or by uploading it under Settings → Capabilities → Skills in the Claude apps.

Does the hads skill run scripts or use the internet?

No. The skill runs no scripts and uses no network access. It contains only a SKILL.md instruction file.

Is there a HADS validator I can run automatically?

Not in this release. The validator is marked as planned and is not included, so validity checks are done by asking Claude to review the document against the rules.

What are the HADS block types?

HADS uses [SPEC] for authoritative facts, [NOTE] for context, [BUG] for verified failures with symptom, cause and fix, and [?] for unverified claims. Each tag is bold on its own line.

Should I use hads instead of a normal README?

Use hads if you want AI assistants to parse your docs efficiently and your team is happy with its block structure. If your docs must follow another house style, pick a different convention because HADS imposes its own tags and layout.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use the hads skill if you want READMEs or API docs that Claude can write, convert and summarise in a consistent, token-efficient block format, and you are comfortable with its structure. Skip it if your documentation must follow another house style or if you need an automated validator, since that is not included in this release.

Download the skill