Community写作与编辑github.com

解释

用用户自己的话,以因果链的形式解释问题——问题优先,每个论断都给出原因,使用口语化的技术表述。在用户询问为什么或如何工作、失败,询问问题是什么,认为解释不清楚,或需要理解系统或变更的架构时使用。

解释 是什么?

该技能旨在通过构建因果链来生成清晰、准确的解释。其核心方法论是:首先,从用户的对话历史中提取其使用的术语、已知知识和知识空白,确保解释完全基于用户的语言体系。然后,按照“问题优先、每个论断附带原因、因果链落脚于已知知识”的原则撰写解释,并使用括号标注新引入的术语。最后,技能会明确指正用户表述中与代码或事实不符的术语和错误假设,并给出正确的表述及原因。该技能适用于任何需要向用户解释系统工作原理、故障原因或架构变更的场景,能够显著提升沟通效率并减少误解。它支持通过Python脚本从当前项目或所有项目的历史对话中收集用户的用语。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/NG-Bullseye/explain-skill/tree/main/skills/explain

Installed? Explore more 写作与编辑 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

此处的解释是用户话中的因果链:几句简短的句子,每个论断都带有理由,基于用户已使用的术语构建,一次性朗读,如需可读出。

1. 收集用户的话

解释依附于用户已知的内容,而他已知的内容体现在他输入的词语中。在首次解释某个话题之前,请阅读他此前如何谈论该话题:

python3 <此技能所在文件夹>/user_words.py <关键词> [<关键词> ...]
python3 <此技能所在文件夹>/user_words.py --all-projects <关键词> ...

它会打印用户在早期Claude会话中输入过的、包含该关键词的消息,按最新优先排序,范围限于当前项目或全部项目。从他的问题以及话题(组件名称、工具、出问题的事物)中选取关键词。并将当前对话中他的消息也纳入考量。

从中注意三点:

  • 他的术语:他对每个事物的用词("第二个SSH方式"、"入站IP"、"代理")。即使代码或文档中有不同命名,也务必使用这些词。
  • 已知知识:他曾陈述或正确使用过的内容。因果链可以在此处结束。
  • 知识空白:话题中他从未使用过的术语。每个都是新词。

当解释所需的每个术语都被归类为他的术语或新词时,收集完成。

2. 编写因果链

  1. 问题优先。 第一句点名问题或答案本身:"问题是X。"当用户提出直接问题("密码有什么用?")时,第一句话应直接回答该问题。
  2. 每个论断都带有原因。 通过“因为”、“由于”、“通过”等词将原因附加在同一句中。孤立的效应陈述是一个未闭合的链接:“所有连接都来自127.0.0.1”毫无解释力,除非紧接着“fail2ban按IP封禁”。
  3. 链至已知知识。 持续追问原因,直到最后一个原因是用户的已知知识。在此处停止。
  4. 使用他的术语,描述机制本身。 用他的术语如实陈述实际机制。禁止使用类比、形象比喻或杜撰的概念。
  5. 新词用括号标注。 新词首次出现时,后面紧跟括号内的关键词解释,之后可单独使用:“HostKeyAlias (SSH选项:根据known_hosts中的另一个条目检查主机密钥)”。关键词,而非句子。
  6. 口语化散文。 三到五句简短陈述句,每句包含一个链接,按原因到结果的顺序排列。纯文本,可经受文本转语音:解释内部不使用标题、表格或项目符号列表。

对于架构,因果链沿着一个请求或一个变更的路径运行:哪个部分行动,它传递给下一个什么,下一个为何能或不能利用该信息完成其工作。

3. 指出修正

用户的话和假设需与代码和事实核对,每个偏差都要指出——在因果链之后,每行一条,格式为“你说… / 正确的是…,因为…”:

  • 代码不支持的说法:他说“通行密钥”,但实际是钥匙串条目;他说“Runner宕机”,但Runner是容器而Docker失败了。给出代码或工具使用的名称,以便他下次搜索和提问。
  • 错误假设:他视为当然但不成立的事情(“我需要密码才能连接”)。说明事实及其原因。

在纠正前需对照代码或系统验证;仅凭记忆的纠正是猜测。之后,仅在他正确使用术语时才继续沿用。

示例

用户本应得到的解释的正确表述(为何fail2ban不能保护通过Cloudflare隧道连接的SSH)。此处的例子是德语;请用用户书写语言进行解释。

问题在于通过密码的第二个SSH方式。任何人可以使用Mac的用户名和用户密码通过暴力破解建立连接。fail2ban无法保护,因为它是基于IP的封锁,并且通过隧道,每个人都有一个相同的入站IP,因为Cloudflare代理了连接。

完成条件

发送前,检查每个句子:

  • 第一句点名问题或回答用户提出的问题;
  • 每个论断都在同一句中带有原因;
  • 最后一个原因是用户的已知知识;
  • 每个术语都是他的术语,或者是带括号标解释的新词;
  • 他的问题中的每个错误说法和错误假设都已被指出并修正。

当用户仍然不理解时,找出缺少原因的那个环节,仅用一句话补充该环节。具体数值(两个IP、一个请求)仅在此处引入,以闭合该链接。

下一步的操作(选项、命令、建议)在解释之后,与解释分开提供,并且仅在用户询问或需要执行时才给出。

相关技能