1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | documentation-and-adrs-addyosmani-agent-skills |
| 项目自述名称 | Agent Skills（合集仓库整体名）；本子技能文件内自称 “Documentation and ADRs” |
| 作者/维护者 | Addy Osmani（个人开发者，知名 Web 工程师，前 Google Chrome DevRel 团队负责人） |
| 来源链接 | https://github.com/addyosmani/agent-skills/tree/main/skills/documentation-and-adrs |
| 许可证 | MIT（GitHub API 确认） |
| GitHub Stars | 合集仓库整体 80,775（GitHub API）——⚠️该数字属整个 24 技能合集，不代表本子技能自身热度 |
| Forks | 合集仓库整体 8,712（GitHub API） |
| 最新版本 | v0.6.5（2026-07-26，合集仓库统一版本号，GitHub Releases） |
| 安装方式 | npx skills add addyosmani/agent-skills --skill documentation-and-adrs；Claude Code/Codex 插件市场；手动复制目录 |
2. 功能介绍与亮点
一份“记录决策而非只记录代码”的文档实践指南：代码回答“做了什么”，文档回答“为什么这样做”。覆盖四块：① ADR 全生命周期——先匹配仓库既有约定，无约定才套默认模板（Status/Context/Decision/Alternatives/Consequences），附 PROPOSED→ACCEPTED→SUPERSEDED 生命周期规则；② 行内注释规范——只注释“为什么”，反对占位 TODO 与死代码；③ API 文档——TypeScript JSDoc 与 OpenAPI 双模板；④ 面向 Agent 的文档——讲 CLAUDE.md/规则文件如何帮 Agent 理解代码库、避免“重新决策”。亮点是“常见借口对照表”与“红旗清单”，把文档意识变成可核查项。
3. 适用场景
固定分类：工程效率与代码质量。典型场景：团队在技术选型、API 变更、功能上线时记录决策背景；新成员（人类或 Agent）借 ADR 快速理解代码库历史。
4. 跨 Agent 兼容性
- Claude Code：原生支持——官方插件市场安装
- Codex：原生支持——v0.122+ 原生插件市场安装，
@documentation-and-adrs调用 - OpenClaw / Hermes Agent：支持但非仓库自身点名——推荐安装器 vercel-labs/skills 官方 Supported Agents 表格列出两者
5. 推荐理由
把“文档写why不写what”这条常挂嘴边却难落地的原则，拆成 ADR 模板、注释正反例、API 文档模板与验证清单，并补上 Agent 时代易被忽视的一块——CLAUDE.md/spec 文件该怎么维护。单文件 Markdown、零依赖、复制即用。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | 属 Addy Osmani 24 技能合集（整体 80,775★，不代表本子技能自身热度）；子目录自身 5 次专属提交，含独立企业 Netresearch 的 CTO Sebastian Mendel 2 次已合并改进，另有一名自述“FAANG产品经理”的用户提交扩展提案（未合并，显示真实关注） |
| 可用性 | 9 | 单文件 Markdown，复制即用；SKILL.md 288 行含完整模板与验证清单；子目录最近提交 2026-07-16，合集整体 2026-07-26 仍活跃；无付费依赖 |
| 安全性 | 9 | 见下方检查清单 |
安全检查清单：
| 检查项 | 结果 |
|---|---|
| ① Shell 命令执行 | 无——纯文档写作指南 |
| ② 运行时联网外发 | 无 |
| ③ API Key/凭据 | 不涉及 |
| ④ 可疑指令/注入迹象 | 通读全文未见异常指令 |
| ⑤ 作者信誉 | 良好——知名 Web 工程师、前 Google Chrome DevRel 负责人 |
| ⑥ License | MIT，明确 |
| ⑦ 最近维护 | 子目录 2026-07-16、合集整体 2026-07-26 |
综合评分 = (7+9+9)/3 = 8.33
7. 跟同类 Skills 相比的优势
| 技能 | 出品方 | 覆盖范围 | 差异 |
|---|---|---|---|
| documentation-and-adrs（本技能） | Addy Osmani | ADR 全生命周期+注释+API文档+README/Changelog+Agent文档 | —— |
| create-architectural-decision-record（37,154★，MIT） | GitHub 官方 | 仅生成单份 ADR，面向 Copilot | 只做“产出一份ADR”单点动作，不覆盖注释/API文档/README 全流程 |
| doc-coauthoring（Anthropic 官方技能） | Anthropic | 与用户协作共创长文档 | 关注对话式共创过程，不涉及 ADR 或代码注释规范，场景互补 |
github/awesome-copilot 更像单点工具；本技能把文档规范系统化为贯穿开发全流程的一套指导。
8. 用户评价
未找到专门针对 documentation-and-adrs 的具名第三方评价。其所属技能包整体在 Hacker News 有独立讨论帖：用户 umeshunni 澄清技能文件默认只加载 frontmatter、不会造成上下文膨胀；用户 wg0 则质疑靠 Markdown 文件约束 LLM 行为的价值有限，方法论效果目前主要靠使用者自行验证。
9. 安装使用方式
- 通用（推荐）：
npx skills add addyosmani/agent-skills --skill documentation-and-adrs（底层 vercel-labs/skills CLI，支持 70+ agents） - Claude Code：
/plugin marketplace add addyosmani/agent-skills→/plugin install agent-skills@addy-agent-skills - Codex（v0.122+）：
codex plugin marketplace add addyosmani/agent-skills，聊天中@documentation-and-adrs调用 - 手动：
git clone后复制skills/documentation-and-adrs/到对应 Agent 的 skills 路径 - 安装后无需重启，按场景由 Agent 自动或手动调用
10. 注意事项
- 属 24 技能合集的一部分，若只需文档能力建议用
--skill参数单独安装 - ADR 模板默认假设项目无既有约定；仓库若已有自己的约定，技能会优先匹配现有约定
- 纯文档写作指导，不执行代码、不联网，效果依赖使用者是否认真遵循清单