yy-create-skill

name: yy-create-skill description: > 创建或更新 Skill（技能）。用于创建新技能、更新现有技能或标准化工作流程，不用于创建规则文件或普通文件。

yy-create-skill

描述

帮助用户创建或更新符合规范的 Skill 技能文件，包含完整的目录结构、YAML 元数据和可执行的指令步骤。

Skill 本质上是"可按需加载的任务说明书"，用于复用复杂流程。关键特点：

1. 自动发现：会被自动发现，只在相关时加载，避免上下文膨胀
2. 精确触发：description 要精确，避免误触发
3. 明确边界：必须有使用场景（触发条件和不应触发场景）
4. 指令清晰：步骤明确，最后一步描述输出格式
5. 决策显式：隐含的分支选择转化为明确规则

使用场景

• 用户想要创建新技能
• 用户想要更新现有技能
• 用户需要把某个工作流程标准化为技能
• 用户想把某个功能打包成可复用的技能

不应触发：

• 用户只是询问技能是什么
• 用户要求创建普通文件
• 用户要求创建规则文件

指令

步骤 1. 捕获意图

理解用户的需求，分三个阶段完成意图捕获：识别意图类型、判定适用范围、补齐必要信息。

意图识别

确定是创建新技能还是更新现有技能：

决策分支：

• 用户明确指定（如"创建一个 XX 技能"、"更新 YY 技能"）：按用户指定执行
• 用户未明确指定：根据以下信号推断：
  • 提及"创建"、"新建"、"帮我搞个"等 → 创建新技能
  • 提及现有技能名称或"更新"、"修改"、"优化"等 → 更新现有技能
• 推断结果不确定时：向用户确认

范围判定

确定技能的适用范围是通用还是专有，此判定结果作为步骤 5 的输入约束。

决策分支：

• 用户明确指定：按用户指定的范围执行
• 用户未明确指定：根据以下信号推断并确认：
  • 技能名称包含通用动词（如"注释"、"格式化"、"审查"）且未限定技术栈 → 倾向通用
  • 技能名称包含特定技术栈限定（如"Vue"、"React"、"Python"）→ 倾向专有
  • 用户描述中提及多种语言/工具 → 倾向通用
  • 用户描述中只提及单一技术栈 → 倾向专有
• 推断结果不确定时：向用户确认"此技能是通用技能（适用于多种语言/工具）还是专有技能（限定于特定技术栈）？"

信息补齐

根据意图类型补齐必要信息：

创建新技能：

• 需求明确：用户同时指定了技能名称和至少一个触发场景（如"创建一个格式化代码的技能，在提交前格式化"），记录技能名称和触发场景
• 需求模糊：用户只指定了技能名称或只指定了用途（如"帮我搞个技能"、"创建一个 lint 技能"），使用以下引导问题补充信息：
  1. 这个技能应该让 AI 助手能做什么？
  2. 何时应触发这个技能？

更新现有技能：

• 读取现有 SKILL.md 内容
• 根据用户输入确定更新范围：
  • 明确指定：用户明确说明要更新的部分（如"更新 description"、"修改步骤 3"），按用户指定范围更新
  • 未明确指定，但目标技能明确：默认按"补充+优化"策略处理，进入步骤 2 等待用户确认
  • 目标技能或任务目标仍不明确：使用最少必要的问题补齐缺失信息，再进入步骤 2

步骤 2. 确认方案与计划

强制规则：无论用户的请求是什么形式，必须先展示方案与计划，并等待用户明确确认后才能进入步骤 3。任何情况下都不得跳过此确认步骤，也不得在同一轮中展示计划后直接继续执行。

决策分支：

• 当前环境可用 yy-mode-plan：优先使用该技能创建方案方向和计划，并等待用户确认
• 当前环境不可用 yy-mode-plan：使用以下本地最小确认流程
  • 方向不明确时：先展示方案方向，等用户确认方向正确后，再展示计划
  • 方向明确时：直接展示计划
  • 展示计划后必须等待用户确认，才能进入步骤 3
  • 展示方案方向时，至少包含以下内容：
    • 目标：一句话说明将要完成的内容
    • 方法：高层策略（1-3 句）
    • 涉及范围：将要创建或修改的技能文件、辅助目录或模板资源
    • 待确认点：仍需用户决策的关键选择（如有）
  • 方案方向结尾必须明确提示用户确认方向是否正确，或提出调整意见
• 计划中至少说明操作类型、目标技能目录、目标文件路径、是否涉及辅助目录、内容生成或更新策略和影响范围

步骤 3. 确定技能目录

• 创建新技能：使用小写、短横线分隔的命名方式，遵循以下原则：
  • 名词使用单数形式：如 create-skill 而非 create-skills
  • 优先动宾结构：如 create-skill、read-pdf、lint-code 而非 skills-creator、pdf-reader
• 更新现有技能：直接使用现有技能目录

命名规范详见 resources/skill-guide.md。

步骤 4. 确定输出目录

• 如果用户指定了目录，则在用户指定目录下生成技能
• 如果用户未指定目录，按以下优先级检测已有的技能目录：
  1. .agents/skills/
  2. .claude/skills/
  3. .opencode/skills/
  4. .trae/skills/
  5. skills/
• 无已有目录时，在项目根目录创建 skills/ 目录

步骤 5. 编写 SKILL.md

生成 SKILL.md 的文本内容，并判断是否需要创建辅助目录（templates/、resources/、examples/、prompts/）。此步骤不执行文件写入操作，文件写入在步骤 6 执行。

编写原则和模板请参考 templates/skill-template.md。

默认策略

• description 默认使用 > 折叠式语法（禁止行内写法）
• ## 指令 章节默认使用 ### 步骤 N. 标题 的分步结构，最后一步描述输出格式
• 默认只生成 SKILL.md，不自动创建 examples/、templates/、resources/、scripts/ 目录；prompts/ 按本步骤中的派生产物规则处理
• 仅在以下条件满足时才创建辅助目录：
  • scripts/：技能需要可执行脚本，用户明确要求或技能功能必须通过脚本实现
  • templates/：需要生成特定格式文件，或模板实际内容超过 20 行（计数规则：只统计实际内容行，不含空行、代码块围栏标记行 ```、YAML frontmatter 行）
  • resources/：需要独立的参考文档，且内容不适合放在 SKILL.md 正文
  • examples/：用户明确要求提供示例
  • prompts/：可选派生产物目录，仅用于存放由 SKILL.md 派生出的系统提示词文件；创建新技能时默认不生成，除非用户明确要求；更新现有技能时，仅当 prompts/ 目录已存在且 yy-skill-to-prompt 可用时才更新，不存在则不新增；默认不手写，优先由 yy-skill-to-prompt 生成
• 当技能指令中存在"生成特定格式的输出文件"步骤时，必须在对应步骤中提供格式模板（章节结构、字段名称、占位符说明），确保不同 AI 生成的文件结构一致；模板内容不超过 20 行时内嵌在步骤中，超过 20 行时移至 templates/ 目录并引用

通用技能结构指导

当步骤 1 的范围判定结果为通用时，按以下分层结构组织内容：

1. 通用层：跨目标共用的规则、判断标准、质量原则等，放在 SKILL.md 正文或 resources/ 下的独立文件中（文件名根据内容性质自行命名，如 common-rule.md、common-spec.md、common-convention.md 等）
2. 特定层：各目标独有的语法、格式、惯例等，按目标维度拆分为 resources/ 下的独立文件（如按语言、框架、工具分别建文件）
3. 路由层：SKILL.md 负责根据目标类型路由到对应的特定层文件，并声明优先级规则
4. fallback 机制：必须有兜底规则覆盖未列出的目标，确保技能不因缺少特定层文件而失效

优先级规则：当特定层的规则与通用层冲突时，以特定层的规则优先。此规则必须在 SKILL.md 中显式声明。

反面案例：将所有目标的规则平铺写在 SKILL.md 正文中，既无通用/特定分层，也无 fallback，导致技能只能覆盖已列出的目标。

专有技能边界检查

当步骤 1 的范围判定结果为专有时，检查以下边界：

• description 和使用场景应明确限定技术栈范围，不使用"支持多种语言"等泛化表述
• 不应出现覆盖多个目标的通用性描述（如"适用于所有编程语言"）
• 如专有技能后续需要扩展为通用技能，应通过更新流程重新评估范围，而非在专有技能上直接叠加通用内容

编写约束

编写 SKILL.md 时需遵循以下约束，详细规范和示例见 resources/skill-guide.md：

• description：遵循结构化公式 <动词引导的动作>. <何时用 / 何时不用>.，控制在 2-3 句话，排除条件写在 description 中，不得出现其他技能名
• 使用场景：触发与排除条目必须贴近技能本质，排除场景必须是 AI 真实可能误触发的相邻场景
• 能力一致性：适用场景必须能在指令中找到执行路径，不适用场景必须与指令无交集
• YAML frontmatter：只允许 name 和 description 两个字段
• 步骤分层：判断步骤只编排，执行步骤包含具体命令；前置动作写在代码块最前面；条件限定需有清晰论据
• 决策点显式化：明确条件与对应行为，避免模糊表述；避免隐性技能依赖
• 项目级规则边界：不重复项目级规则文档已有的通用约定，识别可回流内容
• 受众意识：只写 AI 需要知道的，不罗列底层实现细节
• 派生技能：采用薄覆盖层写法，只声明覆盖规则，不重复源技能内容

更新技能策略

更新现有技能时，遵循以下原则：

• 先读取再修改：读取现有 SKILL.md 和辅助文件内容，理解当前结构后再修改
• 默认补充+优化：保留现有内容，补充缺失部分，优化表达和结构；若用户明确要求"完全重写"，则覆盖生成
• 同步检查辅助文件：修改 SKILL.md 后，检查 examples/、templates/、resources/、prompts/ 中的文件是否需要同步更新。默认只修改 SKILL.md 和必要的派生产物；若本次变更导致辅助文件中的步骤编号、章节名称、字段名或提示词内容与新的 SKILL.md 失配，则同步更新相关辅助文件
• description 独立评估：更新其他章节时，单独评估 description 是否需要同步调整，避免 description 混入实现细节
• 必须按步骤 2 处理方案与计划确认，在用户明确确认前不得执行后续步骤

步骤 6. 创建目录结构

根据步骤 5 的判断结果，执行以下操作：

创建新技能

1. 创建技能目录（如 skills/技能名称/）
2. 写入 SKILL.md 文件
3. 如步骤 5 判断需要辅助目录，同时创建相应目录和文件

目录结构规范详见 resources/skill-guide.md。

更新现有技能

1. 读取现有目录结构
2. 默认只修改 SKILL.md、必要的派生产物或用户指定的部分
3. 若本次变更导致辅助文件失配，则同步更新相关辅助文件
4. 不删除已有辅助文件

生成提示词派生产物

创建或更新 SKILL.md 后，按以下决策分支处理 prompts/skill-prompts.md：

创建新技能时：

• 用户未明确要求：默认跳过 prompts/ 目录生成，不创建该目录
• 用户明确要求且 yy-skill-to-prompt 可用：使用 yy-skill-to-prompt 生成 prompts/skill-prompts.md
• 用户明确要求但 yy-skill-to-prompt 不可用：提示用户安装 yy-skill-to-prompt，或确认是否使用本技能内的最小回退流程手动生成

更新现有技能时：

• prompts/ 目录已存在且 yy-skill-to-prompt 可用：使用 yy-skill-to-prompt 更新 prompts/skill-prompts.md
• prompts/ 目录已存在但 yy-skill-to-prompt 不可用：跳过更新，不阻塞技能更新流程
• prompts/ 目录不存在：不新增该目录，即使 yy-skill-to-prompt 可用也不生成

步骤 7. 验收

创建或更新技能后，按 resources/skill-guide.md 中的验收清单逐项检查，重点关注：

• description 遵循结构化公式，包含排除条件
• 使用场景贴近技能本质，排除场景是真实可能误触发的相邻场景
• 指令步骤完整可执行，决策点显式化
• 文件间一致性（SKILL.md 与辅助文件描述一致）
• YAML 格式正确（仅 name 和 description 两个字段）
• 能力一致性（适用场景有执行路径，不适用场景与指令无交集）

创建技能后还需检查：文件命名规范（kebab-case）、目录名称合规、代码示例包含语言标签。

更新技能后还需检查：description 未混入执行细节、辅助文件是否需要同步更新。

步骤 8. 输出结果

输出以下内容：

1. 创建/更新结果：技能名称和操作类型（创建/更新）
2. 目录结构：生成的文件树（使用 tree 或 text 代码块）
3. 提示词派生产物状态：说明是否生成或更新 prompts/skill-prompts.md，以及使用的是 yy-skill-to-prompt 还是本地回退流程；如未生成，说明跳过原因
4. SKILL.md 内容摘要：
   • description 文本（完整复制）
   • 指令步骤概要（格式：步骤编号. 步骤名称，如 步骤 1. 捕获意图、步骤 2. 确认方案与计划、步骤 3. 确定技能目录）
5. 不输出完整 SKILL.md 正文，除非用户明确要求查看完整内容
6. 可回流规则建议（如有）：列出本次识别出的可回流规则、用户决策结果（回流/写入技能）；如用户选择回流，附上可直接粘贴的话术，以及建议的写入位置（由用户最终决定）

安全边界

• 仅在目标技能目录及用户明确授权的文件范围内创建或修改文件；若需要扩展到其他目录，先说明原因并等待确认
• 更新现有技能时，默认不删除已有辅助文件；只有用户明确要求删除，或文件已被本次统一方案替代且删除范围已确认时，才可执行删除
• 当前环境未安装 yy-skill-to-prompt 时，不得仅为补齐目录结构而手写 prompts/skill-prompts.md；只有用户明确要求必须生成提示词文件，并确认使用本地最小回退流程时，才可手动生成
• 未在步骤 2 获得用户对方案与计划的明确确认前，不得创建、覆盖或改写任何文件；目标、范围或策略不明确时应先回到步骤 1 补齐信息，再进入步骤 2 等待确认

相关资源

本技能包含以下辅助资源：

• examples/input.md：输入示例，展示用户如何请求创建技能
• examples/output.md：输出示例，展示创建技能后的预期结果
• templates/skill-template.md：基础技能模板
• resources/skill-guide.md：技能编写完整指南（命名规范、YAML 语法、章节编写原则、交互设计、验收清单）

目录结构规范

技能支持的目录结构和命名规范详见 resources/skill-guide.md。