wshobson/agents

hads

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.

查看源码

使用方法

  1. 复制安装命令,在自己的智能体环境安装前先检查源码包。
  2. 从原始文档核对所需工具、凭据和支持的宿主。
  3. 说明输入材料与期望交付物,并对照来源检查输出。
npx skills add https://github.com/wshobson/agents --skill hads

开始前需了解

  • 安装不包含模型订阅、API 额度或访问文件的权限。
  • 仓库星数和安装量反映活跃情况,不等于独立质量或安全测试。
仓库原始内容

按源仓库内容呈现,保留标题、案例、代码、表格、链接以及原文引用的演示图片。

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.

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 X.Y.Z** in header (first 20 lines)
  3. AI manifest section before first content section
  4. Content sections (H2), subsections (H3)

4. HOW CLAUDE 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 CLAUDE GENERATES 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 X.Y.Z** in first 20 lines
  • AI manifest before first content section
  • All block tags bold: **[SPEC]** not [SPEC] not [SPEC]
  • [BUG] blocks contain at minimum symptom + fix

Validator: (planned — not yet included in this release)


7. EXAMPLE INTERACTIONS

[SPEC]

User: "Write HADS documentation for this REST API" → Generate full HADS document: header, manifest, sections with [SPEC]/[NOTE]/[BUG] blocks

User: "Convert this README to HADS format" → Restructure existing content into HADS blocks, preserve all facts, add manifest

User: "Is this document valid HADS?" → Check: H1 title, version, manifest, block tag formatting, BUG block completeness

User: "Summarize this HADS document" → Read only [SPEC] and [BUG] blocks, return structured summary

User: "What does this API do?" (HADS doc provided) → Read manifest, read [SPEC] blocks in relevant sections, answer directly


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

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


9. QUICK REFERENCE

[SPEC]

Tag       | Bold format    | Reader  | Required content
----------|----------------|---------|------------------
[SPEC]    | **[SPEC]**     | AI      | Facts, terse
[NOTE]    | **[NOTE]**     | Human   | Context, narrative
[BUG]     | **[BUG] ...**  | Both    | Symptom + fix
[?]       | **[?]**        | Both    | Unverified claims

Manifest minimum:

markdown
## AI READING INSTRUCTION
Read `[SPEC]` and `[BUG]` blocks for authoritative facts.
Read `[NOTE]` only if additional context is needed.
`[?]` blocks are unverified.

按任务相关推荐

来自同一仓库

更多 Skills

全部 Skills
wshobson
社区

typescript-advanced-types

Master TypeScript's advanced type system including generics, conditional types, mapped types, template literals, and utility types for building type-safe applications. Use when implementing complex type logic, creating reusable type utilities, or ensuring compile-time type safety in TypeScript projects.

累计安装量
10.1万
GitHub Stars
4.3万
最近更新
11月21日
wshobson
社区

tailwind-design-system

Build scalable design systems with Tailwind CSS v4, design tokens, component libraries, and responsive patterns. Use when creating component libraries, implementing design systems, or standardizing UI patterns.

累计安装量
7.5万
GitHub Stars
4.3万
最近更新
11月18日
wshobson
社区

kpi-dashboard-design

Design effective KPI dashboards with metrics selection, visualization best practices, and real-time monitoring patterns. Use this skill when building an executive SaaS metrics dashboard tracking MRR, churn, and LTV/CAC ratios; designing an operations center with live service health and request throughput; creating a cohort retention analysis view for a product team; or debugging a dashboard where metrics contradict each other due to inconsistent calculation methodology.

1小时安装量
2
GitHub Stars
4.3万
最近更新
11月18日
wshobson
社区

market-sizing-analysis

Calculate TAM/SAM/SOM for market opportunities using top-down, bottom-up, and value theory methodologies. Use this skill when sizing markets, estimating addressable revenue, validating market opportunity for a new venture, or building investor-ready market analysis for a startup pitch or business plan.

1小时安装量
2
GitHub Stars
4.3万
最近更新
11月18日