关于 explain
用于规范说明文档写作的技能,涵盖术语、图示、文章结构和具体示例,适合需要清晰阐释机制与步骤的作者。
主要功能
- 01术语表要求
- 02Mermaid 图示规范
- 03明确说明因果关系
- 04五部分文档结构
适用场景
- 01规划说明文档
- 02统一定义专业术语
- 03使用 Mermaid 制作图示
- 04解释机制与操作步骤
安装
复制下面的命令,在终端中运行。
$
npx skills add https:/ / github.com/ mathbullet/ skills --skill explain安装后在 Claude Code 中输入/explain确认已加载。
详细介绍
说明文档规范
术语处理
- 在文档顶部以表格形式列出术语(
| Term | Description |)。正文中使用的每个专业术语都必须在此列表中首次出现时加以定义。 - 术语列表中的条目用一到两句话说明该术语是什么。功能或行为细节应放在正文中,而不是术语列表中。
- 即使是广为人知的专有名词(行业标准产品名称、基础设施组件等),也要在此处定义。请假设读者并不了解这些名词。
- 定义复合术语时,也要定义其中的各个词。如果复合术语由三个词组成,就要为这三个词分别列出条目——不能指望读者自行推断它们之间的关系。
图表规范
- 使用 Mermaid 绘制图表。不要使用 ASCII 艺术图。
- 每个节点标签都必须是术语列表中已有的术语。不要在图表中引入新术语。
- Mermaid 节点中不要使用
<br/>。许多渲染器会显示原始 HTML 标签。如果需要换行,请用/分隔,或缩短文本,使其适合单行显示。 - 对于包含四个或更多节点的图表,或标签较长的图表,请使用
graph TD(从上到下)。graph LR(从左到右)会将长标签图表压缩成难以阅读的水平长条。
描述的细致程度
- 不要用含糊的语言掩盖细节。必须明确说明主语、宾语和动词。
- 类似“A 使用 B 来完成 X”的表述,必须说明 A 是什么,以及 A 为何需要通过这种方式完成 X。
- 避免使用“接收”或“传递”等含糊动词。请明确说明谁采取了什么行动来促成状态变化(例如,“接收地址”→“平台自动分配地址”)。
- 不要要求读者自行推断步骤之间的联系。必须明确说明每一步与下一步之间的因果关系。
- 先以一般形式描述机制,再将其与具体的命名实例联系起来,例如“在 X 的情况下,……”。不要让整篇描述都围绕单个专有名称示例展开。
结构
- 术语列表
- 背景(说明此事物为何必要,或解决了什么问题)
- 机制(说明其工作原理——包括图表)
- 具体步骤(命令、流程或演示示例)
- 当前状态(对于持续运行的系统,说明其目前的情况)
评论
支持 Markdown