LLM 更新太快，维护一套评测集既贵又跟不上。problems.md 是个轻量替代：只记长期坏行为，把"感觉有用"变成"问题是否解决"，让人和 Agent 能对齐。坏行为消失，对应的 skill 也就不再被需要。
write-skill 不教你堆指令，教你删噪音，定义什么时候停。
Anchor：坏行为即一切
skill 不该为了存在而存在。它得对应一个具体的、长期能复现的坏行为。如果你说不清没有它时 Agent 会犯什么错，这个 skill 就不该写。
write-skill 强制建 problems.md。它更像一份罪状清单：哪条坏行为、长什么样、怎么算复现。罪状清晰可观察，才动 SKILL.md。
契约：把"何时算完"写成可检查的证据
指令告诉 Agent 做什么，契约告诉 Agent 什么时候算完，而且不许它自己宣布完成。
普通 prompt 走没走到全凭运气。write-skill 要求每步都有 Done when，而且是外部能检查的证据，不是"理解了""已考虑"这种内心戏。
❌ Done when：Agent 理解了用户的意图。
✅ Done when：输出中包含对用户原始问题的逐条回应，且每条回应能追溯到输入中的具体段落。
Prune：删掉一切 no-op
LLM 改 skill有三个问题：遇到一个 case 就补一条规则，不抽象成长期问题； skill 膨胀后自己都开始漏读、挑着执行——这不是它偷懒，是上下文被稀释了；写一堆"要注意""需要考虑"的 no-op 与重复内容，读了和没读一个样。几次迭代下来，SKILL.md 过拟合、过长、充斥废话，几乎不可理解和维护。
write-skill 用 no-op 测试挡这件事：删掉某条规则后 Agent 行为不变，就是 no-op，删。遇到单个 case 先问"这是长期问题吗"，不是就别加入 skill；规则多到自己都要跳读，说明已经在稀释真正该看的那几条。别试图把一条冗长的规则"改好"，直接删。规则越少，剩下的越被当回事。
另外，“不要做 X"会把 X 塞进上下文，反而更容易触发（Negation 效应）。把禁令改成正向引导，只在硬护栏场景保留"不要”。
❌ "不要使用被动语态。"
✅ "所有句子使用主动语态，主语在前。"
SSOT：唯一真相来源
同一条规则别在开头写一遍、中间写一遍、结尾再总结一遍。浪费 token，也稀释注意力。
write-skill 强制 Single Source of Truth：高频信息留在 SKILL.md，低频定义扔进 references/；同一个概念全篇只能有一个 leading word，后面直接回指，别解释别复述；重复出现的概念压成术语，收进 GLOSSARY.md——顺便把"理解了没"变成"用对词没"，可查。
归档：脚手架，不是纪念碑
skill 是为解决坏行为搭的脚手架。problems.md 里的坏行为不再复现，就归档。归档不是失败，是它本来就该走完的生命周期。
写不出 problems.md 里的第一个问题，就别写 SKILL.md。
开源链接
write-skill
Problems
LLM 迭代快，维护评测集与跑评测都贵。problems.md 是本 skill 的问题锚点：只记录长期坏行为，用来判断 SKILL.md 是否该存在、修改或删减。
思想：
- 精简即增益。
- 每条指令只说一次；重复禁令会招致对安全操作的多余确认。
- 说清边界、证据、目标、成功标准、验证对象。
问题
write-skill
description: Use when 编辑 或 review 一个skill。
skill 从随机系统里构建一定的确定性。
先判断是否需要更新目标 skill 的 problems.md：它只锚住目标 skill 要解决的真实长期问题；优化 SKILL.md 写法时默认把 problems.md 当约束读，不把写法问题沉淀进去。然后收敛 invocation、安排 information hierarchy、写运行契约、判断拆分，最后 Prune。 术语见 references/GLOSSARY.md，仅在需要判定术语边界时读取。
输入
- 目标 skill 路径与目标。
- 相关对话上下文；改仓库 skill 时含仓库级 Agent 规则路径。
步骤
Done when 是可校验的完成依据。若步骤正文已包含明确的完成判据（如“输出文件 X”），则省略 Done when，以避免重复。
Anchor 问题。 先判断目标 skill 解决什么问题：读目标 SKILL.md、同目录 problems.md、仓库规则和本次对话；problems.md 作为 目标skill 要解决的问题，只有发现目标 skill 缺少问题锚点，才更新 problems.md。skill 写法问题只作为本次修改依据，不写入目标 skill 的 problems.md。 Done when： problems.md 足以解释该 skill 为什么存在、本次为什么改，契约里没有单次 case 原话。锚定后才动 SKILL.md。
立 skill 骨架。 先写清目标、成功标准、输入、步骤等； 输入覆盖范围参考：特定（通用可以省略）数据与知识来源及查找路径、验证方法、部署方式；仅写本 skill 实际需要的项。 骨架每一项须改变 Agent 行为；无行为差的字段不写。。 Done when： 骨架能回答"做什么、数据与知识从哪来、怎么验证、何时算完"，且每项都回扣 problems.md 的坏行为。
收敛 invocation。 仅当 Agent 需自动发现、或其他 skill 需触达时才保留 description。description 只承载 branch 触发词，首词放该 skill 的 leading word，近义词合并成一条。 Done when： description 每个短语对应一个不同 branch，首词是 leading word。
写运行契约。 正文只留会改变 Agent 行为的动作、边界、证据和 completion criterion；每个 completion criterion 可检查、该穷尽处穷尽。用正向目标表述行为，只有无法正向表达的硬护栏才用禁令。每个 branch 都要的内容 inline，只有部分路径需要的定义、例子、reference 才下沉到 references/，正文保留 context pointer。 Done when： 按契约能判断每步是否完成，最终证据回扣 problems.md。
判断 granularity。 出现独立 branch、或另一 skill 必须触达时，才按 invocation 拆。某步的 post-completion steps 持续诱发 premature completion 时，才按 sequence 拆。 Done when： 拆或不拆的理由回扣触发边界或完成质量，而非“文件太长”。
Prune。 通读本次修改的所有文档，守住每个含义的 single source of truth。逐句做 no-op 测试：删掉后行为无差异的整句直接删，优先删而非改写。合并跨节复述，把铺陈的同一概念坍缩成一个 leading word，清掉 duplication、sediment、冲突、旧迁移和过拟合句。 Done when： 每句话都改变 Agent 行为；改 Git 仓库 skill 时已按仓库级 Agent 规则自检。
输出
汇报：
- Anchor 了哪些问题。
- branch 如何收敛。
- information hierarchy 如何安排。
- Prune 删、留了什么。
![[特殊字符]DeepSeek‑Harness（DSH）小白保姆教程-171主机测评](https://www.171host.com/wp-content/uploads/2026/08/20260816085112-6a817a009aabf-220x150.png)
