agentsclimarketplace
Sign in

Agent readable docs

Skill yeaight7/agent-powerups/skills/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.From its SKILL.md

Install
npx -y skills add yeaight7/agent-powerups --skill agent-readable-docs

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 6 stars6 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

4.3 KB, ~1.0k tokens by cl100k_base, as published. Nobody here has run it

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]

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

What ships with it

Read from the repository

Just SKILL.md. No reference files, no scripts.

Gives 0 of the 12 instructions most docs writing skills give in ~1.0k tokens

Counted across 1,951 of the 3,904 authors here whose files we hold, read 2026-09-06

  • Use third-person for skill descriptionsin 54 of 1951, across 35 files
  • Start descriptions with Use whenin 43 of 1951, across 29 files
  • Run baseline scenarios before writing any skillin 40 of 1951, across 26 files
  • Use active voicein 40 of 1951, across 36 files
  • Map file responsibilities before defining tasksin 36 of 1951, across 29 files
  • Use checkbox syntax for tracking stepsin 35 of 1951, across 27 files
  • Ask one question at a timein 35 of 1951
  • Offer execution options after saving the planin 33 of 1951, across 24 files
  • Include complete code in every stepin 33 of 1951, across 27 files
  • Design units with clear boundaries and interfacesin 31 of 1951, across 23 files
  • Announce the skill usage at the startin 30 of 1951
  • Verify agent compliance after adding the skillin 29 of 1951, across 17 files

Said here and by no other author read

  • Read all SPEC blocks before responding
  • Include AI manifest before first content section
  • Use H1 title and version declaration
  • Place block tags on their own line
  • Follow block tag with content immediately
  • Extract facts into SPEC blocks

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.

Keep looking

Skills are one crate of 325,949. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.