这个 Skill 能做什么，适合哪些场景？
该技能提供了一套明确的文档写作模式与默认结构，帮助作者先给出结论、渐进式披露信息、合理分块、善用标题和列表，让读者能快速扫描与理解。它特别强调评审共情，即设计文档以便评审者能快速验证意图。技能还提供了 Git 和 GitHub CLI 命令来检查文档变更规模，以评估认知负荷。该技能是 Gentle-AI 仓库中 38 个技能之一，仓库采用 MIT 许可证，但技能自身声明 Apache-2.0。
提供六种文档模式（先给答案、渐进披露、分块、路标、识别优于回忆、评审共情）；提供默认文档结构模板（标题、一段概述、快速路径、详情表、清单、下一步）；给出 PR 与评审文档的特定指导；包含用于检查分支中 Markdown 变更文件的 git 命令，以及用于查看 PR 变更行数的 gh 命令。
- 开发者在写 PR 描述时，希望评审者能快速抓住要点，减少来回沟通。
- 维护者在编写贡献指南或维护者指南，希望新贡献者能快速上手。
- 技术作家在撰写架构文档或工作流文档时，希望文档扫读容易、长期可查。
- 在代码评审中，评审者需要清晰的结构和清单来确认变更是否符合预期。
- 团队成员编写 RFC 或设计文档，希望让不同背景的读者都能轻松理解。
如何安装这个 Skill？
- 技能依赖 git 和 gh 命令，这些命令可能不存在或版本不兼容，用户需确保安装。
- 技能许可与仓库根目录不一致（Apache-2.0 与 MIT），可能造成混淆。
- 技能未提供用户确认或作用域限制，使用时需谨慎。
- 技能内容为英文，中文用户可能需要额外翻译。
- Shell / 命令行
- 本地文件系统
git
该技能位于 Gentle-AI 仓库的 internal/assets/skills/cognitive-doc-design/SKILL.md。作为集合的一部分，可通过 Gentle-AI 安装脚本（macOS/Linux 的 curl 脚本或 Windows 的 PowerShell 命令）安装。也可以手动将该文件夹放入支持 Agent Skills 的客户端的技能目录中。
tmp="$(mktemp -d)"
git clone --depth 1 https://github.com/Gentleman-Programming/gentle-ai.git "$tmp"
mkdir -p ~/.claude/skills
cp -R "$tmp/internal/assets/skills/cognitive-doc-design" ~/.claude/skills/
rm -rf "$tmp"根据源仓库地址和 Skill 路径自动生成，只复制这个 Skill 的文件夹。如果上文有作者提供的安装方式，请优先按作者说明操作；想只在当前项目中使用，把 ~/.claude/skills 换成项目里的 .claude/skills。
如何使用这个 Skill？
安装后，把下面任意一句发给 Agent 即可触发：
- 使用认知文档设计技能
在编写或编辑文档时，提示词可包含“使用认知文档设计技能”或类似指令。技能将提供模式与结构建议。如果使用 Git 和 GitHub CLI，可运行 git diff --name-only -- '*.md' 检查当前分支修改的 Markdown 文件，或运行 gh pr view <PR_NUMBER> --json additions,deletions,changedFiles 检查 PR 的变更行数。
这个 Skill 有哪些优点和局限？
- 提供明确、可操作的模式，易于遵循。
- 提供默认文档模板，可直接复用。
- 专门解决评审疲劳问题，提高评审效率。
- 包含实用命令帮助评估变更的认知负荷。
- 不依赖特定平台，普适性高。
- 示例中的命令依赖外部工具（git 和 gh），未提供安装或替代方案。
- 没有自动化测试或验证机制，效果依赖作者自律。
- 可能不适用于已经有更强模板的仓库，需要灵活调整。
- 关于篇幅的实际量化（如“长”或“密集”）缺乏具体阈值。
这个 Skill 与同类方案有什么区别？
与相关 Skills 并排比较；分数均按同一 FSRS 标准得出。
| Skill | FS 评分 | Star 数 | 最近更新 | License |
|---|---|---|---|---|
| 认知负荷友好文档设计 本页 | 43 · 不推荐 | ★ 7.6k | 3 天前 | MIT |
| 发布说明草稿技能 | 32 · 不推荐 | ★ 11k | 3 天前 | MIT |
| writing-pr：PR 标题与描述撰写规范 | 58 · 推荐 | ★ 8.7k | 1 天前 | Apache-2.0 |
| Cookbook 审计助手 ✓ Anthropic · 官方 | 41 · 不推荐 | ★ 53k | 13 天前 | MIT |
| DeepChat 规格驱动开发（SDD）技能 | 58 · 推荐 | ★ 6.4k | 3 天前 | Apache-2.0 |
FollowSkills 如何评估这个 Skill？
技能只建议运行只读的 git diff 和 gh pr view 命令，未授权执行写入操作或修改系统状态，行为在最小权限范围内。但技能未包含明确的用户确认或作用域限制，也未说明对敏感数据的处理方式。依赖外部命令 git 和 gh，未提供依赖安全说明。源码归属明确（作者、许可证），但未验证来源的可信度。扣分原因：缺少用户确认机制和敏感数据处理说明，外部命令依赖未声明安全措施。
技能指令清晰且相互一致，提供了明确的框架和命令。但缺少测试、边界情况和错误处理说明。命令执行失败时未提供诊断建议，用户需要自行排查。静态审查无法执行验证，且技能本身没有提供可复现的测试证据。扣分原因：无测试覆盖，失败信息不足，依赖环境不明确。
技能适用场景定义明确（写作指南、README、RFC、入职文档等），但非适用边界未清晰界定，触发条件仅基于描述，没有精确的语义触发词。技能内容为纯英文，未提供中文支持，但技能本身不依赖网络服务，可从中国大陆网络访问。扣分原因：非适用边界不明确，中文支持不足。
技能有清晰的名称、描述、版本和作者信息，但许可证与仓库根目录的MIT不一致（技能声明Apache-2.0）。缺少变更日志、已知限制说明和维护责任说明。未提供示例或FAQ，安装依赖说明不完整。扣分原因：许可证不一致，缺少变更日志和已知限制。
技能提供了清晰的文档结构和具体命令，核心任务（降低认知负荷）可能实现，但缺少实际输出示例或验证证据。价值主张未量化，与手动或替代方案相比的边际收益不明确。静态审查无法验证输出直接可用性。扣分原因：缺乏代表性输出验证和对比证据。
技能中的关键主张（如降低认知负荷）没有可追溯的证据，也未提供可复现的测试。仓库有CI工作流和测试，但未覆盖该技能的关键路径。扣分原因：主张无证据，测试未覆盖技能路径。
点击维度查看打分理由
证据充分度：低 — 主要依赖静态检查、作者材料或有限演示；适合发现线索，不适合做高风险决策。
查看完整评分方法 →