用途:撰写或修订面向学习者的文档、Markdown 页面、政策、指南和说明材料,使读者能快速抓住要点,无需依赖单独的聊天解释。
主要能力与要求:
- 先定义“扫读即得”的核心信息:用一句话说明主要结论、读者应采取的行动、需要防止的误解,并放在页面顶部附近,确保只扫读 3 秒也能看到重点。
- 建立可见层级:按需使用 H1 至 H3;一节一个主题;重要内容在前,支撑细节在后;列表型内容用项目符号;段落超过 2-3 行必须拆分。
- 把抽象规则转化为可感知理解:当要求读者改变行为时,必须同时给出抽象规则、具体示例和原因,不能只写“做这个”或“不要做这个”。若渲染器支持,可用带标题的提示框区分“结论优先”“OK 示例”“NG 示例”“为什么”“检查点”等读者任务,但不要添加只重复标题、无实际意义的框。
- 选择性强调:每节至少一个强调焦点,每段通常 1-2 个强调短语;粗体用于结论、关键词、规则和必需行动,斜体用于细微差别、警告或次要重要性,下划线仅用于可能的误解或高风险警告;格式不支持下划线时改用警告句或警告样式提示框。
- 保持对比:不要强调所有内容,支撑性说明保持普通;除非整句就是关键要点,否则不要整句加粗。
- 最终扫读测试:确认仅读标题和粗体即可理解页面;每节有可见焦点;每个重要抽象点都有足够示例或原因支撑;没有仍显密集、拖慢扫读的段落;强调是选择性的而非饱和的。
使用方式:该技能的规范来源是 GitHub 仓库 metyatech/skill-guided-doc-writing,更新技能需编辑该仓库并重新安装;代理不得将代理技能目录中的已安装副本视为主要编辑位置。
限制:资料未提供具体安装命令、平台支持范围、收费或价格信息。