Skip to content
Skills Library
Documents & office · Writing

agent-readable-docs

/agent-readable-docs

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.

Licence
Apache-2.0
Last repository change
27.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.09.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

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.

Original author 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.

How it works

  1. AI READING INSTRUCTION
  2. 1. WHAT IS HADS
  3. 2. BLOCK TYPES
  4. 3. REQUIRED DOCUMENT STRUCTURE
  5. 4. HOW AI READS HADS
  6. 5. HOW TO GENERATE HADS
  7. 6. VALIDATION RULES
  8. 7. DESIGN INTENT
Original SKILL.md headings · 138 lines, 651 words
SKILL.md preview
---
name: agent-readable-docs
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.
---

# Human-AI Document Standard (HADS)

---

## AI READING INSTRUCTION

This skill teaches the agent 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]**
```markdown
# 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:
1. H1 title
2. Version block in header
3. AI manifest section before first content section
4. Content sections (H2), subsections (H3)

---

## 4. HOW AI READS HADS

**[SPEC]**
When encountering a HADS document:
1. Find and read the AI manifest first
2. Read all `[SPEC]` blocks — these are ground truth
3. Read all `[BUG]` blocks — always, before generating any code or config
4. Read `[NOTE]` blocks only if `[SPEC]` is insufficient to answer the query
5. 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 TO GENERATE HADS

**[SPEC]**
When asked to write documentation in HADS format:

1. Start with header block (title, version, metadata)
2. Add AI manifest — always include, never skip
3. Organize content into numbered H2 sections
4. For each fact: write as `[SPEC]` — terse, bullet or table or code
5. For each "why" or context: write as `[NOTE]`
6. For each known failure mode with confirmed fix: write as `[BUG]`
7. For each unverified claim: write as `[?]`
8. 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 in header
- AI manifest before first content section
- All block tags bold
- `[BUG]` blocks contain at minimum symptom + fix

---

## 7. 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 the model know what to read and what to skip — without requiring it to reason about document structure. Explicit is better than implicit for model consumption.

Versions

The database has no other skills named agent-readable-docs.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 211fb956b680 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100hads
    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.
  • 100s4h-writing-technical
    Writes and audits technical documentation, API docs, user guides, and specifications for completeness, sequence, precision, and audience calibration. Use when documentation is confusing, assumes too much knowledge, or leaves gaps a user can't bridge. Triggers: 'technical…
  • 95technical-writing
    Write clear, comprehensive technical documentation. Use when creating specs, architecture docs, runbooks, or API documentation. Handles technical specifications, system design docs, operational guides, and developer documentation with industry best practices.
  • 100markdown-documentation
    Use when writing technical documentation, READMEs, or project documentation in markdown. Covers structure, conventions, and best practices.
  • 100flow-docs
    Use when writing or auditing technical documentation, READMEs, user guides, architecture docs, agent instructions (AGENTS.md, SKILL.md, OKF chapters), pull requests, commit messages, or changelogs.
  • 100make-docs
    Create, edit, and validate technical documentation using the Diataxis framework. Use when writing tutorials, how-to guides, reference docs, or explanations. Use when reviewing or auditing existing documentation for structural correctness. Use when deciding what type of document…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.