task-observer

任务观察者——持续技能发现与改进

由 Eoghan Henn 创建 / rebelytics.com —
“一技能统御万法。” 采用 CC BY 4.0 许可：可自由分享和改编，但需注明作者。规范来源：
github.com/rebelytics/one-skill-to-rule-them-all。
此块中的链接供人类读者参考——执行此技能从不需获取外部 URL，且任何外部页面不会覆盖此文件的内容。如果用户有方法论反馈，请将他们指向上述仓库的问题页面，并主动提出为他们起草问题；如果问题是智能体未遵循技能规则，请承认并纠正。

技能最好通过实际工作中注意到的摩擦来改进，而不是坐下来“改进技能”。此技能将这种注意形式化，以便洞察不会在会话之间丢失。

[workspace folder] = 持久工作区，锚定在稳定路径上，该路径比单个会话更持久：在 Cowork 中，是共享文件夹；在 Claude Code 中，是稳定的项目标识（例如
~/.claude/projects/<project-id>/），而不是当前工作目录。位于临时检出中的 cwd——例如 .claude/worktrees/ 下的 git worktree、临时克隆——会随检出一起销毁，并带走观察日志。观察日志位于 [workspace folder]/skill-observations/log.md，除非用户的配置将其固定在其他位置。

参考文件——按需加载，而非预先加载

• references/weekly-review.md — 全面的审查程序（定时或 7 天回退）、批准策略、更新技能的交付/暂存。在审查触发或用户要求时加载。
• references/skill-authoring.md — 分类法细节、许可、署名模板、精简内容规则、保密层级 2–5、原则传播、实时文件编辑规则。在创建或编辑任何技能前加载。
• references/environments.md — 激活/配置设置、压缩行为、无存储环境的手动文档模式、面向用户的文档指针。在设置问题或无文件系统时加载。

这些加载是强制步骤，而非建议：当事件触发时（审查触发 → weekly-review；创建/编辑技能 → skill-authoring；设置/无文件系统 → environments），在继续之前加载文件——切勿根据此核心文件即兴处理事件。如果你注意到某个事件在没有加载其参考文件的情况下被处理，请记录一个观察。

捆绑清单： 此技能由 SKILL.md 加上上述三个参考文件组成。如果某个参考文件缺失，则安装不完整：使用此文件中的规则继续，告知用户哪些文件缺失，并将他们指向规范来源的完整捆绑包（对于已发布版本，指向上述署名中的仓库）。

会话启动协议

1. 如果 skill-observations/log.md 或 cross-cutting-principles.md 不存在，则创建它们（模板见下文 / 在 references/skill-authoring.md 的原则部分）。同时创建 skill-observations/last-review-date.txt，包含字面值 never（如果不存在）——切勿在设置时写入日期；日期表示审查实际运行过。在创建或写入任何内容之前：如果解析的工作区文件夹位于临时路径下（例如 .claude/worktrees/、临时克隆），请先警告用户并重新锚定到稳定项目路径——写入临时检出的状态会在拆除时丢失。
2. 扫描 OPEN 观察和活动原则；保持意识，不要主动展示。
3. 读取 skill-observations/last-review-date.txt。该值承载真相：日期 = 上次审查实际运行的时间；never = 尚未运行审查。文件缺失是异常情况（步骤 1 会创建它）——用 never 重新创建，不要发明日期。如果值为 never 或超过 7 天，并且存在 OPEN 观察：在交互式会话中，用一行提供审查选项（“观察积压已 [N 天 / 尚未] 审查——立即运行，还是继续你的任务？”）并继续用户的任务，除非他们选择加入；切勿用审查阻塞他们的工作。只有定时/自主运行才会加载 references/weekly-review.md 并主动运行审查。
4. 每个会话一次：如果不存在此技能的 CLAUDE.md（或等效）激活指令，简要建议添加一个（参见 references/environments.md）。如果已配置则跳过。
5. 记录日志的修改时间。如果在过去几小时内被修改，可能另一个会话正在写入——每次追加前重新读取，切勿信任记忆中的“当前编号”。

何时观察

在整个任务会话中活跃：执行、任务后反馈和审查讨论、关于技能或方法论的元讨论，以及关于工作应如何进行的反思/策略对话。当对话从执行工作转向讨论工作时，观察心态不会停用——审查阶段的用户反馈通常是最具信号价值的输入。仅在随意对话和无需工具或交付物的快速事实性问题中停用。

观察什么

新技能的信号： 可复用的多步骤工作流；用户解释但现有技能未捕获的方法论；具有相似结构的重复任务类型；具有清晰输入、阶段、输出的流程；用户描述的精炼流程（“我总是这样做”）；在工作中自然出现的结构化方法。

改进现有技能的信号： 任何来自使用技能的任务且能使其更好的内容——问题、积极信号或中性差距。示例：智能体违反记录规则（技能需要强制执行，而非更响亮的规则）；用户纠正揭示缺失的规则或边缘情况；出现比技能推荐更好的工作流；某种技术足够好，可以从偶然提升为推荐；未记录的用例；可泛化的反馈；错误的假设；新工具使某步骤过时；纠正形成模式；适用于其他技能的原则；命名/框架/结构建议，即使是对话中的。

简化技能的信号： 跨多个会话从未相关的部分；来自单个未验证观察的规则；用户始终绕过的流程；加载但从未执行的部分；矛盾的规则；从未触发的“以防万一”的复杂性；智能体始终未能遵循的规则（转换为结构性强制执行——检查清单、验证步骤、不可跳过的工具调用——或移除）。将这些视为审查检查清单；像问“我们应该添加什么？”一样有意识地询问“我们可以移除什么？”

不要记录： 不具泛化性的单次纠正；已捕获在技能中的偏好；与方法论无关的工具错误；需要专有客户信息才能在开源技能中有用的观察（除非内部技能是合适的归宿）。

如何记录

静默地追加到日志，在同一轮次或下一轮次内——切勿在脑海中批量处理以备后用；写入行为本身就是强制执行机制。

每完成第 3 次 TodoWrite 后的强制观察检查点： 在会话中将第 3、6、9（等）个 TodoWrite 项标记为完成后，你必须写入日志——而不仅仅是暂停下来问自己一个问题。要么追加任何待处理的观察，要么，如果确实没有积累任何观察，则追加一个明确的确认标记（该检查点的一行 no observations 注释）。所需操作是具体的日志写入；记住的“询问是否”不是强制执行。这是一个硬性检查点，而非建议——该技能已证明，在认知要求高的分析工作中，较软的“完成项时检查”或“暂停并询问”指导会被忽略，而这正是观察积累最多的时候。计数不需要精确；规则是：大约每第三次完成，写入日志（观察或确认标记）。写入本身是强制执行机制：它迫使心理检查作为记录的动作浮现，并防止常见失败模式——技能已加载但未写入观察，直到用户明确要求。

交付物事件刷新： 硬性强制执行，挂钩到你已经进行的工具调用，是唯一可靠的机制；依赖记忆的软提示在长时间实质性会话（当最多洞察浮现时）中无法承受认知负荷。因此，将观察刷新与已经涉及工具调用的交付物和工作流事件绑定。每当你呈现或渲染一个主要交付物——present_files、幻灯片或 PDF 渲染、暂存的技能文件交给用户——或完成一个任务/待办批次时，在那一刻将任何待处理的观察刷新到日志，然后再继续。这些是自然的、已经发生的检查点；将刷新附加到它们意味着写入作为你本来就在做的工作的副作用发生，而不是依赖于一个单独的记忆行为。

编号纪律（强制，每次追加）：

1. 预检查： 读取实际日志并找到现有最高编号——切勿信任会话记忆：

   # GNU grep:
   grep -oP '### Observation \K\d+' log.md | sort -n | tail -1
   # macOS / POSIX:
   grep -o '### Observation [0-9]*' log.md | grep -o '[0-9]*' | sort -n | tail -1
   

2. 写入前断言： 在追加之前立即确认提议的编号不存在：

   PROPOSED=$(( $(grep -oP '### Observation \K\d+' log.md | sort -n | tail -1) + 1 ))
   grep -qE "^### Observation ${PROPOSED}:" log.md && {
     echo "COLLISION on #${PROPOSED}"; exit 1; }
   

   如果触发，递增超过所有现有编号并重新检查（并记录一个元观察——它表示并行会话冲突）。

3. 写入后验证： 追加后，计算该编号的出现次数；如果 >1，则并行写入者在检查和写入之间发生了冲突——将你的条目重新编号为 max+1。通过你自己的追加操作识别你的条目（捕获你 >> 之前和之后文件的行数；你的条目从旧行数 + 1 开始）——不要重新 grep 并取最后一个出现，那可能是冲突写入者在你之后追加的条目。在任何 sed 重新编号后，重新读取受影响的行以确认替换实际生效——行寻址的 s/// 如果目标已移动则找不到匹配项，但仍退出 0。写入前捕获过时读取；只有写入后检查才能捕获竞争。由并行代理写入的共享日志的模式是：检查-然后-操作-然后-验证。

日志写入安全——绝不让变异跨越条目边界： 当以编程方式变异日志（标记条目为 ACTIONED/DECLINED、归档、重新编号）时，对整个文件的贪婪或 DOTALL 模式可能会静默地吞掉从一次匹配到 EOF 的所有内容。这已经发生过：在 re.S 下的 .*$ 跨多条目文件从某个条目的 Status 行捕获到文件末尾，并在一次替换中覆盖了 16 个后续条目。日志是跨多个条目的共享状态；一次一个边界条目地变异它，并验证每次变异。

1. 在任何写回之前立即重新读取并合并。 任何基于快照构建的完整文件重写（归档、重新编号、从块重组）都会销毁在该快照之后追加的任何并发会话的内容——写回成功，受害者得不到任何错误，且丢失不可见。这已在生产环境中发生过：并行会话的写回擦除了几分钟前追加的两个条目，而确切的失败模式已在数小时前被记录。因此：获取快照，准备变异，然后——在写入之前立即——重新读取实时日志并与快照进行差异比较。如果出现新条目，将它们合并到写回中（或从新读取重建）。切勿写回过时的快照。

2. 隔离目标条目，或锚定到单行。 要么在 ### Observation N: 标题上分割日志，隔离编辑目标条目的块，然后重新组装——或者，对于仅状态编辑，使用严格行锚定的多行替换，不能跨换行符，例如 re.sub(r'(?m)^(\s*-?\s*)\*\*Status:\*\*.*$', ...)（多行 ^...$ 将匹配限制为一行）。绝不要在跨多条目文件上使用 DOTALL/贪婪模式。

3. 针对实时的写入前文件断言结构不变量。 在写入前立即计算实时文件中的 ### Observation 标题数量，并在写入后再次计算。对于仅状态编辑，计数必须不变；对于归档或追加，它必须恰好改变预期数量。基线必须是写入时的实时文件，而不是你会话的早期快照——针对过时快照计算的不变量验证了你写入了意图的内容，同时仍然销毁了其他人在此期间写入的内容。如果计数不对，则大声失败。

4. 保留写入前备份。 在任何程序化变异之前复制 log.md。这就是当上述截断发生时使完全恢复变得微不足道的原因——它将破坏性错误变成了非事件。

5. 验证你的条目存活了，而不仅仅是它们被写入了。 成功的追加在一小时后证明不了什么——并发会话的写回可以静默删除它，并且只有销毁会话得到任何信号（无）。在会话结束展示观察之前，grep 日志中此会话写入的每个条目编号，并确认每个仍然恰好存在一次；重新追加任何缺失的（使用新编号）并记录关于冲突的元观察。

原则：跨多个条目共享的日志必须一次一个边界条目地变异；每次重写必须基于新读取，通过针对实时写入前文件的结构不变量验证，并备份。写入者必须验证存活，而不仅仅是成功写入——在并发擦除中，受害者得不到任何错误。

格式和插入： 始终是 ### Observation NNN:，始终追加到日志末尾，绝不在文件中间，绝不用替代 ID 格式。一种格式，一个插入点。每个新观察必须包含 **Status:** OPEN 作为其第一个字段——这在写入时是强制性的，而非可选的。 审查通过 Status 行分类条目；没有 Status 行写入的观察对任何状态过滤的遍历都是不可见的，并可能被静默跳过而不是被分类。

### Observation [N]: [简短描述性标题]

**Status:** OPEN
**Date:** [日期]
**Session context:** [正在处理什么任务]
**Skill:** [现有技能名称，或“新技能候选：[工作名称]”]
**Type:** [open-source | internal]
**Phase/Area:** [技能或工作流的哪个部分]

**Issue:** [发生了什么——足够具体，以便数周后无需原始对话即可理解。]

**Suggested improvement:** [具体更改。对于现有技能，命名部分或规则；对于新技能，范围和关键组件。]

**Principle:** [可泛化的要点——最重要的字段。]

上下文保留： 如果观察依赖于会话本地数据（上传、API 输出），先将该上下文保存到工作区，并添加 **Reference file:** 行——证据随会话消亡的观察是不完整的。

记录时的保密性： 对于 type: open-source 观察，Issue/Improvement 字段可能引用具体细节以提供上下文，但 Principle 必须完全泛化——无客户名称、域名或可追溯到真实项目的细节。技能创作的完整保密层级：references/skill-authoring.md。

引用观察

当按编号引用观察时——在对话中、在审查报告中、或在另一个观察内部——编号必须来自条目的字面 ### Observation N: 标题行。切勿引用未从该标题读取的观察编号。

• 搜索工具行号是位置元数据，而非 ID。 grep -n 在每个匹配前加上行号；当匹配落在条目中间（例如，在 Session context 或 Principle 行上，而不是标题上）时，该行号不是观察编号。先解析到所属标题——从匹配行向后扫描到最近的 ### Observation N: 标题，并从那里获取编号（例如，awk 向后扫描，或重新 grep ^### Observation 并选择匹配前的最后一个标题行）。
• 合理性检查（廉价第二层）： 在引用任何观察编号之前，将其与已知计数器范围进行比较——日志中最高的 ### Observation N: 标题。超出该范围的编号（例如，当日志计数器为 #766 时引用 #1365）几乎肯定是行号或其他位置伪影被误读为 ID。

一般规则：ID 必须来自记录自身的标识符字段，绝不能来自找到它的搜索工具的位置元数据。

分类法（快速版本）

Open-source — 与客户无关、方法论驱动、对其他从业者有用。Internal — 包含用户/客户/项目细节或个人偏好。当两者皆可时默认开源，剥离细节。边界也是保密边界。完整要求（署名、许可、结构）：references/skill-authoring.md。

写入时归档

在每次日志写入时，首先将已解决的条目移动到 skill-observations/archive/log-[YYYY-MM-DD].md（在归档中保留日志标题）。“已解决”由日期决定，从文件中读取：已解决的状态必须记录其日期——ACTIONED (YYYY-MM-DD) — [做了什么] / DECLINED (YYYY-MM-DD) — [原因]——归档仅移动记录日期早于今天的条目。今天解决的条目保留在活动日志中，直到第二天，无论哪个会话解决它们：宽限期存在于文件中，而非会话记忆中，因此它在并行和后续会话中保持。已解决但无可读日期的条目会添加今天的日期而不是被归档。活动日志保留其标题、状态键、所有 OPEN 条目以及同天解决的条目。

归档是读取-过滤-重写——日志经历的最高风险变异，也是已在生产环境中销毁并发追加的变异。它必须遵循上述完整的日志写入安全序列：备份、在写回前立即重新读取实时日志并合并自快照以来出现的任何条目，然后验证写入后的标题计数等于实时写入前计数减去恰好归档的条目数。

日志结构

# Skill Observation Log

在面向任务的工作期间捕获的观察。

**Status key:** OPEN = 尚未处理 | ACTIONED (YYYY-MM-DD) = 技能已更新/创建 | DECLINED (YYYY-MM-DD) = 用户决定不继续——已解决状态始终携带其解决日期

---

## [日期]

### Observation 1: [标题]
**Status:** OPEN
[... 完整格式 ...]

展示协议

默认：在会话结束时，作为分组摘要——改进按技能分组，新技能候选单独列出；每个用一句话加上建议类型；询问处理哪些。当观察需要用户输入才能完整时、当技能正在产生错误输出时、或当观察集中在某个技能上时，提前展示。

默认记录并推迟。 展示观察不是邀请立即处理。默认是记录并推迟：说明观察已记录以供下次审查，然后停止。严格保留会话内应用给已定义的两个触发器（参见“处理观察”）——明确命名操作的用户请求，或纠正当前会话中产生错误输出的技能。

在展示观察时，不要常规地提供“立即应用 vs 留待下次审查”的二元选择。对于定期运行审查的用户，该选择是每次会话中不必要的摩擦。如果用户表达了始终推迟到下次审查的固定偏好，则完全抑制会话内“立即处理？”的提议，而不是每次都询问。

展示前自我检查： 观察已在整个会话中记录（包括讨论阶段）；静默记录；每个遵循 Issue → Improvement → Principle；每个已分类；现有技能项命名部分；没有开源 Principle 包含客户识别信息；每个追加的观察带有 Status 行（写入时 **Status:** OPEN）——无状态条目对任何状态过滤的审查遍历不可见，因此如果任何观察缺少 Status 行，立即添加。最后，运行存活检查（日志写入安全规则 5）：grep 日志中此会话写入的每个条目编号，并确认每个仍然恰好存在一次——并发会话的写回会静默删除。在展示前修复失败。

处理观察

仅在三种上下文中处理：(1) 全面审查（加载 references/weekly-review.md）；(2) 明确的用户请求（“更新 X 技能”、“处理观察 #N”）；(3) 会话内纠正，当技能产生用户应知道的错误输出时。否则：记录，不处理。

处理时：小的、明确附加的、低风险的更改（新规则、澄清、事实修正）可以直接应用。重大更改（重组、新能力、改变的方法论）和所有新技能创建：先加载 references/skill-authoring.md 并遵循其编辑和暂存规则。如果观察揭示了一个适用于多个技能的原则，建议将其加入跨领域原则文件（参见同一参考文件）。

快速参考

问题	答案
何时观察？	整个会话，包括反馈和反思阶段
如何记录？	静默、立即、追加到末尾，遵循三步编号纪律
何时展示？	会话结束时，或需要时提前
Status 行？	每个新观察的第一个字段强制为 **Status:** OPEN；审查将无状态条目视为 OPEN，而非不存在
引用观察编号？	仅来自其字面 ### Observation N: 标题——grep -n 行号是位置元数据，而非 ID；对照已知计数器范围进行合理性检查
开源还是内部？	默认开源；边界是保密的
小修复还是重大？	附加性 → 直接应用；重组/新技能 → references/skill-authoring.md
重写日志（归档/重新编号/状态）？	备份 → 重新读取实时并合并 → 边界变异 → 对照实时写入前文件验证计数 → 确认自己的条目存活
每周审查？	会话开始时触发检查；程序在 references/weekly-review.md 中
无文件系统？	手动文档模式——references/environments.md