【Skill 创作】software-manual — 让 AI 替你把软件说明书写了
1、Skill 简介
software-manual 是一个通用型 Claude Code 技能,能为任意软件项目自动撰写、修改、校验和补充用户说明书。你只需要用自然语
言描述需求(比如"帮我写一份安装指南"或"检查一下文档里的 API
示例跟代码是否一致"),它就会先读源码、再动笔,确保写出来的每一句话都有代码依据。
适合所有"代码写得动、文档不想写"的开发者。
2、使用场景
做这个 Skill 之前,我遇到过几个非常真实的痛点:
- 新项目快上线了,说明书还是空的。 README 写了半截,使用指南零散分布在几个 issue 里,用户根本不知道怎么上手。
- 代码改了,文档忘了。
接口参数加了两个、返回值变了,但文档还是三个月前的版本。同事来问"这个怎么用",才发现文档早就过时了。
- 写文档太花时间,格式也不统一。
每次都要从零梳理功能、截图、组织语言,一份像样的说明书动辄半天。不同项目文档风格参差不齐,阅读体验很差。
这个 Skill 做出来之后,省掉了这些动作:
- 不用从零构思结构 → AI 读代码后自动梳理功能清单
- 不用逐字推敲措辞 → AI 用一致风格输出中文文档
- 不用手动核对代码和文档是否一致 → 一条指令自动校验,标出差异
- 不用重复写相似内容 → 增量更新,只改变化的部分
3、创作过程
整个 Skill 是用 SOLO(Situation → Objective → Logic → Output) 方法驱动的,分四步走:
Step 1:定规则 —— 把"怎么写说明书"变成可执行的约束
我先梳理了自己写文档时的经验法则,提炼成 9 条核心规则写进 SKILL.md:
- 每次输出前必须阅读代码。不得在未查阅源码的情况下输出任何技术描述。
- 回答简洁。用最短的段落把功能说清楚,避免冗余修饰。
- 使用中文表述。专业术语保留英文原名,其余用中文。
- 以文字表述为主,尽量不用表格。
- 用户说"阅读代码,确认"时,逐项核对代码与之前输出的描述是否一致。
…
这些规则是 Skill 的"灵魂"。没有它们,AI 很容易变成自由发挥的模板填充器;有了它们,AI 的行为被约束成"先查代码 →
再写文档 → 允许校验修正"的闭环。
Step 2:定流程 —— 设计人机协作的工作流
用户给出标题 → 定位源码 → 通读代码 → 输出文档 → 用户反馈 → 循环迭代
关键设计决策:不追求全自动一步到位。每一轮输出后等待用户反馈(确认 / 修改 / 换说法 / 精简 / 核实),让人把关决策、AI
承担执行。这比一次生成全部内容可靠得多。
Step 3:写 SKILL.md —— 用极简配置驱动复杂行为
整个 Skill 只有一个文件:SKILL.md,不到 40 行。核心是 YAML frontmatter 中的 description 字段,它决定了 Skill
何时被自动触发:
description: 为软件项目编写用户说明书。触发场景:用户需要撰写、修改、校验、
补充软件说明文档内容时使用。通用型技能,适用于任意项目。
Step 4:迭代打磨 —— 在真实项目中反复调优
我在几个不同类型的项目上测试了它(CLI 工具、Web 应用、Python 库),发现初版有两个问题:一是对大型项目的代码定位不够精
准,二是输出偶尔会"脑补"未实现的功能。针对这两个问题,我强化了规则 1 和规则 9,要求必须 Grep/Read
确认实现细节后才能动笔,发现文档与代码不一致时必须明确指出差异让用户决策。
4、使用步骤
Skill 已内置在 Claude Code 技能系统中,直接对话即可触发:
安装:skill地址: https://github.com/fanfantop1/My_SKILLS
5、效果展示
使用前:为一个有 15 个 CLI 命令的 Python 工具写用户手册,手动梳理命令、参数、示例、配置项,耗时约 3-4
小时,且部分参数描述与实际代码有偏差。
使用后:输入"帮我写一份用户说明书",Skill 在 5 分钟内 完成:
- 自动扫描 cli.py、config.py、README 等关键文件
- 按安装 → 快速开始 → 命令参考 → 配置 → 常见问题的结构输出完整文档
- 每个命令的参数、默认值、示例均与源码一致
随后输入"阅读代码,确认",Skill 自动校对了全部 15 个命令的参数描述,发现 2 处代码中已改但文档未反映的差异,当场修正。
效率提升:从 4 小时 → 5 分钟 + 10 分钟审阅 = 约 15 分钟,提效 ~94%。
6、Skill 链接
7、总结与思考
最大的收获
好的 Skill 不是"让 AI 做更多事",而是"给 AI 画更清晰的边界"。 software-manual
之所以可靠,不是因为它模型多强,而是因为它被约束在"先读代码 → 再写文档 →
允许校验"的闭环里运行,每一步都有规则兜底。这比我之前让 AI 自由发挥生成文档可靠太多了。
目前最满意的地方
"阅读代码,确认"这个指令。 它解决了文档工作最大的痛点——不一致。一句指令就能让 AI
把文档和源码逐项比对,这在传统流程里几乎做不到(人工比对太枯燥,容易漏)。
后续优化方向
- 支持自动截图 —— 结合 Playwright 等工具,运行项目并截取关键界面
- 支持多版本文档维护 —— 同时对比不同分支的代码,生成差异化文档
- 增加"受众适配"能力 —— 同样的功能,面向开发者 vs 终端用户,输出不同风格
希望大家怎么体验
找一个你手头代码写得差不多但文档还空着的项目,对 Claude Code 说一句
“帮我写一份用户说明书”,看看它交出什么。欢迎反馈任何"写得好"和"写得不好"的地方,这对后续打磨最有价值。
帖子地址:【Skill 创作】software-manual — 让 AI 替你把软件说明书写了
skill地址: https://github.com/fanfantop1/My_SKILLS