learn-anything

学习任何内容

这是一项由用户调用的 Skill。创建或更新持久化软件包需要用户主动选择；不要代替用户调用另一项由用户调用的 Skill。

目的

使用这项 Skill 判断任意源材料是否包含简洁、可复用的 Agent 方法。提取可重复的操作方法，而不是对已发生之事做被动总结。

只有证据完整时，来源充分性分支才会生成一份内部方法契约。契约必须保留可能反复出现的触发条件、决策、命令、约束、失败模式、验证关卡和输出约定。不得使用通用默认值，从不完整的材料中编造可直接用于生产的 SKILL.md。

兼容的 Agent

编写生成的 Skill 时，应确保其可适配常见的 AI Agent 宿主，而不局限于某一种运行环境。预期使用者包括：

• OpenAI Codex 和 Codex 风格的本地编码 Agent
• Claude Code
• Gemini CLI
• Cursor Agent
• Windsurf Agent
• GitHub Copilot 编码 Agent
• Aider
• OpenCode
• Roo Code
• Continue
• CrewAI Agent
• LangGraph Agent
• AutoGen Agent
• ReAct 风格的自定义 Agent
• 其他能够遵循 Markdown 指令并运行捆绑脚本的文件读取型编码、研究、文档或自动化 Agent

来源采集

只收集推断可重复方法所需的来源：

• 用户请求或目标陈述
• 对话记录、任务笔记、问题讨论串、README、文件夹树、测试输出或工作流文档
• 用户的更正，尤其是反复提出的“不要做 X；改为做 Y”指导
• 未来 Agent 必须识别的命令、路径、文件名、API、架构和确切错误字符串
• 新 Skill 必须遵循的现有 Skill 或项目规则

如果来源材料过于稀少，返回 BLOCKED，并准确列出缺少的方法字段。即使已有标题，也要将 TBD、TODO、N/A、unknown、空占位符、通用模板套话、内联字面标记（如 <placeholder>）以及嵌入的未解决标记（如 TBD - decide later）视为缺少证据。Purpose、Triggers、Inputs、Ordered Method、Decisions、Outputs 或 Verification 中单独出现的 TBD 或 TODO 仍表示证据尚未解决；不要仅因 Constraints 或 Failure Modes 中的防护说明要求不要保留 TBD 值就拒绝。如果所声明的资源以未解决标记结尾，应视为来源缺口；明确写明 none 的资源则允许。如果调用证据同时指出由用户调用和由模型调用，应返回调用类型冲突的阻塞结果，而不是自行选择。如果材料是叙述、一次性任务或被动总结，则返回明确标记为 not_promoted 的学习总结。来源证据充分之前，不要起草软件包。

决策工作流

1. 判断来源属于可复用工作流、叙述、被动摘要、一次性任务，还是内容过少、无法评估。只有存在肯定性的标题、开篇上下文、Purpose、Trigger 或有明确边界的 Scope/Context 证据时，才将内容归类为一次性任务或被动摘要；不要扫描泛泛的失败模式描述，也不要因为某个字段写着 not merely a one-off、no longer a one-off，或只有失败模式记录了 no procedure，就降低一个完整方法的级别。
2. 区分持久有效的流程与偶发的任务细节。保留会改变未来行为的内容；准确保留权威材料中的操作细节。
3. 提取目的、触发分支、明确的调用类型、输入、有序方法、决策、约束、失败模式、输出、资源和验证方式。
4. 将纠正措施和失败模式转化为有来源依据的约束、护栏或验证检查，不得改写掉命令、路径、决策或错误信息。
5. 仅当所有必需的方法字段都有证据支持时，才创建内部 Method Contract。在该合同中记录置信度和未解决的缺口。
6. 证据不足时，返回未提升为方法的学习摘要，或返回带有明确所需来源缺口的 BLOCKED。绝不要用通用工作流、约束或质量检查填补缺失字段。
7. 只有在完整的内部 Method Contract 存在后，集成式 Package Build Layer 才能考虑构建包。Method Contract 本身不可单独安装为 Skill。

包构建前提

不要直接从原始来源开始构建包。完整的内部 Method Contract 是构建包的前提条件。来源充分性门本身不会输出 SKILL.md。

包构建

门控返回 outcome: method_contract 后，使用该 JSON 结果运行集成式包构建器。构建器是确定性的，并会将 Method Contract 保持为内部内容：

python learn-anything/hooks/package_builder.py \
  --contract-file <method-contract-result.json> \
  --output-root <skill-collection-root> \
  [--resource-root <source-resource-root>]

除非提供 --name，否则构建器会根据合同标题生成 kebab-case 名称。它会生成直接指令式的 SKILL.md，其中包含有来源依据的目的、触发分支、调用类型、输入、有序方法、决策、约束、失败模式、输出、资源、保留的证据和验证方式。每个有序步骤都包含可检查的完成标准。运行时不会导入、复制或依赖 writing-great-skills。

将构建器结果视为明确的状态：

• created 表示已写入新包。
• updated 需要 --update，且只会更改生成的包说明，同时保留无关文件。构建器会在 .learn-anything-managed.json 中跟踪复制的资源，并且只删除此前由生成合同管理、但新合同中已省略的资源。
• no-op 表示相同合同已生成该包；应予以保留。
• duplicate 表示已存在未受管理的包或不同的安装；应停止操作，并在更新前获取明确授权。
• blocked 表示合同不完整、存在未解决的问题或矛盾，或超出包的边界。应返回确切原因，不要写入文件。

仅从生成的包安装到干净的宿主目录。使用构建器的 install_package() 边界（或通过宿主提供的文档化安装程序复制完整的包目录），然后验证 SKILL.md、声明的元数据以及每项有充分依据的资源均已就位。第二次相同的安装必须是 no-op；除非用户明确授权更新，否则已存在的不同包属于重复项。

内部编写规则

生成软件包时请遵循这些规则；它们是内部指导，不是对其他 Skill 的运行时依赖：

• 在 SKILL.md 中为每个触发分支写出所需的最简有序方法；仅在分支需要时才说明该分支专属的参考资料。
• 在描述中说明软件包的作用及其适用场景。每项决策只保留一个权威来源，并删除重复或无实际作用的文字。
• 保留已接受来源中的准确命令、路径、更正和失败条件。不得用通用标题或默认值填补缺失字段。
• 仅当契约明确提及并说明资源的必要性时才纳入资源。不要创建空目录、占位文件或未经验证的脚本副本。仅在明确提供 --resource-root 且通过存在性和路径包含性检查后，才复制相对路径资源；绝对路径应继续记录为外部前置条件。
• 明确声明调用边界。应建议用户调用另一个 Skill，并在此停止，而不是暗中运行它。

生成的 Skill 结构

每个生成的 Skill 都必须包含：

• 带有 YAML frontmatter 的 SKILL.md，其中仅包含 name 和 description
• 一个 kebab-case 文件夹和一个长度少于 64 个字符的技能名称
• 一段同时说明该技能的作用以及 Agent 应在何时使用它的描述
• 以直接操作指令编写的正文
• 涵盖目的、触发条件、输入、工作流、约束、输出格式和质量检查的章节或等效内容
• 仅在直接有用时才附带资源

除非来源明显更适合采用其他简洁结构，否则优先使用以下正文结构：

# Skill Title

## Purpose

State what repeatable work the skill enables.

## Inputs

List source artifacts, credentials, paths, or context needed before acting.

## Workflow

Give the minimum ordered procedure that a future agent should follow.

## Constraints

Capture user preferences, scope boundaries, failure modes, safety rules, and exact decisions.

## Output Format

Describe the artifact, summary, patch, command output, or decision the skill should produce.

## Quality Checks

List concrete verification gates before final response.

提取规则

• 保留具有操作意义的准确命令、文件名、标题、API、错误字符串和用户更正。
• 优先使用命令式工作流步骤，而非描述性文字。
• 示例应简短且具体。
• 除非项目专属名称是必要的触发信号、路径约定或示例，否则不要包含它们。
• 不要把一次性回答、翻译、天气查询或时间查询转化为技能。
• 不要创建宽泛的记忆摘要。应编码说明下次如何采取不同操作的内容。
• 不要将未解决的方法字段变成占位章节。应返回来源缺口。
• 不要包含未使用的资源文件夹。

Hook 脚本

可选的确定性辅助脚本位于 hooks/：

• learn_gate.py：在任务开始前对请求进行分类，结果为 normal_task、observe_and_summarize 或 create_or_update_skill。
• session_reflector.py：检查已完成的对话记录，寻找可复用的经验，并返回 ignore、summarize_candidate 或 create_skill。
• skill_candidate_builder.py：评估来源是否充分，并返回内部 Method Contract、未晋升的学习摘要或 BLOCKED 来源缺口。

使用原始文本或 stdin 上的 JSON 对象运行这些脚本。它们会输出 JSON，供其他 Agent 使用决策，而无需解析散文。

质量检查

交付生成或更新的技能前：

• 确认来源充分性结果为 method_contract，而不是 learning_summary 或 blocked。
• 确认 Method Contract 包含目的、触发条件、调用类型、输入、有序方法、决策、约束、失败模式、输出、资源、验证、未解决的缺口和置信度。
• 确认来源证据中保留了所提供的准确命令、路径、决策、更正和失败模式。
• 确认 SKILL.md 的 frontmatter 有效，且仅包含 name 和 description。
• 确认描述包含具体的触发条件。
• 确认正文讲授可重复执行的操作方法，而非总结会话。
• 确认约束体现了用户更正和已知失败模式。
• 确认输出格式和质量检查具有可操作性。
• 有可用的技能文件夹时，运行 Skill Creator 验证。