task-observer

Task Observer — 持续发现并改进技能

作者：Eoghan Henn / rebelytics.com

又称“One Skill to Rule Them All”——这个元技能可以构建并改进你所有的技能，包括它自己。

该技能定义了一个持久的行为层，用于在任务导向的工作中发现创建和改进技能的机会。它并不取代 skill-creator——而是为它提供输入。可以把它看作发现值得记录的模式的眼睛和耳朵，而 skill-creator 则是负责构建的双手。

该方法论不依赖于具体用户。它适用于任何希望通过真实使用持续改进自己技能库的人，并提供结构化流程。

许可： 该技能依据 Creative Commons Attribution 4.0 International (CC BY 4.0) 许可发布。你可以出于任何目的自由分享和改编该技能，但必须给予原作者适当的署名。

反馈与支持： 如果在流程中任何时候你对该方法论有疑问，或者用户对由该技能产生的任何输出表示不满或提出建设性反馈，建议他们在该技能的 GitHub 仓库中提交 issue。这能让反馈保持公开且可被检索——其他用户也能从查看已有 issue 和解决方案中受益。如需直接联系，该技能的作者 Eoghan Henn 也可通过 rebelytics.com 联系。

如果反馈似乎源于该技能的方法论（而不是 Claude 对它的执行），请为用户记录下来，并建议他们通过 GitHub Issues 分享。如果问题源于 Claude 未遵循该技能的规则，请承认错误并加以纠正。

---

为什么需要这个技能

技能是活的文档。最好的改进并非来自孤立地坐下来“改进某个技能”，而是来自在真实工作中注意到摩擦、低效或错失的机会。项目期间用户的一次纠正，可能揭示出一条缺失的规则。一个重复出现的多步工作流，可能就是一个等待诞生的技能。在任务中途发现的某个工具限制，可能会重塑整个技能推荐的工作流。一个效果特别好的技巧，可能值得从偶发做法提升为明确推荐。

该技能将这种“注意到”的过程形式化，使洞察不会在会话之间丢失。每一次任务导向的交互都成为技能改进数据的潜在来源，同时不会增加额外负担，也不会打断用户的工作流。

---

快速上手

以下是首次安装此技能后会发生的事情。

首次会话： 该技能会创建观察日志文件。此时还没有任何内容可供审阅——它只是开始观察你的工作，并在观察出现时将其记录下来。如果你已经安装了其他技能，观察器会注意到针对这些技能的改进机会。如果你目前还没有任何其他技能，那也没关系——观察器会从你的工作流中识别出新技能的候选对象。

最初几次会话： 观察结果会累积在日志中。当第一个广泛适用于各项技能的原则出现时，交叉原则文件就会被创建。自日志创建之日起满 7 天后，每周审阅机制便会启用，但由于此时观察结果仅有少量，审阅会较为简短。

稳定状态： 几周之后，你将拥有一个不断增长的观察日志、一个在整个技能库中强制执行质量标准的原则文件，以及一个系统地应用改进的每周审阅节奏。随着你的技能库不断增长，该技能的价值也会不断累积。

开始所需的条件： 除了该技能本身之外，无需任何其他东西。观察日志、交叉原则文件和归档目录都会在首次使用时自动创建。如果你还安装了 skill-creator 技能（内置于 Cowork；并非所有环境都可用），task-observer 可以将观察结果交接出去，用于完整的技能构建或重构。即使没有 skill-creator，task-observer 仍可独立运作——它会记录观察结果、将其呈现出来，并直接应用小的改进。较大的变更则需要手动完成。

快速开始

想在 15 分钟内跑起来？以下是最简路径：

1. 安装该技能。 将 task-observer 添加到你的技能目录中。
2. 添加激活语句。 将以下内容复制到你的 CLAUDE.md 或项目指令中：At the start of any task-oriented session — any interaction where you will use tools and produce deliverables — invoke the task-observer skill before beginning work.
3. 执行一项真实任务。 在该技能处于激活状态时，使用 Claude 完成任意一项实质性的工作。
4. 查看你的第一条观察结果。 在会话结束时，该技能会呈现它记录下的任何观察结果。就这样。

无需预先设置，也无需手动编辑配置文件。观察日志和支持文件会在首次使用时自行创建。这是根据采用反馈添加的——来自实际测试者的验证尚待进行。

什么是 [workspace folder]？

在本技能中，[workspace folder] 指的是你的持久工作区目录——即文件在会话之间得以保留的位置。在 Cowork 中，这是你在会话开始时选择的文件夹。在 Claude Code 中，这是你的项目根目录。在没有文件系统访问权限的基于 Web 的聊天界面中，该技能会切换到交接文档模式（参见环境兼容性），你需要手动管理这些文件。

---

推荐激活方式

此技能需要在任务导向会话开始时被调用才能有效工作。由于技能调用取决于 Claude 将用户请求与技能描述进行匹配，一个监控所有任务的技能可能会在 Claude 专注于任务本身时被忽略。

为最大限度地提高激活可靠性，请将以下指令添加到你的配置文件中（例如 CLAUDE.md、项目指令或等效文件）：

At the start of any task-oriented session — any interaction where you will
use tools and produce deliverables — invoke the task-observer skill before
beginning work. This ensures skill improvement opportunities are captured
throughout the session.

When loading any skill, check the observation log for OPEN observations
tagged to that skill. Apply their insights to the current work, even if
the skill file hasn't been updated yet. This enables immediate application
of observations before they're permanently integrated during the weekly
review.

此结构性触发与技能描述层面的触发协同工作。描述旨在广泛匹配任务导向语言（“多步任务”、“Agentic 工作流”、“工作会话”、“工具与交付物”），但配置层面的指令提供了额外的安全网，不完全依赖描述匹配。

致所有用户： 一旦 CLAUDE.md 或等效配置中包含了上述激活指令，描述层面的触发将作为备份而非主要机制。这种双层机制可防止在仅靠描述匹配可能错过调用信号的会话中跳过该技能。

应避免的反模式： 相比从 CLAUDE.md 独立加载两者，依赖一个技能加载另一个技能更为脆弱。如果 task-observer 依赖另一个技能来调用它，该链条中的中断将使所有观察活动静默。相反，应直接从配置指令中加载 task-observer 及任何相关技能。

检测配置文件

在会话开始时，该技能应检查是否存在配置文件（CLAUDE.md、项目指令或等效文件）并包含激活指令。此检测有两个目的：

1. 对于已有配置的用户： 确认双层激活正常工作。无需操作。

2. 对于没有配置的用户： 该技能仅通过描述匹配被激活，可靠性较低。给出简要建议，添加配置层面的指令以便在未来的会话中更一致地激活。

检测方法取决于环境：

• 具有文件系统访问权限的环境（桌面工具、基于终端的工具）：检查工作区根目录中是否存在 CLAUDE.md 或等效文件。如果找到，扫描其中是否包含 task-observer 激活指令。如果文件存在但未提及 task-observer，建议添加该指令。如果根本不存在配置文件，建议创建一个。

• 没有文件系统访问权限的环境（基于 Web 的聊天）：检查系统提示词或项目指令是否包含 task-observer 激活指令。如果没有，建议用户将其添加到项目设置中，或在未来会话开始时粘贴该指令。

此检查在会话开始时运行一次，不会重复。保持建议简短——一两句话，而非完整教程。

---

技能分类

所有技能都属于两类之一。这一区分很重要，因为它决定了该技能可以包含哪些信息、如何组织，以及是否可以公开共享。关键在于，开源/内部的边界也是一条保密边界——开源技能绝不能包含任何可能识别客户、项目或专有流程的信息，即使是间接的。

开源技能

开源技能与客户端无关，且以方法论为驱动。它们沉淀了可复用的工作流、最佳实践和结构化流程，适用于任何人。它们包含作者署名、许可证和反馈渠道，从而让真实使用情况推动改进。

如何识别一个开源候选技能：

• 该方法论可跨不同客户端、项目和场景使用
• 技能运行不需要任何专有信息
• 同一领域的其他从业者会觉得它有价值
• 技能沉淀的是一个流程或方法，而不是个人偏好

必需元素：

• 技能正文明确标明自身为开源，并包含作者姓名和联系方式
• 顶部的作者署名区块（参见下方作者署名模板）
• 许可证声明 — 推荐 CC BY 4.0（参见下方许可）
• 反馈与支持部分，将方法论反馈导向创作者
• 尽可能使用与工具无关的语言 — 引用“浏览器访问”之类的能力，而不是具体产品名称；可以给出示例，但不要硬编码对任何单一产品的依赖
• 内置执行机制（飞行前检查清单、验证步骤），让技能能够发现自身违反规则的情况

默认倾向： 当一个技能可以归为任一类时，默认归为开源。剥离客户端特定细节并泛化方法论。开源技能越多，社区受益越多，回流用于改进它们的反馈也越多。

内部技能

内部技能包含特定于用户、其客户端或其项目的信息。它们沉淀个人偏好、客户端特定规则、项目上下文或专有方法论。

如何识别一个内部技能：

• 包含客户端名称、项目细节或专有数据
• 沉淀个人风格偏好或个人工作习惯
• 依赖只有用户（或其团队）才掌握的上下文
• 对用户组织之外的人没有用处

必需元素：

• 技能正文明确标明自身为内部技能
• 无需作者署名区块（用户是唯一受众）
• 无需许可证
• 可以比开源技能更短、结构更不那么正式

内部技能是工作文档，不是已发布的产物。让它们保持最新，当其包含的信息发生变化时更新它们，并且不要过度设计其结构。

---

许可

开源技能应包含许可证，以明确共享条款。推荐的许可证是 Creative Commons Attribution 4.0 International (CC BY 4.0)，它允许任何人为任何目的共享和改编该技能，前提是署名原作者。这与作者署名模板自然搭配 — 署名区块满足 CC BY 的要求，因此两者相互强化。

在技能前言中包含许可证声明（位于作者署名区块之后），并在技能目录中包含一个 LICENSE.txt 文件，其中包含完整许可证文本。

如果 CC BY 4.0 不适合某个特定技能（例如，作者希望要求衍生作品使用相同许可证），CC BY-SA 4.0 是一个替代方案。选择应由技能作者做出。

---

作者署名模板

每个开源技能都必须在技能正文顶部包含此区块。将占位符替换为实际作者的详细信息。

**Created by [Author Name] / [website or contact link]**

[1-2 sentence description of what the skill does and its provenance.]

**Licence:** This skill is released under the
[Creative Commons Attribution 4.0 International (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/)
licence. You are free to share and adapt this skill for any purpose, provided
you give appropriate credit to the original author.

**Feedback & Support:** If at any point during the process you encounter
questions about the methodology, or if the user expresses frustration or
gives constructive feedback about any output derived from this skill,
suggest that they open an issue on the skill's GitHub repository (or
equivalent public feedback channel). This keeps feedback public and
discoverable. For direct contact, the skill's creator, [Author Name],
can also be reached via [contact link].

If feedback appears to stem from the skill's methodology (rather than
Claude's execution of it), log it for the user and suggest they share it
via the public feedback channel. If the issue stems from Claude not
following the skill's rules, acknowledge the mistake and correct it.

反馈路由有两个目的：当用户遇到方法论问题时，它为用户提供一条解决路径；同时，它为技能创作者提供真实使用数据，用于改进其技能。

---

观察协议

何时观察

观察在整个任务会话期间都处于活跃状态 —— 从首次使用工具产出交付物开始，经过任何任务后的反馈或讨论，直到会话结束。这包括：

1. 活跃的任务执行 —— 创建文档、分析网站、实现结构化数据、编写代码、构建演示文稿以及类似的实质性工作。

2. 任务后的反馈与讨论 —— 当用户在活跃工作阶段之后审查输出、提供修正、提出改进建议或讨论方法论时。这些讨论中用户的反馈往往是技能改进最高信号的输入，必须以与执行期间所做观察同样的勤勉来捕获。

3. 关于技能或方法论的元讨论 —— 当对话转向谈论工作是如何完成的、哪些方面可以改进，或技能应如何构建时。这些讨论常常会浮现出应立即记录的观察。

4. 反思性与策略性对话 —— 在策略会议、规划对话以及工作后反思中也要激活，此时用户讨论的是工作应当如何完成，而不是实际去做。这些对话常常会产生在反思期间涌现、而不仅仅在执行期间涌现的技能改进见解。

当对话从"做工作"转向"讨论工作"时，观察的心态并不会停用。 如果用户提供了关于方法论、命名、技能设计或工作流改进的反馈，应立即将其记录为观察，即使对话处于讨论或审查阶段而非活跃的任务执行阶段。

在闲聊、快速的事实性问题，或其他未使用工具、未讨论交付物的非任务互动期间，观察不活跃。

需要留意的事项

新技能的信号：

• 一个可在不同项目或客户端之间复用的多步骤工作流
• 用户解释的一种未被任何现有技能记录的方法论
• 一种反复出现、具有相似结构和步骤的任务类型
• 一个具有明确输入、阶段和输出的领域特定流程
• 用户描述一个他们经过长期打磨的流程（“我总是这样做”“这个的流程是……”）
• Claude 和用户自然而然地针对某个问题形成一种可被形式化的结构化方法

改进现有技能的信号：

任何来自使用某项技能的任务、且能让该技能变得更好的新信息都值得记录。这包括问题，也包括正面信号和中性观察。例如：

• Claude 尽管有文档记录，却不遵守某项技能的规则——这意味着该技能需要更强的执行力度，而不仅仅是更好的规则
• 用户对 Claude 输出的纠正揭示出一条缺失的规则或该技能未覆盖的边界情况
• 某项技能推荐的工作流被证明不如任务过程中自然形成的做法高效
• 某种技术或方法效果特别好，值得从偶然发现提升为该技能中明确推荐的内容
• 某个工作流步骤被证明比技能所暗示的更重要，或者不如其所受的强调那么重要
• 一个该技能能处理但未明确记录的新用例
• 用户提供的反馈可推广到当前实例之外
• 某项技能的某个假设在实践中被证明是错误的
• 新的工具或能力使某项技能工作流的一部分变得过时或可改进
• 用户的纠正多次形成一种模式
• 涌现出一条可适用于其他技能的通用原则（见下文“原则传播”）
• 用户对某项技能提出命名、表述框架或结构上的修改建议——即便是在对话中——且有可能提升其有效性

简化现有技能的信号：

健康的技能维护既需要增长，也需要修剪。留意去除不必要复杂性的机会，而不仅仅是添加新功能。某项技能已准备好被简化的信号：

• 某项技能中的某个章节或规则在多次启用该技能的会话中从未被用到
• 某条基于单次观察添加的规则尚未通过重复出现得到验证——一次性情况不应累积为永久性规则
• 一个精心设计的工作流，用户却总是走捷径或跳过
• Claude 加载却从不据此行动的章节（上下文窗口中的死重）
• 相互矛盾或造成不必要复杂性的规则
• 出于“以防万一”而添加、却从未被触发的复杂性

在每周回顾中，要像你刻意问“应该添加什么？”那样刻意地问“可以移除什么？”当先前应用过的观察被证明是一次性、并未再次出现时，将其标记为已拒绝，并考虑回退该更改。

不应记录的信号：

• 不会推广到当前实例之外的一次性纠正
• 已被现有技能记录的用户偏好
• 与技能方法论无关的工具缺陷或临时问题
• 若要在开源技能中有用就需要专有客户信息的观察（除非内部技能才是合适的归宿）

如何记录日志

在会话期间静默地将观察结果追加到持久化观察日志中。用户不应被日志记录过程打断。

当出现用户纠正、方法论洞察或与技能相关的事件时，应在同一轮或紧接的下一轮将其写入日志文件——不要在内存中累积观察结果以便之后批量写入。 写入这一行为本身就是执行机制；心理笔记不是观察结果。将观察结果的刷新绑定到现有的工作流检查点——例如，在将某个 TodoWrite 条目标记为已完成时，检查是否已累积任何未记录的观察结果，并在继续之前将其写入。

在分配任何观察编号之前，先执行一个强制的记录前步骤： 搜索整个日志文件，找出所有匹配模式 ### Observation \d+: 的行，提取已使用的最高观察编号，并从此编号递增。每次都必须这样做，无论你是否认为自己从会话早些时候已知当前计数。切勿依赖会话记忆或摘要来确定下一个编号。始终读取实际的日志文件。像下面这样的一行命令就足够了：

# GNU grep (Linux, Cowork):
grep -oP '### Observation \K\d+' log.md | sort -n | tail -1

# macOS / POSIX-compatible alternative:
grep -o '### Observation [0-9]*' log.md | grep -o '[0-9]*' | sort -n | tail -1

这可以防止反复出现的编号冲突问题，即对大文件的部分读取会造成对当前计数的错误认知。

格式与插入规则： 始终使用 ### Observation NNN: 格式。始终将新的观察结果追加到日志文件的末尾。切勿在文件中间插入观察结果。切勿使用其他 ID 格式（例如 OBS-YYYY-MMDD-NN）。一种格式，一个插入点——这确保日志可被 grep、可计数，并可程序化审查。

每条观察结果遵循以下格式：

### Observation [N]: [Short descriptive title]

**Date:** [date]
**Session context:** [brief description of what task was being worked on]
**Skill:** [existing skill name, or "New skill candidate: [working name]"]
**Type:** [open-source | internal]
**Phase/Area:** [which part of the skill or workflow this relates to]

**Issue:** [What happened or what was observed. Be specific — include what
Claude did, what the user corrected, or what pattern emerged. Include enough
detail that someone reading this weeks later can understand the context
without having seen the original conversation.]

**Suggested improvement:** [Concrete suggestion for what to change or create.
For existing skills, reference the specific section or rule. For new skills,
describe the scope and key components.]

**Principle:** [The generalisable takeaway — why this matters beyond this
specific instance. This is the most important part. It turns a single
observation into a reusable insight.]

该格式是通过反复的实际使用逐步完善而来的。这一结构之所以有效，是因为它强制要求具体性（Issue）、可操作性（Suggested improvement）和泛化（Principle）。

上下文保留检查： 在记录观察结果时，确认采取行动所需的所有信息都可在共享文件夹中获取。如果该观察结果依赖于已上传的文件、API 响应或会话本地数据，请在记录该观察结果之前，先将该上下文保存到相应的工作区位置。在观察结果中添加一行 **Reference file:**，指向上下文所在的位置。若观察结果引用的数据仅在当前会话中可用（已上传的文件、API 输出、内存中的结果），则这些观察结果是不完整的——未来的审查会话将拥有该观察结果，却缺少实现它所需的数据。

交接文档分析

当交接文档送达以进行观察记录时，应从显性和隐性来源中系统地提取观察结果：

1. 先记录所有明确陈述的观察结果。 这些很容易浮现，应不加筛选地记录下来。

2. 然后系统地分析整个文档。 阅读每一节并追问：“这里隐含了哪些未陈述的技能缺口、改进机会或新技能候选？”交接文档包含超出会话期间明确捕捉内容的显著信号。

3. 特别关注：

   • 行动项（每一项都可能暗示缺失的技能或工作流）
   • 未决问题（未解决的歧义往往预示决策框架的缺口）
   • “已完成工作”叙述（跨工作项的模式可能揭示元技能）
   • 会话笔记（关于过程的反思性洞察，而不仅是内容）

4. 记录这些额外观察结果并明确注明归因。 说明它们源自对交接文档的分析，而非原始会话。这保留了已陈述洞察与推导洞察之间的区别。

写入时归档

观察日志通过事件驱动的归档机制保持精简，该机制在每次日志写入时运行，而不是累积已解决的条目直到定期审查将其清除。

定义“上一次更新”： “上一次更新”指的是在上一次 SESSION 或之前的日志写入中状态已被解决的条目，而不是在当前会话中被标记为 ACTIONED 或 DECLINED 的条目。关键点：在当前会话的每周审查期间被标记为 ACTIONED 或 DECLINED 的条目，不得在同一会话的写入过程中被归档。它们应在活跃日志中获得一轮可见性——归档发生在下一次会话的日志写入或下一次每周审查时。

每周审查期间的归档时机： 每周审查分两个阶段执行归档：

1. 步骤 1（审查开始时）： 归档来自上一次会话的条目。 在加载观察记录之前，归档在上一次会话中被标记为 ACTIONED 或 DECLINED 的任何条目。这会清除旧的已解决项目。

2. 步骤 6（标记 ACTIONED 之后）： 不要立即归档。当观察记录在当前审查期间（步骤 6）被标记为 ACTIONED 时，它们保留在活跃日志中。在下一次日志写入时归档它们——要么在下一个会话写入日志时，要么在下一周的审查开始时（下一个审查周期的步骤 1）。

这防止了过早归档问题：在当前会话中刚刚被执行操作的条目在移入归档之前会保持可见一个完整的更新周期。

归档文件结构： 将已解决的条目移动到位于以下位置的归档文件：

[workspace folder]/skill-observations/archive/log-[date].md

其中 [date] 是今天的日期，格式为 YYYY-MM-DD。

归档文件保留原始日志的完整头部和状态键。归档后，活跃的 log.md 仅保留其头部、分隔符和所有 OPEN 条目，以及在此次更新中刚刚被标记为 ACTIONED 或 DECLINED 的任何条目。

归档前的安全检查： 在将任何条目移动到归档之前，验证它没有在当前会话中被标记为 ACTIONED 或 DECLINED。如果被标记过，则将其保留在活跃日志中。这防止了观察记录生命周期所描述的同一会话内的过早归档。一种实现方式：跟踪当前会话中被标记为 ACTIONED/DECLINED 的条目 ID 集合，并将它们排除在归档过程之外。

结果：活跃日志保持专注于 OPEN 项目和最近解决的条目，而归档则提供完整的历史记录。

---

保密防护措施

开源/内部的边界是一条保密边界。客户名称、项目细节、域名和专有信息绝不能出现在开源技能中。由于一次泄露就可能侵蚀信任，因此通过多层机制来强制执行——其中任何一层都应能捕获其他层遗漏的内容。

第 1 层：观察记录级别的剥离

在记录标记为 type: open-source 的观察记录时，Issue 和 Suggested Improvement 字段应已使用通用语言。私有观察日志可以为提供上下文而引用具体内容，但 Principle 字段——它会被用于技能创建——应完全通用化。可以这样理解：日志是私人笔记本，但 Principle 是可发布的洞见。

第 2 层：创建前审查

在起草或重新生成任何开源技能之前，扫描所有源材料（观察记录、对话笔记、现有技能内容）以查找可识别信息：客户名称、项目 URL、域名、内部术语、描述得过于具体以至于可被识别的站点结构。在开始编写之前，将发现的任何内容替换为通用等效项。

第 3 层：草稿后扫查

在编写或重新生成开源技能后，重新阅读它，并特别关注信息泄露。这是与 通用飞行前检查清单分开的一轮检查。寻找：

• 不是技能作者姓名的专有名词
• 域名、URL 或项目标识符
• 会缩小客户范围的行业特定细节
• 仅在某个组织语境中才有意义的内部术语
• 具体到可追溯到真实项目的示例

如果发现任何此类内容，请将其替换为通用等价物或删除。

第 4 层：结构原则

分类部分已明确说明这一点，但仍值得重复：开源/内部的区分不仅仅关乎 实用性——它还关乎保密性。当不确定某个细节是否过于具体时，删除它。 一个稍微更通用的技能，总好过一个泄露客户信息的技能。

---

呈现协议

默认节奏

在会话结束时呈现所有观察结果。将它们作为分组摘要呈现：针对现有技能的 观察结果按技能名称分组，新的技能候选单独列出。

提前呈现的情况

• 某项观察需要用户输入才能完整或准确（例如，“这是你希望捕获的模式， 还是一次性的情况？”）
• 某项观察揭示某个技能在当前会话中正在产生错误输出，用户应当知晓
• 多项观察集中在同一个技能上，表明它需要立即关注，而不是在会话结束时 再审查

如何呈现

• 简洁地呈现观察结果：标题、技能，以及一句话摘要
• 对于每一项，说明它是新的技能候选，还是对现有技能的改进
• 说明建议的类型（开源或内部）
• 询问用户希望处理其中哪些（如果有）
• 对于用户想继续推进的项目，移交给 skill-creator 技能，以进行实际的 构建或改进工作

---

根据观察结果采取行动

此技能识别要构建或改进什么。如果你安装了 skill-creator 技能（内置于 Cowork；在其他环境中可作为单独安装项使用），它负责如何处理——指导从 零开始构建新技能，或系统性改进现有技能的完整过程。没有 skill-creator 时，task-observer 仍然有效：小改进可直接应用，较大的更改可依据观察结果 作为规范手动完成。直接应用与移交给 skill-creator 之间的边界：

小改进（直接应用）

如果改进明显是增量的、低风险，且不需要测试来验证其是否有效，则可以直接 应用到技能中：

• 向现有列表添加新规则或反模式
• 澄清已被证明含糊的现有措辞
• 向现有章节添加注释或边缘情况
• 修正事实错误

示例：向技能的反模式列表添加新的反模式。澄清内联代码注释应在其 自身文档中具备上下文意识。

重大变更（如可用，请使用 skill-creator）

如果该变更可能以需要验证的方式影响技能的运行表现，请在 skill-creator 可用时交由它处理：

• 重构阶段或工作流
• 新增能力或章节
• 更改核心方法论或决策框架
• 任何需要真正回答“这样是否确实更有效？”的变更

不过，应根据复杂度和受众来匹配技能创建流程的严格程度。skill-creator 对于需要测试的开源技能、逻辑复杂的技能，或设计尚不明确的情况很有价值。对于需求已在对话中确定的内部技能，直接编写更高效。

如果 skill-creator 不可用，请将观察结果用作规格说明并直接进行更改——但要向用户标明这些是重大变更，可能需要人工审核。

示例：重构某项技能，使自动化工作流成为主要路径而非次要选项。为一项此前从内容工作开始的技能添加一个全新的设置阶段。

创建新技能

在可用时，使用 skill-creator 创建新技能。提供观察结果作为上下文——它们包含高效起步所需的目的、范围和初始设计思路。如果没有 skill-creator，观察结果可作为手动构建技能的详细说明。

创建新技能时，应尽早确定其类型：

• 如果是开源技能，去掉任何客户端特定的细节并进行通用化
• 如果是内部技能，可自由包含所有相关具体细节
• 如果不确定，默认按开源处理——去掉具体细节并进行通用化，然后让用户决定是否需要添加任何内部细节

---

原则传播

当某项观察揭示出一条通用原则——不仅适用于正在改进的技能，也适用于一般技能——就应将其传播到整个技能库，而不只是应用于触发它的那一个技能。

跨领域原则文件

跨领域原则记录在一个与观察日志并列的持久化文件中：

[workspace folder]/skill-observations/cross-cutting-principles.md

该文件在任何技能创建或重新生成过程中都作为强制性检查清单。在交付新的或更新后的开源技能之前，请阅读跨领域原则文件，并验证该技能符合每一条生效原则。这正是将通用原则从良好意愿转变为强制标准的关键。

工作原理

1. 在技能更新期间，某项观察揭示出一条适用范围广泛的原则——不只是适用于正在处理的技能
2. 将其记录为一条观察，标记为 Skill: All skills，并将其呈现给用户
3. 如果用户批准其作为跨领域原则，则将其添加到跨领域原则文件中
4. 从那时起，每次技能创建或重新生成都包含一次针对全部生效原则的合规检查

传播时机

由用户决定每条原则何时以及如何传播：

• 立即传播 —— 适用于重要到需要立即更新所有现有技能的原则（例如保密规则）
• 机会性传播 —— 适用于可在每次技能更新或重新生成时再应用的原则（例如添加许可证声明）

跨领域原则文件结构

# Cross-Cutting Principles

Principles that apply to all skills. This file is read as a mandatory
checklist during any skill creation or regeneration.

---

## Active Principles

### 1. [Principle title]
**Added:** [date]
**Applies to:** [all skills | all open-source skills | all skills with rules]
**Requirement:** [what the principle requires]
**Propagation:** [immediate | opportunistic]
**Status:** [active]

---

每周全面审查

每 7 天，在间隔期满后的第一个任务导向会话开始时，会自动触发一次全面审查。该审查会将所有未关闭的观察结果与所有技能进行交叉核对——而不只是每条观察中提到的技能——并将跨领域原则传播到任何尚未符合要求的技能。

触发机制

审查由 Session Start Protocol 的第 3 步触发（见 Observation Log Management）。当每周审查时间戳超过 7 天或缺失时，Session Start Protocol 会触发此审查。 告知用户每周审查已到期，并开始该流程。

审查步骤

第 0 步 — 调度器可用性检查

在运行审查本身之前，检查每周审查是否可以通过平台的 任务调度能力实现自动化。

1. 检查文件 [workspace folder]/skill-observations/scheduler-registered.txt 是否存在。 如果存在，则说明计划任务已注册 — 跳到 第 1 步。

2. 如果该文件不存在，检查是否有可用的任务调度能力。 在 Cowork 中，检查 create-shortcut 技能及其 set_scheduled_task 工具。在基于终端的环境中，cron 或 等效的调度工具可能可用。

3. 如果调度能力可用：

   • 读取位于 [workspace folder]/skill-observations/scheduled-task-draft.md 的草拟任务描述
   • 在 Cowork 中，调用 create-shortcut 技能，将每周 技能审查注册为计划任务。在其他环境中，使用 可用的调度机制。
   • 使用任务名 weekly-skill-review 和每周一次的频率（例如，周一 早晨）
   • 成功后，将今天的日期写入 [workspace folder]/skill-observations/scheduler-registered.txt
   • 告知用户："每周技能审查已注册为 计划任务。手动 last-review-date.txt 触发器仍作为 回退方案保留。"

4. 如果该工具不可用，静默进入第 1 步。不要在每次审查时 都告知用户 — 此检查在成功之前有意保持静默。

第 1 步 — 加载观察记录和原则

读取位于 [workspace folder]/skill-observations/log.md 的观察日志。 提取所有状态为 OPEN 的观察记录。同时读取 [workspace folder]/skill-observations/cross-cutting-principles.md 并 提取所有生效原则。

如果没有 OPEN 状态的观察记录，且所有原则都已传播， 则跳过审查，更新时间戳，并继续会话。简要 告知用户："每周技能审查：没有未处理的观察记录或未完成 的原则。所有技能均为最新。"

第 2 步 — 清点所有技能

使用系统提示中的 <available_skills> 来识别所有技能。在 不包含该标签的环境中，使用技能目录或 等效的列表机制来发现可用技能。

对于每个技能，读取其位于所提供位置的 SKILL.md 文件。将 平台内置技能排除在更新范围之外 — 只更新用户 创建的自定义技能。

已知系统技能（只读，用户无法替换）： docx、pdf、xlsx、pptx、skill-creator、schedule。此列表可能会随着 平台演进不断增长 — 如果某个技能更新失败，原因是用户无法覆盖 该文件，则将其添加到此列表中。

自定义技能（归用户所有，可被替换）是指技能目录中 不在上述系统列表中的所有其他技能。

第 3 步 — 将观察记录与每个技能进行交叉核对

对于每条 OPEN 观察记录，评估其是否与每个技能相关。 不要仅依赖观察记录自身的 "Skill" 字段 — 观察记录可能 包含比原始上下文所暗示的更广泛适用的一般原则。同时考虑 具体的 "Suggested improvement" 和一般的 "Principle" 字段。构建技能 → [相关观察记录] 的映射。

第 4 步 — 将横切原则与每个技能进行交叉核对

对于每条生效的横切原则，检查每个技能是否已经 遵循。标记出尚未实现该原则的技能。

第 5 步 — 应用更新

对于每个具有相关观察记录或不合规原则的技能， 创建其 SKILL.md 的更新版本。编辑时：

• 将洞察整合到技能中适当的章节（不要只是在底部追加一份观察列表）
• 保留技能现有的结构、语气和作者署名
• 让改进感觉是技能原生的一部分，而不是生硬拼凑上去的
• 如果某条观察建议新增一个阶段、步骤、反模式或检查清单项，就把它放在逻辑上应处的位置

为针对系统技能的观察进行路由： 当某条观察针对的是系统技能时（参见 Step 2 中的已知系统技能列表），不要跳过它。而应将改进路由到一个补充技能 —— 一个用户拥有的技能，命名为 {system-skill}-extras（例如 docx-extras），它在系统技能之上叠加额外的指导。如果该补充技能尚不存在，就创建它。该补充技能应当：

• 说明它扩展的是哪个系统技能
• 只包含增量部分 —— 即系统技能中不存在的额外规则、反模式或指导
• 与系统技能一同加载（如有需要，在 CLAUDE.md 或等效配置中添加一条说明）

这确保针对系统技能的观察仍然可执行，即使系统技能文件本身无法修改。

重要： 不要就地编辑技能文件。将更新后的版本保存到工作区文件夹中，供用户审阅和手动替换（参见下方的 Delivering Updated Skills）。

Step 6 — 将观察标记为 ACTIONED

在根据某条观察成功创建出更新后的技能后，将 log.md 中该观察的状态从 OPEN 更新为 ACTIONED。添加一条简短说明，指出更新了哪些技能，例如：

ACTIONED — Applied to [skill-name] (weekly review [date])

注意：标准的写入时归档机制（参见 Observation Protocol 中的 "Archival on Write"）会在下一次写入日志时自动归档这些新解决的条目。此处无需单独的归档步骤。

Step 7 — 更新时间戳

将今天的日期写入 [workspace folder]/skill-observations/last-review-date.txt。

Step 8 — 呈现摘要和用户操作项

向用户呈现一份清晰的摘要以及他们需要做什么的明确指示。遵循下方 Delivering Updated Skills 中的格式。

Constraints

• 除状态字段外，不要修改观察条目
• 不要创建新技能 —— 只更新现有技能。如果某条观察建议创建一个新技能，请在摘要中注明，让用户通过 skill-creator 单独处理
• 如果某条观察看似相关但你不确定如何整合，请跳过它并在摘要中注明这一不确定之处
• 对待标记为 "internal" 的观察要与 "open-source" 的观察同样严格

---

Delivering Updated Skills to the User

当每周审查（或任何其他流程）产生更新后的技能文件时，必须将这些更新后的文件交付给用户以进行手动替换。技能文件在会话期间位于只读位置，并且可能受版本控制管理、跨设备同步或打包分发。自动就地编辑既不可能也不可取 —— 交付到工作区文件夹并提供明确指示，可让用户保持控制权。

Delivery Process

1. 使用以下结构将每个更新后的 SKILL.md 保存到工作区文件夹：

   [workspace folder]/skill-updates/[date]/[skill-name]/SKILL.md
   

   例如：

   [workspace folder]/skill-updates/2026-02-16/my-skill-name/SKILL.md
   

2. 使用以下格式向用户呈现一份明确的操作清单：

   ## Weekly Skill Review Complete — [date]
   
   The following skills have been updated based on [N] open observations
   and [N] cross-cutting principles.
   
   ### What you need to do
   
   For each updated skill below, replace the existing SKILL.md in your
   skill directory with the updated version from your workspace folder.
   
   ### Updated Skills
   
   **[skill-name]**
   - Changes: [1-sentence summary of what changed]
   - Observations applied: #[N], #[N]
   - Updated file: [link to file in workspace folder]
   - Action: Replace [skill-directory]/SKILL.md with this file
   
   [repeat for each updated skill]
   
   ### Observations Actioned
   [list of observation numbers and titles marked ACTIONED]
   
   ### Skipped (needs manual review)
   [observations that were unclear or couldn't be applied, with explanation]
   
   ### No Changes Needed
   [skills that were checked but already compliant]
   

3. 在用户确认该摘要之前，不要继续其他工作。用户不需要立即替换文件，但他们应当知道有哪些待处理事项。

---

Observation Log Management

Location

观察日志在会话之间持久保存在用户的工作区文件夹中。如果日志文件不存在，请在首次使用时创建它。默认路径：

[workspace folder]/skill-observations/log.md

Log Structure

# Skill Observation Log

Observations captured during task-oriented work. Each entry identifies a
potential skill improvement or new skill opportunity.

**Status key:** OPEN = not yet actioned | ACTIONED = skill updated/created |
DECLINED = user decided not to pursue

---

## [Date or Session Identifier]

### Observation 1: [Title]
**Status:** OPEN
[... full observation format ...]

### Observation 2: [Title]
**Status:** ACTIONED — Applied to [skill-name], rule 35
[... full observation format ...]

会话启动协议

这是所有会话启动检查的唯一入口。在每个面向任务的会话开始时，依次执行以下步骤：

1. 检查文件是否存在。 如果观察日志或跨领域原则文件尚不存在，说明这是首次设置——请使用日志结构部分（见本文档下文）和跨领域原则文件结构部分（见原则传播）中的模板创建它们。如果文件已存在，继续执行步骤 2。

2. 扫描相关上下文。 阅读所有 OPEN 状态的观察记录和活跃的跨领域原则。除非它们与当前任务直接相关，否则不要主动提及——只需将其保持在意识中。

3. 检查每周审查触发条件。 读取 [workspace folder]/skill-observations/last-review-date.txt 中的时间戳。如果该文件不存在或日期距今超过 7 天，请在继续处理用户任务之前触发每周全面审查（详见其专属章节）。如果距今不足 7 天，正常继续。

4. 检查配置文件。 运行检测配置文件（见推荐激活设置）中描述的配置检测。每个会话运行一次。

保持日志整洁

归档是事件驱动的，在每次写入日志时运行。在追加新观察记录或更新状态之前，之前更新中已标记为 ACTIONED 或 DECLINED 的条目会被移入带时间戳的归档文件（见观察协议中的“写入时归档”）。这样可以使活跃日志专注于 OPEN 条目和最近已解决的条目，而归档则提供完整的历史记录。

---

预检原则

本技能在帮助创建或改进每个技能时最应该传播的最重要模式之一：内置强制执行。

实际经验表明，技能中记录的规则在创作输出的流程中并不总是被遵守。结果就是：输出违反了技能自身的标准，从而对技能造成不良影响。

修复方法：每个包含明确规则或要求的技能都应包含一个验证步骤，让 Claude 在交付前重新阅读规则并对照检查其输出。这不是额外开销——这是质量保证。30 秒的重新阅读可以避免 30 分钟的返工周期。

在通过此观察过程创建或改进任何技能时，请问：“这个技能有规则吗？如果有，它是否有强制执行这些规则的机制？”如果第二个问题的答案是否定的，就添加一个。

通用调试原则

调试时，始终要问：这是单个实例还是某种模式？如果某个错误揭示了一种模式（例如，一类相似问题），就修复这一类，而不仅仅是这一个实例。每个具体错误都是关于一类错误的信号。在首次遇到时审计完整范围，以避免在后续周期中发现相关故障。

自我强制执行

本技能言行一致。在会话结束时呈现观察记录之前，请验证：

1. 观察记录是否贯穿整个会话——包括任务后反馈、讨论阶段和反思性对话，而不仅仅是在活跃使用工具期间？
2. 观察记录是否在不打断用户流程的情况下静默记录？
3. 每条观察记录是否遵循格式（问题 → 建议改进 → 原则）？
4. 每条观察记录是否标记了正确的类型（开源或内部）？
5. 对于任何关于现有技能的观察记录，建议改进是否引用了具体的章节或规则？
6. 对于任何标记为 type: open-source 的观察记录，原则字段是否包含任何可识别客户的信息？如果有，请在呈现之前将其泛化。

如果任何观察记录未通过这些检查，请在呈现之前修复。

---

环境兼容性

该观察方法在任何 Claude 能在任务导向型工作中与用户交互的环境中都适用。 持久化机制才是变化的部分。

有持久化存储

在具有文件系统访问权限的环境中（带工作区文件夹的桌面工具、 带项目目录的终端工具或类似环境），完整工作流按所述方式适用：观察结果 记录到持久化文件，跨领域原则文件在技能重新生成时被读取，日志会在 会话之间自动延续。

无持久化存储

在无文件系统访问权限的环境中（基于 Web 的聊天界面或 类似环境），该技能仍然有效——观察方法与环境无关。 区别在于持久化变成了用户的责任，并且该技能会切换到 交接文档模式 以支持 这一点。

交接文档模式如何工作：

• 观察结果在对话过程中被捕获，并像往常一样在 会话结束前呈现
• 不是写入日志文件，而是在会话内收集观察结果， 并在会话结束前以结构化的 交接文档 形式呈现
• 交接文档包括：完整格式的所有观察结果、会话期间做出的 任何决策、行动事项和后续步骤，以及任何需要 保留到下一次会话的工作产物（草稿、分析）
• 用户将此文档复制到自己的存储中（笔记应用、文件系统 等），并将其粘贴到下一次会话中以恢复上下文
• 跨领域原则应包含在交接文档中，以便用户 在开始新会话时可以提供它们

主动生成交接文档： 在没有持久化存储的会话中， 不要等用户请求交接文档。当对话 开始收尾时——用户正在总结、说“暂时就到这里”， 或实质内容即将结束时——主动提出生成一份。过早 提出只是轻微打扰；遗漏则意味着工作丢失。

交接文档格式：

# Session Handoff: [Session Topic]

**Date:** [date]
**Context:** [what was worked on and what the next session needs to know]

## Decisions Made
[numbered list of decisions]

## Observations Logged
[full observation entries in standard format]

## Cross-Cutting Principles (current)
[any principles that were active or newly added]

## Action Items
[what needs to happen next, with enough context to resume]

## Working Artifacts
[any drafts, analyses, or intermediate work products in full]

这不如持久化存储工作流那样无缝，但核心价值 ——系统性地捕获否则会丢失的见解——得以保留。观察 格式和呈现协议在两种环境中完全相同。

---

快速参考

问题	答案
我什么时候观察？	贯穿整个任务会话，包括任务后的反馈和反思性对话
我如何记录？	触发时立即静默追加到观察日志；不要批量处理
我什么时候呈现？	会话结束时，或如有需要更早
我如何可靠地激活？	添加配置级指令（参见推荐的激活设置）
开源还是内部？	尽可能默认开源
开源的许可证？	推荐 CC BY 4.0
小修复还是 skill-creator？	需要测试 → skill-creator（如果可用）。对于需求已明确的内部技能，直接编写效率更高。明确为增量 → 直接应用
什么格式？	问题 → 建议改进 → 原则
作者署名？	开源技能必须署名；使用模板
跨领域原则？	添加到原则文件，在重新生成时强制执行
保密检查？	四层：观察、创建前、草稿后、结构性
没有持久存储？	交接文档模式 — 观察在会话结束时呈现在结构化文档中
调度器自动化？	每周审查的第 0 步自动检查；在工具可用前保持静默
观察编号？	强制性的记录前搜索确保无冲突；绝不使用缓存的编号
日志归档？	事件驱动 — 已解决的条目在下次写入日志时归档
简化信号？	留意一次性规则、从未使用的部分、用户跳过的繁琐工作流以及矛盾之处
交接文档分析？	系统地从行动项、开放问题和叙述部分中提取隐含的观察
调试方法？	始终识别错误的类别，而不仅是实例；首次遇到时审计完整范围