Skip to content
Back to search

explain-plainly

用中文大白话向小白或不了解项目的人解释 Agent 输出、任务进度、具体功能、实现质量和主要风险;结合贯穿例子,按需使用两层 G-W-T、图示或 HTML,并通过后续交互帮助理解。适用于“这段话什么意思”“给外行讲明白”“用图解释”等理解诉求,不把解释自动升级为实现、审计或正式验收。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/buccaneermethodology--explain-plainly/badge.svg)](/listings/buccaneermethodology--explain-plainly)

HTML

<a href="/listings/buccaneermethodology--explain-plainly"><img src="/api/listings/buccaneermethodology--explain-plainly/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

推荐从 [v0.1.0 Release](https://github.com/buccaneermethodology/explain-plainly/releases/tag/v0.1.0) 下载 `explain-plainly-v0.1.0.zip` 与 `SHA256SUMS`。在只放这两个文件的空目录中校验:

# macOS
shasum -a 256 -c SHA256SUMS
# Linux 也可用 sha256sum -c SHA256SUMS
unzip explain-plainly-v0.1.0.zip

解压后得到 `explain-plainly/`,含 `SKILL.md`、`agents/openai.yaml`、两个参考文件和许可证。请保留整个目录,单独复制 SKILL.md 会丢失参考资料。

Codex 的当前官方技能目录是用户级 `~/.agents/skills/` 或项目级 `.agents/skills/`,见 [OpenAI 官方技能文档](https://learn.chatgpt.com/docs/customization/overview#skills)(2026-11-18 核对)。以用户级安装为例,在刚才的解压目录运行:

mkdir -p "$HOME/.agents/skills"
# 先拒绝覆盖已有安装,避免丢失本地修改;已有符号链接也会拒绝。
if [ -e "$HOME/.agents/skills/explain-plainly" ] || [ -L "$HOME/.agents/skills/explain-plainly" ]; then
  echo '已存在 explain-plainly,请先比较并备份原目录。'
else
  cp -R explain-plainly "$HOME/.agents/skills/explain-plainly"
fi

项目级安装时把上述目标换成项目的 `.agents/skills/`。若现有环境明确使用 `.codex/skills/`,按该宿主配置放置完整目录;本项目不保证所有旧版本都支持当前官方路径。安装后在新聊天中确认宿主能列出或选择该技能,再显式调用。这里的文件安装检查不代表所有宿主已加载;其他支持 `SKILL.md` 的 Agent 须按各自文档配置。

也可以取得固定版本源码,从仓库根目录重建安装包:

git clone --branch v0.1.0 --depth 1 https://github.com/buccaneermethodology/explain-plainly.git
cd explain-plainly
python3 scripts/check.py
python3 scripts/package.py --output-dir dist

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 68 lines
  1. ---
  2. name: explain-plainly
  3. description: 用中文大白话向小白或不了解项目的人解释 Agent 输出、任务进度、具体功能、实现质量和主要风险;结合贯穿例子,按需使用两层 G-W-T、图示或 HTML,并通过后续交互帮助理解。适用于“这段话什么意思”“给外行讲明白”“用图解释”等理解诉求,不把解释自动升级为实现、审计或正式验收。
  4. ---
  5. # 大白话解释
  6. 帮助读者形成能复述、能判断影响的理解:这是什么、与谁有关、哪里有问题、现在能确定什么、还差什么。默认中文,尊重用户指定的语言、篇幅和媒介。把“不了解项目”当作缺少背景,不当作缺少思考能力。
  7. ## 先理解,再展开
  8. - 优先解释用户圈定的句子或对象,补足最少必要背景:谁在做什么、想得到什么结果。不要先抛项目缩写、Session 编号或治理流程。
  9. - 使用当前对话和用户材料;解释原文通常不需要全仓审计。只有判断“当前实际进度/质量”确实需要时,定向读取可用的最新来源。若只依据摘录,直说“根据这段描述”;旧来源不冒充当前事实。
  10. - 将内容分清:来源明确的事实、说明性示例、推断、期望/建议、未知。仅在容易混淆处自然标明,不给每句话贴标签。
  11. - 指代不明且会改变解释对象时,先问一个关键问题;可以解释的部分先解释。无关键缺口时,直接给出第一轮说明,不先收集长问卷。
  12. ## 第一轮怎样讲
  13. 按理解需要组织,不强制每次使用全部标题:
  14. 1. **先给核心意思与影响。** 用一两句说明真实操作者想做成什么、当前结论意味着什么。内部工具的操作者可能是 CLI 调用者、Reviewer 或服务消费者,不虚构普通终端用户。
  15. 2. **用同一个具体例子串起来。** 给输入起名字,说明操作前、操作后和出错时的差异;例子中的输入、动作、结果要对应。例子覆盖的是局部,不能替代原始全部验收要求。
  16. 3. **只解释必要术语。** 首次出现给短括注,再说明它为什么影响结果。把“结构未对齐”等抽象语改成“缺了什么 → 可能发生什么 → 怎样才能判断”。类比帮助入门时,要指出与真实机制有关的限度。
  17. 4. **落到可观察的结果。** 说明在什么时点看什么输入、输出或状态,以及不能发生的副作用。来源未规定的判定方法,标为建议或未知,不编造预期数据。
  18. 5. **交代现状和缺口。** 已做成什么、还不能证明什么、需要哪项观察或决定。不要把“应该这样”写成“已经这样”。
  19. 优先使用短段落、熟悉词汇和具体动词;保留会改变结论的限定条件。术语可保留在括注中便于回查,避免把原文换成另一组术语。无需为了通俗省略严重风险,也不要为完整而堆满背景。
  20. ### 按解释对象选择重点
  21. | 对象 | 要让读者理解 | 常用表达 |
  22. | --- | --- | --- |
  23. | 当前进度 | 总目标、已完成的可用部分、剩余缺口、下一步 | “要做到什么 / 现在做到哪 / 还差什么”;只有分母和依据明确才给百分比 |
  24. | 具体功能 | 谁在什么情境下操作、得到什么、边界在哪里 | 贯穿例子;行为复杂时加两层 G-W-T |
  25. | 实现质量 | 想保障什么、实际检查过什么、发现什么、影响多大 | 预期与实际对照;区分代码检查、模拟测试、真实运行 |
  26. | 主要风险 | 什么条件触发、谁受影响、后果、当前证据、应对 | 因果链;没有数据不编概率和严重度分数 |
  27. ## 按需选择表达形式
  28. - **简短概念或一句话**:直接解释,必要时加一个小例子。
  29. - **对比、进度、质量或风险**:优先短表、前后对照或简图,避免装饰性图表。
  30. - **功能行为与验收含义**:可用“大白话 + 用户视角 G-W-T + 系统视角 G-W-T”。先读 [两层 G-W-T 与教学案例](references/examples.md)。G-W-T 是组织行为说明的方法,不是所有解释的必选项。
  31. - **多步骤、多角色、随条件变化的内容,或用户要求图文/HTML**:读 [图示与 HTML 指南](references/visuals.md),主动选最能减轻理解负担的形式。用户已指定 HTML 时直接制作;未指定时,首轮可先给有用的文字和小图,再建议 HTML。
  32. ## 不能因解释而改变的边界
  33. - 不把摘录里的评审发现自动升级为已验证缺陷;不把教学字段写成产品 schema,不替产品决定等价性、权限、兼容性、日期口径、持久化或失败政策。
  34. - 界面文字相同不必然代表字段身份、资源归属、动态含义或查询结果相同;日志和内部状态也不能冒充操作者已看到的结果。
  35. - 静态阅读、示例、模拟或测试通过,只证明实际观察的层次。未执行保持“未观察”;缺来源保持“未知”。解释不能产生新的通过、完成或验收授权。
  36. - 有来源可链接时,把关键事实关联到可点击的原文件/段落,说明它支持什么;不使用裸摘要作为小白的证据入口。来源只在对话中时如实说明,不伪造引用。
  37. - 本技能只解释和制作说明材料;不自动修复功能、改任务状态、发布网页或修改正式需求。用户另行要求的行动按其授权和所在环境规则处理。
  38. ## 第一轮之后怎样继续
  39. 先交付能独立读懂的解释,再根据本次内容提供 2–3 个具体、可选的深入方向,例如“看复制前后对照图”“看一遍实际操作”“看失败时会发生什么”。简单问题已讲清则无需附菜单;不要每次机械列出全部媒介。
  40. 用户仍困惑时,定位理解卡点:是不知道它是什么、为什么影响结果、怎么操作,还是不清楚当前做到哪。一次问最有帮助的一项,例如:“你更想看操作过程,还是想弄清为什么只看界面文字还不够?”也允许用户指出难懂句子,不用考试式问法。
  41. 下一轮针对卡点改换例子、分解步骤、补背景或换图,减少重复。可以邀请用户用自己的话确认理解,但不强迫复述、不把沉默当作已经理解,也不声称已经保证所有读者都懂。
  42. ## 交付前的六项复核
  43. 1. 没看过项目的人能先回答“谁要做成什么”,再读技术说明吗?
  44. 2. 例子的输入、操作、结果是否属于同一情境,且没有替代完整要求范围?
  45. 3. 必要术语是否解释了影响,因果是否有依据?
  46. 4. 操作者结果与系统保障是否分清,内部工具是否用了真实操作者?
  47. 5. “正常、正确、一致”是否落到可观察行为,判定来源是否明确或标为缺失?
  48. 6. 要求、示例、实际结果和未知是否分清,格式是否真的帮助理解?
README.md · README · 94 lines
  1. # 大白话解释 · explain-plainly
  2. 把 Agent 输出、项目进度、功能、质量和风险讲给不了解背景的人听。先说谁想做成什么,再用一个具体例子说明影响;分清要求、实际观察、建议和未知,按需配图或制作离线 HTML。
  3. 这是以中文为默认语言的 Agent 技能,包含提示规则与参考案例,无第三方运行依赖。它提供解释方法;输出质量仍取决于宿主、模型、输入材料和实际执行,不能用包检查证明所有读者都能理解。
  4. ## 适合什么问题
  5. - “这段评审意见是什么意思,会影响谁?”
  6. - “目标是什么,现在做到哪,还差什么?”
  7. - “用同一个例子解释这个功能,分别讲用户结果和系统保障。”
  8. - “用图或可离线打开的 HTML 说明风险怎样发生。”
  9. 解释不会自动授权修复代码、修改需求、改变验收状态或发布网页。静态检查、教学案例和模拟结果不能替代真实运行及正式验收。
  10. ## 安装
  11. 推荐从 [v0.1.0 Release](https://github.com/buccaneermethodology/explain-plainly/releases/tag/v0.1.0) 下载 `explain-plainly-v0.1.0.zip` 与 `SHA256SUMS`。在只放这两个文件的空目录中校验:
  12. ```sh
  13. # macOS
  14. shasum -a 256 -c SHA256SUMS
  15. # Linux 也可用 sha256sum -c SHA256SUMS
  16. unzip explain-plainly-v0.1.0.zip
  17. ```
  18. 解压后得到 `explain-plainly/`,含 `SKILL.md`、`agents/openai.yaml`、两个参考文件和许可证。请保留整个目录,单独复制 SKILL.md 会丢失参考资料。
  19. Codex 的当前官方技能目录是用户级 `~/.agents/skills/` 或项目级 `.agents/skills/`,见 [OpenAI 官方技能文档](https://learn.chatgpt.com/docs/customization/overview#skills)(2026-11-18 核对)。以用户级安装为例,在刚才的解压目录运行:
  20. ```sh
  21. mkdir -p "$HOME/.agents/skills"
  22. # 先拒绝覆盖已有安装,避免丢失本地修改;已有符号链接也会拒绝。
  23. if [ -e "$HOME/.agents/skills/explain-plainly" ] || [ -L "$HOME/.agents/skills/explain-plainly" ]; then
  24. echo '已存在 explain-plainly,请先比较并备份原目录。'
  25. else
  26. cp -R explain-plainly "$HOME/.agents/skills/explain-plainly"
  27. fi
  28. ```
  29. 项目级安装时把上述目标换成项目的 `.agents/skills/`。若现有环境明确使用 `.codex/skills/`,按该宿主配置放置完整目录;本项目不保证所有旧版本都支持当前官方路径。安装后在新聊天中确认宿主能列出或选择该技能,再显式调用。这里的文件安装检查不代表所有宿主已加载;其他支持 `SKILL.md` 的 Agent 须按各自文档配置。
  30. 也可以取得固定版本源码,从仓库根目录重建安装包:
  31. ```sh
  32. git clone --branch v0.1.0 --depth 1 https://github.com/buccaneermethodology/explain-plainly.git
  33. cd explain-plainly
  34. python3 scripts/check.py
  35. python3 scripts/package.py --output-dir dist
  36. ```
  37. ## 怎样用
  38. 在支持显式调用技能的宿主中输入:
  39. ```text
  40. 请用 $explain-plainly 向不了解项目的人解释这段材料:
  41. “静态检查通过;在真实浏览器点击保存出现500错误;重试是否生成重复数据未知。”
  42. 用一个具体例子说明影响,分清已知和未知。
  43. ```
  44. 一种说明方式(教学示例,并非本仓库执行了这个产品流程):
  45. > 代码通过了基础检查,但实际点击保存时,服务端报了错误,所以这次操作没有得到可确认的成功结果。失败前有没有写入部分数据还不知道,重试会不会重复保存也没有验证。下一步要查这次请求的处理结果,再检查重试后的数据;仅凭检查通过不能说保存已经可用。
  46. 需要进一步展开时,可以说“分别用用户视角和系统视角讲一遍”,或者“做一个可离线打开的 HTML 说明页”。图示、浏览器和文件工具由宿主提供;缺少工具时应如实说明观察范围,不能伪造截图、执行记录或验收结论。
  47. ## 项目内容与维护
  48. | 内容 | 用途 |
  49. | --- | --- |
  50. | [SKILL.md](SKILL.md) | 技能入口与解释规则 |
  51. | [两层 G-W-T 与案例](references/examples.md) | 用同一情境区分用户结果与系统保障 |
  52. | [图示与 HTML 指南](references/visuals.md) | 选择图示、离线页面与检查方式 |
  53. | [界面配置](agents/openai.yaml) | 显示名称与默认调用提示 |
  54. | [贡献指南](CONTRIBUTING.md) | 修改、验证与版本发布方法 |
  55. | [发布记录](CHANGELOG.md) | 版本范围 |
  56. | [开源 Goal](Dashboard/Artifacts/Goal-OPEN-001/Goal.md) | 首次开源任务的验收范围与证据入口 |
  57. 维护检查需要 Python 3.10+ 和 Git;技能本身只需支持该格式的宿主。以下命令验证来源、相对链接、公开候选内容、确定性构建和实际临时目录安装,并运行隔离副本的拒绝案例:
  58. ```sh
  59. python3 scripts/check.py
  60. python3 -m unittest discover -s tests -v
  61. python3 scripts/package.py --output-dir dist
  62. ```
  63. ZIP 固定包含 4 个技能文件及 LICENSE,顶层为 `explain-plainly/`。脚本、测试、Dashboard、KB 和本地治理材料不进入 ZIP。`SHA256SUMS` 对 ZIP 校验。检查结果证明包与安装文件的边界;不证明 Agent 解释效果、真实产品可用性或生产验收。
  64. ## 许可与反馈
  65. 采用 [MIT 许可证](LICENSE),允许使用、修改和再分发,需保留版权与许可声明,按原样提供、不附保证。许可证原文为英文。
  66. 普通问题和改进建议请提交 [GitHub Issue](https://github.com/buccaneermethodology/explain-plainly/issues);安全问题按 [安全反馈说明](SECURITY.md) 处理。提交材料前请移除凭据、客户信息和无关项目内容。

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.