docs-writing-protocol
文档写入协议（去躁点版）。控制 AI 何时写入文档、写入什么内容。当用户说"沉淀到文件"、"记录下来"、"update: xxx.md" 时使用。
Install
npx skillscat add z-soulx/ai-toolkit/docs-writing-protocol Install via the SkillsCat registry.
This skill implements a protocol for controlling when and what content gets written to documentation files. It addresses the problem of documentation noise by only recording design contracts, process changes, rules, and semantic updates, while excluding bug fixes, retries, and style adjustments. Developers should use it when they need to persistently record specific changes to a designated markdown file, triggered by phrases like "update: xxx.md" or "record this to a file.
文档写入协议（去躁点版）
目标：只有明确指定目标文件时才写入；写入时只记录设计/契约/语义的变化，不把修 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— 本轮强制不写入（即便命中必须更新，也只在对话说明）
Install
npx skillscat add z-soulx/ai-toolkit/docs-writing-protocol Install via the SkillsCat registry.