Hads

Use when writing, converting, validating, or optimizing Markdown technical documentation that must be readable by both humans and AI agents.

9 stars 3 forksWriting & Content

Install

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add sandbaseai/workbuddy-skill --skill hads
Manual install
git clone --depth 1 https://github.com/sandbaseai/workbuddy-skill.git /tmp/workbuddy-skill
mkdir -p ~/.claude/skills
cp -r /tmp/workbuddy-skill/skills/hads ~/.claude/skills/hads

Personal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.

From the SKILL.md

# 人机文档标准(HADS)

使用标准 Markdown 组织既给人读、也给 Agent 消费的技术文档。核心是让机器先找到权威事实,同时保留人类需要的背景;不要用隐含语气让模型猜测哪些内容可信。

## 四类文档块

块标签必须独占一行并使用粗体,内容紧跟标签,中间不插空行:

```markdown
**[SPEC]**
Token expires after 15 minutes.

**[NOTE]**
This limit was chosen to reduce the impact of leaked credentials.

**[BUG] Refresh fails when the session cookie is absent**
- Symptom: the client receives 401.
- Cause: the refresh path assumes a cookie exists.
- Fix: return a typed error and start a fresh login.

**[?]**
The next SDK version may change the default timeout; verify before release.
```

| 标签 | 内容 | 读取策略 |
| --- | --- | --- |
| `[SPEC]` | 可由来源支持的权威事实、参数、表格、代码或契约 | Agent 总是读取 |
| `[NOTE]` | 背景、历史、取舍和示例 | 需要上下文时读取 |
| `[BUG]` | 已验证的失败及修复 | 总是读取;必须包含症状、原因、修复 |
| `[?]` | 未验证、推断或可能变化的说法 | 降低置信度并在回答中保留不确定性 |

块不能嵌套。`[SPEC]` 不是“作者觉得正确”,仍需链接来源;`[BUG]` 不能把猜测写成原因;`[?]` 不能在摘要中被悄悄升级为事实。

## 必需结构

文档按以下顺序组织:

```markdown
# Document title
**Version 1.2.0** · Owner · 2026-09-06 · status

---

## AI Reading Instruction

Read `[SPEC]` and `[BUG]` blocks first.
Read `[NOTE]` only when context is needed.
Treat `[?]` as unverified and report the uncertainty.

## 1. Content section

**[SPEC]**
Facts go here.
```

必须具备:H1 标题、前 20 行内的版本声明、首个内容章节之前的 `AI Reading Instruction`,以及用 H2/H3 划分的内容章节。版本、所有者、日期和文档状态不能凭空编造;未知值明确写 `Unknown`。

## 阅读流程

1. 先定位 AI manifest,按其规则决定读取范围;
2. 扫描标题,读取相关章节中的全部 `[SPEC]` 和 `[BUG]`;
3. 只在事实不足以回答问题时读取 `[NOTE]`;
4. 将 `[?]` 当作假设,回答时标注未验证项;
5. 对数字、日期、引文、Schema 和命令回到原始来源核对,并说明版本/时间。
Read the full skill on GitHub

Details

Skill name
hads
Path
skills/hads/SKILL.md
License
MIT
Repo updated
8 September 2026

FAQ

What does the Hads skill do?

Use when writing, converting, validating, or optimizing Markdown technical documentation that must be readable by both humans and AI agents.

How do I install the Hads skill?

skills CLI (Claude Code, Cursor, Codex and more): npx skills add sandbaseai/workbuddy-skill --skill hads. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.

Is Hads popular?

It lives in sandbaseai/workbuddy-skill, which has 9 GitHub stars and 3 forks.

Related skills

Browse the most popular Claude skills, all writing & content skills, or write your own with the skills generator.