Skill create

Skill: SKILL 创建闭环向导

用于把一个用户意图、领域资料或已有过程沉淀为可触发、可执行、可维护、可迭代的 SKILL。执行时默认追求一次成型的最佳方案，但必须通过排查闭环和评估闭环持续修正，直到达到交付标准。

本地资源与权威顺序

1. SKILL.md frontmatter：只定义技能标识和主要触发描述。
2. SKILL.md 正文：只定义流程、选择规则、门禁、失败处理和交付要求；正文与其他本地文件冲突时，以正文为准。
3. _meta.json：只提供注册与展示元数据，不补充、不覆盖、不改写执行规则。

核心原则

• 先确定边界，再创建内容；先形成最小可用版本，再补强复杂能力。
• SKILL 必须自包含到足以独立执行核心任务；外部引用只能作为可选资料，不得承担核心流程。
• 每个阶段都要有明确输入、动作、输出和通过标准。
• 设计决策与执行修改分开：先给结论让用户审阅，确认后再改。
• 评估不是结束；凡是不达标项都要进入修正，并在修正后重新评估。
• 保持上下文经济：SKILL.md 只放核心流程，细节资料只在阶段 2 判定需要时放入 references/、scripts/、assets/。
• 每次迭代的新增修改必须命中以下至少一项：减少歧义、提升可执行性、增强触发准确性。
• 先按阶段 0 判断任务模式，再选择流程出口；独立评估分流规则只以阶段 0 为准。
• 优化已有 SKILL 时必须保留仍然有效的原始能力；新增规则只允许补足缺口、收窄歧义或增强验收，不得用简化替代能力完整性。
• 评估类输出、摘要字段、内部原始值、等级映射和封顶规则只以阶段 7 为准；其他章节只引用，不另起口径。

交互协议

1. 若用户已经给出足够信息，直接执行，不要把流程拆成多版方案让用户选择。
2. 若缺少关键输入，只问阻塞性问题；一次最多问 3 个问题。
3. 需要用户判断的内容，输出明确结论、理由、建议动作和影响范围，让用户审阅。
4. 用户用“执行、确认、移除、修改、继续、按你的结论处理”等短语确认后，立即执行相应动作。
5. 用户要求“直接落地、直接体现到 SKILL 中”时，跳过方案枚举，直接修改目标 SKILL。
6. 每次修改后都要复查受影响文件，确认没有破坏 frontmatter、触发描述、执行流程和闭环关系。
7. 用户只要求评估、审查、打分或给建议时，不直接修改文件；用户要求“根据评估修正、优化、调整、落地”时，才进入修正优化模式。

标准流程

阶段 0: 立项与边界

输入：

• SKILL 名称或目标能力。
• 使用场景描述。
• 参考资料、代码目录、已有文档或过往对话。
• 目标输出位置；用户已指定时使用用户指定的位置，未指定时使用当前工作区的 skills/{skill-name}/。

动作：

• 将名称规范化为 lowercase kebab-case。
• 明确该 SKILL 解决什么问题、不解决什么问题。
• 识别目标用户、触发语境、典型任务、输入输出和风险边界。
• 按以下顺序判断任务模式；命中后立即停止，不再继续匹配：
  1. archive-only：用户只要求沉淀可复用过程资产，且不要求改动核心 SKILL。直接进入阶段 9；若发现阻塞性结构问题，先说明问题，只有用户确认后才改动核心 SKILL。
  2. fix/optimize：用户要求根据问题清单、评估结论或现有缺陷修正、优化、调整或落地 SKILL。先固化问题清单，再进入阶段 1-8 中受影响的部分。
  3. evaluate-only：用户只要求评估、审查、打分或建议，且不要求直接修改文件。只有满足以下任一条件才保留在本技能内执行：用户明确指定本技能；评估属于当前创建/重构/修正闭环；环境中没有更专门的评估能力。若以上条件全部不满足，且存在更专门的评估能力，则转交更专门的评估能力。进入该模式后，只执行结构扫描、场景走查、门禁检查、评分、问题分级和修正建议，停在评估报告，不修改文件。
  4. create/refactor：其余新建、重构或把领域知识沉淀为 SKILL 的请求，进入阶段 1-8。
• 进入 evaluate-only 后，必须先在内部完成证据采集、门禁检查、场景走查、评分、问题分级和最终判定，再输出单一终局报告；不得边评边把阶段结论追加给用户。

输出：

• 标准化场景描述。
• 能力边界。
• 任务模式与本轮流程出口。
• 成功标准。
• 目录规划。

通过标准：

• 能用一句话说明“何时必须使用此 SKILL”。
• 能列出至少 2 个典型触发请求。
• 能列出至少 1 个不应触发本 SKILL 或应转交专门能力的边界请求。
• 能判断哪些内容属于核心流程，哪些内容只适合放入参考资料。
• 能说明本轮是否会修改文件，以及若会修改，修改范围是什么。

阶段 1: 学习与资料整理

动作：

• 深度阅读用户提供的资料、目录、代码、文档或已有 SKILL。
• 提取对执行有直接价值的信息，避免堆砌背景材料。
• 将知识整理为可供 SKILL 使用的结构化资料。

整理维度按以下顺序执行：

• 任务场景。
• 输入要求。
• 操作步骤。
• 输出格式。
• 质量规则。
• 常见错误。
• 需要用户确认的决策点。
• 可复用脚本、模板或参考材料。

输出：

• 若用户要求保留过程资产，输出 skill-doc-{skill-name}/；若用户已指定承担同一职责的资料目录，则使用该目录，不再并行创建等价目录。
• 创建 SKILL 所需的核心知识清单。

通过标准：

• 已能从资料中抽出稳定流程。
• 已识别必须内置在 SKILL.md 的核心规则。
• 已识别可按需加载的参考内容。

阶段 2: 资源设计

动作：

• 判断是否需要额外资源。
• 只有满足以下任一条件时才创建额外资源：
  • 同一内容需要被重复引用。
  • 存在确定性执行步骤，且仅靠自然语言容易出错或会重复执行。
  • 内容属于长篇资料、规范、示例、查询表或输出素材，不继续放入 SKILL.md。

资源选择按以下固定职责处理：

• SKILL.md：放核心触发、流程、选择规则、质量门禁和失败处理。
• references/：放较长的领域资料、规范、示例和查询表。
• scripts/：放需要确定性执行、容易写错或会重复执行的程序。
• assets/：放模板、图片、字体、样例工程等输出素材。
• agents/openai.yaml：仅在运行环境需要 UI 元数据时创建或更新。

禁止项：

• 不创建无执行价值的 README、安装说明、变更日志或冗余文档。
• 不把一次性对话记录塞进最终 SKILL。
• 不让核心执行流程依赖另一个 SKILL 才能理解。

通过标准：

• 每个资源都有明确用途。
• 没有重复存放同一类信息。
• 删除任意非核心资源不会影响 SKILL 的基础触发和主流程理解。

阶段 3: 生成或更新 SKILL

动作：

• 新建 SKILL 时创建 {skill-name}/SKILL.md。
• 更新已有 SKILL 时先读取现有内容，保留仍然有效的能力，移除过时或耦合内容。
• frontmatter 只保留 name 和 description，除非当前平台已有明确额外字段要求。
• description 必须同时说明能力和触发场景，因为它是主要触发依据。

SKILL.md 必备内容： 按以下顺序组织：

• 核心用途。
• 核心原则。
• 执行流程。
• 用户交互规则。
• 决策点。
• 质量门禁。
• 迭代闭环。
• 失败处理。

质量门禁：

• 结构可加载：SKILL.md 存在，frontmatter 至少包含 name 和 description，目录名、文件名和引用路径可追踪。
• 触发可信：description 同时说明能力和触发场景，且与正文能力一致；至少能匹配 2 个典型请求，并排除阶段 0 已定义的边界请求。
• 主流程可达：执行者只读当前 SKILL 就能知道输入、动作、输出、用户确认点和失败回退路径。
• 边界可控：删除能力、改变触发范围、引入外部依赖、拆分/合并 SKILL 等动作必须先让用户确认。
• 结果可验收：交付前能说明完成了什么、如何验证、还剩什么风险。

写作要求：

• 使用命令式、可执行表达。
• 让下一个执行者读完后知道下一步该做什么。
• 避免泛泛而谈的背景解释。
• 避免“参考某某技能规范”作为核心规则来源；必要规则必须写进当前 SKILL。

通过标准：

• 用户只给典型请求时，执行者能判断是否触发该 SKILL。
• 用户只要求独立评估已有 SKILL 时，执行者能判断是否应转交专门评估能力或进入本技能的 evaluate-only。
• 执行者触发后能按流程完成任务。
• 用户参与点明确，不会在关键决策上自行越权。
• 以上质量门禁均通过，或已把未通过项列入修正闭环。

阶段 4: 统一命名与结构

动作：

• 统一 skill 名称、目录名、文件名、章节名、术语和路径引用。
• 使用 kebab-case 命名目录和文件。
• 将过程资料按步骤编号，例如 01-deep-learn.md、02-collect-organize.md。

检查项： 按以下顺序检查：

• frontmatter name 与目录名一致。
• description 与实际能力一致。
• 所有路径存在或明确为待创建路径。
• 章节顺序符合执行流程。
• 不存在同一概念多种命名。

通过标准：

• 文件结构可预测。
• 引用路径可追踪。
• 用户和执行者都能快速定位核心文件。

阶段 5: 结构排查闭环

执行一次深度排查，重点检查“是否完整、是否自洽、是否可执行”。排查不得只给笼统结论，必须列出问题、影响和建议动作。

排查维度按以下顺序执行：

• 触发准确性：description 是否覆盖阶段 0 已定义的触发场景。
• 边界清晰度：是否知道做什么、不做什么。
• 流程完整性：是否覆盖准备、学习、生成、排查、评估、迭代、归档。
• 自包含性：核心能力是否摆脱不必要外部依赖。
• 可执行性：每一步是否有动作和产出。
• 用户交互：何时询问、何时直接执行、何时等待确认是否明确。
• 资源合理性：是否存在冗余文件、缺失资源或错误归档。
• 维护性：后续修改是否容易定位和验证。

闭环规则：

深度排查 -> 分析决策 -> 用户审阅/确认 -> 执行调整 -> 再次深度排查

退出条件：

• 没有仍未处理且命中阶段 6“必须让用户确认的情况”的结构问题。
• 没有阻塞执行的缺口。
• 剩余问题都可以进入质量评估阶段处理。

阶段 6: 分析决策与用户确认

当发现设计取舍问题时，先分析再执行。

决策输出格式：

结论：...
理由：...
影响范围：...
建议动作：...
需要用户确认：是/否

必须让用户确认的情况：

• 删除已有能力、文件或资源。
• 拆分或合并 SKILL。
• 改变触发范围。
• 引入脚本、外部依赖或新目录结构。
• 对用户原始意图做明显收窄或扩展。

可直接执行的情况：

• 修复格式、命名、路径、错别字，以及当前阶段明文要求但正文缺失的检查项。
• 补充不改变设计方向的质量门禁。
• 强化已有闭环和交互规则。

阶段 7: 质量评估闭环

结构稳定后，从资深 SKILL 设计者和使用者角度评估是否达标。评估必须聚焦当前 SKILL 自身，不依赖与其他 SKILL 比较。

本阶段是唯一评估口径来源；所有分流、摘要、分数、等级和封顶相关规则都以本阶段为准。

任务模式分支：

• evaluate-only：只输出评估结论、证据、风险和修正建议；不得进入文件修改，除非用户随后明确确认。该模式是否由本技能执行，只按阶段 0 的分流规则判断。
• fix/optimize：以已有评估结果或本阶段评估结果为问题基线，逐项修正并复评受影响维度。
• create/refactor：把评估作为交付前门禁，未达标项进入修正闭环。

评分维度按以下顺序执行：

• 规范性：frontmatter、命名、目录结构是否合规。
• 触发性：description 是否准确覆盖阶段 0 的标准化场景描述。
• 完整性：关键阶段和必要规则是否齐全。
• 可执行性：执行者是否能按步骤完成任务。
• 交互性：用户审阅、确认和参与点是否清晰。
• 独立性：核心流程是否自包含。
• 可迭代性：是否有明确回评机制。
• 可维护性：结构是否简洁，资源是否遵守阶段 2 的分配规则。

结论等级：

• 优秀：可直接使用，仅有轻微表达优化空间。
• 良好：可使用，有少量非阻塞优化项。
• 合格：基本可用，但需要修正明显短板。
• 不合格：核心流程、触发或执行能力存在重大缺陷。

评估执行约束：

• 先完成内部判定，再生成对外报告。执行顺序固定为：证据采集 -> 门禁检查 -> 场景走查 -> 评分 -> 问题分级 -> 最终判定 -> 生成报告。
• 评分时区分“内部原始值”和“对外展示值”：内部原始值用于阈值判断、等级映射和封顶规则；展示值只用于可读性展示。
• 内部基线等级按 raw_total 固定映射：
  • raw_total >= 9.0：优秀
  • 7.8 <= raw_total < 9.0：良好
  • 6.5 <= raw_total < 7.8：合格
  • raw_total < 6.5：不合格
• 任何四舍五入、保留位数、格式化展示都不得改变等级；只要内部原始值未达到阈值，就不得因为展示值看起来到达阈值而升档。
• 阈值比较必须严格按数值判断，不得用“接近”“约等于”“显示为”替代真实比较。
• 必须显式防止以下误判：
  • 7.785 显示为 7.8，不得从 合格 跃升为 良好。
  • 8.995 显示为 9.0，不得从 良好 跃升为 优秀。
  • 6.495 显示为 6.5，不得从 不合格 跃升为 合格。
  • 任何低于阈值的值，只要内部原始值未过线，就仍按原区间判级。
• 若需要对外展示分数，必须同时满足两条：
  • 该分数只是最终展示分，不承担判级职责。
  • 摘要中不得把它表述为原始判级依据或中间推导结果。
• 若本轮评估存在门禁失败、未关闭高优问题、证据不足，或当前 SKILL 明文定义的其他封顶规则，必须先应用封顶规则得到最终等级，再决定摘要和正文如何展示；摘要只写最终等级状态，不写“基线等级”“待确认等级”“准最终等级”。

evaluate-only 输出契约：

• 报告必须只有一个终局结论来源；不得同时保留“阶段性结论”“基线结论”“最终结论”三套并列状态。
• 若提供摘要，摘要只能展示最终态字段：
  • 最终等级
  • 交付结论
  • 置信度
  • 关键结论
  • 若正文已对外展示分数，可附最终展示分
• 摘要中禁止出现：
  • raw_total
  • 基线等级
  • 待确认规则
  • 命中规则前的等级状态
  • 四舍五入说明
  • 阶段编号式中间过程
• 评分、基线、命中规则、阈值校验等过程信息只允许放在正文对应章节，不得上浮到摘要。
• 若摘要与正文中的最终判定不一致，以正文重算为准；不得保留旧摘要继续交付。

闭环规则：

评估能力 -> 列出不达标项 -> 逐项修正 -> 验证修改 -> 重新评估

评估报告最小内容：

• 评估模式和证据来源。
• 门禁结果和最终等级。
• 分维度结论或关键维度结论。
• 问题优先级、影响、修正动作和验收标准。
• 是否建议直接修改，以及需要用户确认的原因。

退出条件：

• 综合结论达到“良好”或以上。
• 没有阻塞实际使用的问题。
• evaluate-only 已交付完整评估报告，或用户认可当前交付状态，或明确要求停止。

阶段 8: 验证

动作：

• 读取修改后的 SKILL.md，检查 frontmatter 和正文结构。
• 若有验证脚本，运行验证脚本。
• 若创建或修改了脚本，至少运行代表性测试。
• 若技能复杂且当前平台、用户授权和上层规则均允许使用子代理，可用真实任务做前向测试；测试提示只给任务和技能路径，不泄露预期答案。
• 其余情况一律改用本地场景走查：至少覆盖 1 个正向触发、1 个边界/误触发和 1 个失败/缺资料场景；涉及修正优化时，必须追加 1 个与已修问题直接相关的回归场景。

验证清单： 按以下顺序检查：

• name 只含 lowercase、数字和 hyphen。
• description 能独立触发技能。
• description 能排除独立评估已有 SKILL 且应由专门评估能力处理的边界请求。
• 正文不依赖未说明资源。
• 所有用户确认点明确。
• 两个闭环都能回到检查或评估。
• 没有无关文档或无效资源。
• 评估摘要只包含最终态信息，不暴露 raw_total、基线等级或其他中间判定变量。
• 任一阈值比较都基于未四舍五入的内部原始值，展示值不会造成等级跃升。
• 不存在 7.785 -> 7.8 -> 良好、8.995 -> 9.0 -> 优秀、6.495 -> 6.5 -> 合格 这类由展示值导致的越级判定。

阶段 9: 归档与沉淀

当本轮创建过程产生可复用方法时，才归档过程资产。

归档内容：

• 有复用价值的提示词模板。
• 关键决策问题及分析框架。
• 评估维度和修正规则。
• 能明显提升下次创建效率的过程记录。

归档目录建议：

• prompt-step/{skill-name}/：存放过程提示词。
• skill-doc-{skill-name}/：存放整理后的领域资料。

不归档：

• 临时推理。
• 重复聊天记录。
• 只对本轮有效的中间草稿。

失败处理

• 资料不足：说明缺口，并只询问继续所必需的信息。
• 用户目标过宽：收敛为一个主 SKILL，并把可拆分能力列为后续候选。
• 现有 SKILL 在阶段 5 或阶段 7 已确认存在阻塞执行的缺口：保留有效意图，重构执行流程。
• 发现核心执行流程依赖外部资料才能理解：将核心规则内化，外部资料改为阶段 2 下的参考资源。
• 修改后出现新问题：回到结构排查闭环，不进入最终交付。
• 用户要求一次到位：仍然执行内部排查和评估，但对外只交付最终结果。

最终交付格式

按任务模式选择交付格式：

• create/refactor：说明创建或重构了什么核心能力、目标 SKILL 路径、目录和资源如何组织、验证了什么、仍有什么风险。
• evaluate-only：若包含摘要，只写最终等级、交付结论、置信度、关键结论，以及在正文已对外展示分数时附最终展示分；正文再说明关键证据、主要问题、修正优先级和复评入口，不输出修改清单，并说明本次为何满足阶段 0 的保留条件而由本技能处理。
• fix/optimize：说明修正了哪些问题、保留了哪些原能力、触发/流程/交互/验收如何增强、验证了什么、仍有什么风险。
• archive-only：说明归档了哪些可复用资产、放在什么位置、后续如何复用。

最低交付项： 按以下顺序输出：

• 目标 SKILL 路径或归档路径。
• 本轮任务模式和能力边界。
• 新增、修改或保留的核心能力。
• 验证方式和验证结论。
• 残留风险、未处理项或复评入口。
• 若本轮涉及评估输出，必须保证摘要与最终判定一致，且所有阈值比较均基于内部原始值而不是展示值。

不要输出多版方案；除非用户明确要求，不要把内部草稿、备选路径或低价值过程细节展开给用户。