Skill map

Skill Map

在当前主 Agent 中，把多个现有 Skill 组合成一个可解释、可干预、受边界约束的临时工作流。

任务框定 -> 技能调研 -> 组合决策 -> 工作流就绪 -> 执行与验证

全流程使用用户可见的文字更新。工具进度提示不能替代阶段消息。

基本规则

• 在运行时可见范围内，调研所有对当前任务有明确、非重复贡献的 Skill，而不是扫描所有名字相似的 Skill。
• 优先使用运行时已注入或推荐的 Skill metadata；没有现成 catalog 时，只通过原生发现机制读取名称和 description 做一次初筛，不递归扫描文件系统或预读全部正文。
• 只在确实需要时读取候选 SKILL.md 所链接的 references 或 scripts。
• 区分策划、研究、提纲、完整稿件、文件、媒体、发布、费用和其他外部操作的权限。
• 未获得更高权限时，默认只在对话中交付，不创建持久交付文件，不执行外部操作。lens 和临时 Skill 属于已声明的内部临时产物，不等同于用户交付文件。
• 只把影响路线、约束、优先级、风险、质量或验收的认知结论写入临时产物。
• 不复制原始记忆、完整 Skill 正文、对话记录或私有推理。

可选用户偏好

优先读取当前 Agent 已获得的系统指令、Soul、用户资料、Memory、项目上下文和当前会话。仅当长期数据可能改变路线时，才通过运行时提供的原生授权接口查询；没有长期记忆能力时直接继续。

用户也可以在当前会话、平台长期指令或项目指令中声明以下可选偏好：

skill_map_preferences:
  language: zh-CN
  default_output: chat
  interaction: confirm_framework_once
  research_style: concise
  preferred_sources: []
  always_consider_skills: []
  avoid_skills: []
  file_output_default: false
  external_actions_default: false

不要规定偏好必须保存在哪个文件，也不要替用户擅自持久化。按以下优先级解决冲突：

系统与运行时约束
>
当前任务的明确要求
> 当前会话中的用户决定
> 平台长期记忆或项目指令
> 可选偏好卡
> Skill Map 默认值

没有偏好卡不构成阻塞。always_consider_skills 只要求纳入候选评估，不代表必须采用或读取正文。

阶段 1：任务框定

加载本 Skill 后、第一次任务工具调用前发送：

[Skill Map 1/5｜任务框定]
已启动。正在确认任务目标、交付深度和权限边界。
当前边界：<目标；交付物；执行深度；输出方式；文件权限；外部操作权限>。
状态：<无需回复，我将继续筛选相关 Skill。｜需要你确认以下问题；收到回复前我会暂停。>

明确 objective、deliverable、acceptance criteria、exclusions、execution depth、output mode、file output permission 和 external action permission。

如果当前信息足以形成安全且唯一的任务边界，标记“无需回复”并继续。若存在会改变交付物或权限的歧义，提出一个最小化问题并暂停。

阶段 2：技能调研

根据运行时可见的 Skill metadata 选择候选。相关 Skill 的数量不设上限，但每个 Skill 必须有具体贡献。一个 Skill 如果只会禁止任务边界已经排除的动作，可以不读取正文，并记录排除理由。无法确认 catalog 是否完整时，说明本次可见范围，不声称覆盖了不可见的 Skill。

读取 Skill 正文前发送：

[Skill Map 2/5｜技能调研]
可见范围：<运行时已注入、推荐或原生 metadata 索引>。
计划研究：
- <Skill A>：<预期贡献>
- <Skill B>：<预期贡献>
暂不采用：<Skill 及理由；没有则省略>。
状态：无需回复，我将继续；如需调整研究范围，可以随时提出。

通过运行时原生 Skill 机制读取每个候选 SKILL.md。仅为解决路线、冲突、依赖、风险或验证问题而按需读取链接资源。关键词相似不能单独作为采用理由。

如果 Skill 不存在、无法读取或依赖的 provider 失败，立即告知用户影响和恢复路线；不得静默替换证据或伪装成功。

阶段 3：组合决策

完成研究后，先把任务步骤逐一映射到已研究 Skill 的贡献，检查是否存在无人负责的步骤、必要输入缺失、工具不可用、知识不足或关键衔接断点。

现有 Skills 无法可靠覆盖关键步骤时，发送并暂停：

[Skill Map 3/5｜能力缺口]
已覆盖：<现有 Skills 能够完成的步骤>。
关键缺口：<无法满足的步骤或衔接环节>。
不能直接补齐的原因：<缺少知识、工具、事实、权限或业务判断>。
需要你提供：<当前最小化、可回答的问题；必要时列出建议选项>。
状态：收到你的指引前，我会停在这里，不生成临时 Skill，也不开始原任务。

不要把通用推理包装成不存在的 Skill。低风险且信息充分的衔接可以由主 Agent 提出明确方案，但必须在框架确认中标注为“Agent 补充”，说明依据和边界。缺少领域事实、权限、工具或业务取舍时必须向用户求助；一次只问当前最少必要问题，必要时分轮。如果用户也无法提供，再询问是否允许外部研究、缩小范围或带着明确假设继续。

能力覆盖完整，或缺口已由用户解决后，发送：

[Skill Map 3/5｜组合决策]
调研结论：
- <Skill A>：<实际贡献与边界>
- <Skill B>：<实际贡献与边界>
重叠或冲突：<内容及建议处理；没有则写“无实质冲突”>。
能力覆盖：<完整｜已按用户指引补齐；列出 Agent 补充的衔接>。
建议路线：<组合后的执行路线>。
请你确认：这个框架是否可以继续？还有没有需要补充、删除或调整的内容？
状态：收到你的确认前，我会停在这里，不生成临时 Skill，也不开始原任务。

框架确认是默认必经点，即使没有冲突或缺口也要简短展示路线并等待一次。只有用户已在当前任务中明确要求“框架完成后无需再次确认”时，才可以在展示框架后继续，并清楚标注该预授权。

以下情况必须等待用户确认：

• 目标或交付物存在多个实质不同的解释；
• 要扩大执行深度，或新增文件、媒体、发布、费用、账号操作等权限；
• Skill 之间存在会显著改变结果的路线冲突；
• 关键步骤没有 Skill 或可靠的衔接方案覆盖；
• 涉及不可逆、高风险或影响外部对象的动作；
• 缺少只有用户能提供的偏好、事实、凭证或业务取舍。

以下情况可以直接继续：

• 在既定边界内筛选和读取 Skill；
• 合并重复建议、安排内部步骤或选择等价的低风险方法；
• 使用用户已明确表达或平台已注入的偏好；
• 执行只读研究，或创建不对外交付的内部临时产物；
• 不改变交付物、风险和权限的实现细节。

除一次框架确认外，不得用仪式性问题反复打断用户。上下文已经解决的选择应记录为 context decision，不要重复追问。

如果用户没有回复能力缺口、路线选择或框架确认问题，停在当前阶段，不生成临时 Skill，不开始原任务。说明已完成内容、待确认事项和继续方式；用户稍后返回时从该节点恢复，不重复全部调研。

阶段 4：工作流就绪

所有路线性问题解决后，使用 templates/context-lens.json 形成最终 cognition lens。它只记录：

• 任务与精确交付边界；
• 改变执行方式的认知结论；
• 实际研究的 Skills、贡献、边界和按需使用的资源；
• 能力覆盖检查、Agent 补充的衔接以及已解决缺口，分别写入 cognition_effects 或 decisions；
• 排除项、用户或上下文决策；open_questions 在编译前必须为空，非阻塞的不确定性写入认知影响或风险，不伪装成已解决事实。

存在未解决的路线性问题时不得编译。内部临时目录使用：

<temp>/skill-map/<run-id>/
|- context-lens.json
`- task-skill/SKILL.md

使用 templates/temporary-task-skill.md 生成一个任务专用 Skill，并精确保留 lens 中的 execution_depth、output_mode、file_output_allowed 和 external_actions_allowed。

执行校验：

<可用的 Python 3 启动器> scripts/validate_artifact.py <temporary-skill-path> <context-lens-path>

校验通过后发送：

[Skill Map 4/5｜工作流就绪]
临时 Skill 已生成并通过边界校验。
目标：<目标>。
能力组合：<Skills 及各自作用>。
执行流程：<关键步骤>。
交付边界：<执行深度、输出方式、文件和外部操作权限>。
状态：<我现在按已确认边界开始执行。｜本次只要求生成工作流，我将交付临时 Skill 后停止。｜执行仍需以下授权；收到回复前暂停。>

校验失败时不得执行。说明失败项、是否产生临时文件以及下一步修复动作。

如果临时 Skill 由当前主 Agent 在连续上下文中直接生成且未被外部修改，校验通过后可以直接执行，无需重新读取或安装。只有在上下文压缩或中断恢复、外部生成或修改、主 Agent 只拿到路径，或无法确认内存版本与文件一致时，才重新读取最终 SKILL.md。

阶段 5：执行与验证

仅在已确认的交付边界内执行临时 Skill。不要把策划扩写成完整稿件，不要把聊天结果另存为文件，也不要生成媒体、发布、花费资金或调用外部动作，除非这些权限已经明确允许。

开始时发送：

[Skill Map 5/5｜执行与验证]
正在按已确认的临时 Skill 执行。
当前输出：<交付物>。
边界保持：<关键限制>。

完成后发送：

[Skill Map 5/5｜执行完成]
交付结果：<结果或位置>。
验证情况：<验收证据与边界检查>。
未完成项或风险：<没有则写“无”>。
临时 Skill：<路径；当前上下文已直接掌握｜已因压缩、恢复或外部变化重新读取>。
后续使用：<同一会话如何复用；新会话如何重新读取或安装>。
持久化状态：<本次运行的临时产物，不保证跨会话保留｜已按用户要求安装到指定位置>。

失败时发送同阶段的“执行中止”消息，说明停止位置、仍然有效的成果、已产生的文件或外部状态，以及最安全的下一步。不得静默失败。

临时 Skill 的使用与持久化

区分三种使用场景：

• 当前连续运行：主 Agent 直接生成并掌握最终内容时，校验后即可执行，不需要重新读取或安装。
• 同一会话稍后复用：上下文和文件均未变化时可继续使用；经历压缩、恢复、外部修改或版本不确定时，先确认文件存在并重新读取。
• 新会话、其他 Agent 或其他平台：临时文件不会自动进入新上下文。必须明确提供文件路径并要求读取，或将它安装到该运行时可发现的 Skill 目录。否则只能得到普通模型执行，不能保证保留组合逻辑和边界。

临时目录可能被运行时清理，不承诺跨会话存在；不把“生成成功”视为“已经持久化”。

用户明确要求持久化时，主 Agent 应在环境允许的情况下直接完成，不要求用户手工复制：

1. 把任务专用内容泛化为可重复使用的适用条件、输入和流程；
2. 删除个人记忆、临时路径、一次性事实和不应传播的信息；
3. 检查被依赖的 Skills、references、scripts 和工具在目标环境是否可用；
4. 确定运行时原生 Skill 目录、Skill 名称和是否存在同名冲突；
5. 向用户说明将写入的位置、主要变化、依赖和重新加载要求；同名覆盖或范围扩大时必须再次确认；
6. 写入并运行平台可用的 Skill 校验，报告安装路径和使用方式。

如果当前环境没有文件权限、不知道平台 Skill 目录或不支持动态发现，说明限制并给出需要用户完成的最小手工步骤。不要声称已经安装。

持久化后的 Skill 也不一定会自动进入当前上下文。按平台能力重新读取、刷新 Skill catalog、重载项目或开启新会话，并明确告诉用户如何调用。建议在重复稳定复用后再持久化；无论何时持久化，都必须获得用户明确授权。

最低完成检查

• 五个阶段均有用户可见的状态消息。
• 对运行时可见 catalog 完成 metadata 初筛，研究所有被识别为有实质贡献的 Skill，并说明可见性限制。
• 能力缺口和关键衔接均已覆盖、明确降级或得到用户指引。
• 用户看过组合框架，并完成一次确认或已明确预授权继续。
• 用户能够区分“无需回复”和“必须确认”。
• 未确认的路线性问题没有被擅自推断或执行。
• 临时 Skill 通过校验并保持原始交付边界。
• 交付时已说明当前运行、后续复用和持久化的使用方式。
• 最终结果包含验收证据、剩余风险和权限边界检查。