Docs writing protocol
Skill z-soulx/ai-toolkit/skills/doc-processing/docs-writing-protocol
文档写入协议（去躁点版）。控制 AI 何时写入文档、写入什么内容。当用户说"沉淀到文件"、"记录下来"、"update: xxx.md" 时使用。From its SKILL.md
npx -y skills add z-soulx/ai-toolkit --skill docs-writing-protocolAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 13 stars13 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
2.7 KB, as published. Nobody here has run it
文档写入协议（去躁点版）
目标：只有明确指定目标文件时才写入；写入时只记录设计/契约/语义的变化，不把修 bug、重试、风格调整等噪声落进文档。
核心原则（两句口诀）
- 写入门槛：没点名文件，就不写入（只在对话里回答）。
- 去躁点：纠错不记账；改契约/改流程/改规则/改语义，就记账。
1. 写入门槛
只有满足任一条件，才允许对 md 文件做持久化更新：
-
明确指定目标文件路径，例：
update: docs/xxx.md -
明确要求"生成/落地到某个文件路径"的文档产物
-
语义上表达"需要沉淀/记录/落地到文件"，例：
- "这个需求沉淀到文件"
- "把这个记录下来"
- "落地到文档"
- "需要持久化"
- "写进 xxx.md"
→ 若未指定文件名，先询问目标文件路径，确认后再写入。
否则：只在对话中输出，不创建、不修改任何文件。
2. 目标文件绑定
当用户第一次点名 X.md，设置 DocTarget = X.md，后续交互默认继续更新 DocTarget（仍遵守去躁点规则）。
- 切换目标：
switch: Y.md - 停止写入：
stop writing
3. 去躁点判定
不写入
满足任一条：不写入 DocTarget
- 修复编译/语法/单测
- 修正 AI 理解偏差，但不改变既定设计
- 重试/提示词调整/代码风格/重构不改外部行为
口诀：纠错不记账
必须写入
满足任一条：写入 DocTarget
- 对外契约变了（接口字段、枚举、返回码、回调语义）
- 流程变了（状态机、时序、重试策略）
- 规则变了（优先级、分支条件、开关含义）
- 数据含义变了（字段意义、来源、映射、默认值）
口诀：改契约/改流程/改规则/改语义，就记账
4. 写入格式（强制最小化）
每次写入只允许：
- What changed：变化点（1~3 条）
- Why：一句原因
- Impact：对外影响（可选）
实现过程、排障、试错、重构细节一律不写入。
5. 交互指令
update: path/to/doc.md— 指定写入目标switch: path/to/another.md— 切换目标stop writing— 停止写入no-record— 本轮强制不写入（即便命中必须更新，也只在对话说明）