架构决策与工程文档助手
帮助工程团队记录决策依据、维护文档并保留长期代码上下文。
该技能仅提供文档与 ADR 指导，不执行命令、不要求凭据或外部服务，权限风险较低；但未明确敏感信息处理、用户确认、数据流、回滚或来源核验，因此未满分。
内容结构一致，包含触发条件、模板、反模式和验证清单，正常使用路径合理；但没有针对该技能关键路径的测试、异常输入处理或可诊断失败反馈，按静态评估限制扣分。
明确面向架构决策、公共 API、功能发布和团队/代理上下文，并定义了不适用场景；但输出格式、非适用边界和语义触发细则仍较粗，未提供中文支持说明。核心功能不依赖海外服务。
具备概览、使用时机、模板、生命周期、示例、常见合理化和验证章节，仓库提供 MIT 许可及维护者信息；但该技能自身没有版本、变更记录、安装/依赖说明或明确更新责任与路径。
提供 ADR 模板、文档原则、API 示例和检查清单，能够直接辅助完成常见文档任务；但内容较通用，缺少该技能实际产出或与替代方案相比的验证证据，仍可能需要较多项目化调整。
仓库 CI 声称验证技能结构并运行评估，但给出的测试夹具与本技能无关，未见覆盖 ADR、API 文档或验证清单关键路径的专门测试；因此仅给予有限可审计证据分。
- 该评估未执行任何脚本或安装流程，不能确认代理实际触发、生成文档或处理失败的行为。
- 使用前应补充项目级 ADR 目录、编号规则、敏感信息审查、用户确认和回滚要求；默认模板不应覆盖既有项目约定。
- 发布者身份未通过 FollowSkills 企业注册表核验，应将维护状态和来源提交记录单独核查。
这个 Skill 能做什么，适合哪些场景？
这是 addyosmani/agent-skills 仓库中的 documentation-and-adrs 技能，专注于架构决策记录、API 文档、内联注释、README、变更日志和面向 AI agent 的项目文档。它强调记录“为什么”而不只是“做了什么”，并要求先遵循仓库已有的 ADR 约定。技能还提供 ADR 生命周期、文档检查清单和常见反模式。它适合需要持续维护工程上下文的代码库，但不是自动文档生成器或独立的文档发布工具。
指导 agent 在重大架构决策、公共 API 变更、用户可见功能发布和重复解释问题出现时创建或更新文档；检查现有 ADR、项目指令及相关配置以匹配目录、格式、编号和标题；生成包含状态、日期、背景、决策、替代方案和后果的 ADR；为公共 API 添加参数、返回值、异常和示例说明；为非显而易见的约束记录内联注释和已知陷阱；检查 README、变更日志、规则文件及文档验证项目。
- 负责架构选型的工程师需要记录框架、数据库、认证策略或基础设施决策及被否决的替代方案。
- 维护公共 REST、GraphQL 或库接口的团队需要补充类型、参数、返回值、异常和示例文档。
- 发布改变用户行为的功能时，团队需要同步 README、变更日志和相关项目上下文。
- 新成员或 AI agent 反复询问同一设计背景时，维护者需要将隐含知识转化为持久文档。
这个 Skill 有哪些优点和局限？
- 覆盖 ADR、API 文档、内联注释、README、变更日志和 agent 上下文等常见工程文档场景。
- 要求优先匹配现有仓库约定，避免引入第二套 ADR 编号或格式。
- 明确区分记录意图与重复代码，并提供文档后的验证清单。
- MIT 许可证允许在项目、团队和工具中使用。
- 内容主要是流程指导和模板，未显示自动创建、校验或发布文档的脚本。
- 示例和默认 ADR 模板包含 PostgreSQL、Prisma 等具体技术，但这些不是本技能对项目的强制要求。
- 提供的材料没有展示测试套件、运行时集成或真实项目采用效果。
- 使用前仍需由团队判断哪些决策足够重大，以及现有文档约定是否存在冲突。
如何安装这个 Skill？
安装整个仓库的 24 个技能：npx skills add addyosmani/agent-skills。也可以先浏览：npx skills add addyosmani/agent-skills --list。README 还展示了按名称安装单个技能的方式，可使用：npx skills add addyosmani/agent-skills --skill documentation-and-adrs。仓库采用 MIT 许可证。
如何使用这个 Skill？
在支持 Agent Skills 的客户端中，将技能目录作为技能来源使用，并提出具体任务，例如：“为这次数据库选型创建 ADR，先检查仓库现有 ADR 的目录、编号和格式，再记录背景、替代方案、决策与后果。”技能描述表明它会在架构决策、公共 API 变更或功能发布等场景使用。README 未提供该技能专属的独立 slash command，也未说明额外脚本或自动化运行方式。
这个 Skill 与同类方案有什么区别？
README 将 Superpowers 和 Matt Pocock's skills 列为可比较的替代方案，并链接到比较文档；所提供材料未包含该比较文档的具体结论，因此无法据此断言三者的功能差异。