mcpField
E
explain

explain

github.com/mathbullet文档处理175174 次安装2 周前更新
代码仓库

关于 explain

用于规范说明文档写作的技能,涵盖术语、图示、文章结构和具体示例,适合需要清晰阐释机制与步骤的作者。

主要功能

  1. 01术语表要求
  2. 02Mermaid 图示规范
  3. 03明确说明因果关系
  4. 04五部分文档结构

适用场景

  1. 01规划说明文档
  2. 02统一定义专业术语
  3. 03使用 Mermaid 制作图示
  4. 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 的情况下,……”。不要让整篇描述都围绕单个专有名称示例展开。

结构

  1. 术语列表
  2. 背景(说明此事物为何必要,或解决了什么问题)
  3. 机制(说明其工作原理——包括图表)
  4. 具体步骤(命令、流程或演示示例)
  5. 当前状态(对于持续运行的系统,说明其目前的情况)

评论

支持 Markdown