# Yy Create Skill

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

- Skill: `bulls-cows/yy-create-skill` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add bulls-cows/yy-create-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bulls-cows/yy-create-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: bulls-cows (https://skillmd.com/u/bulls-cows)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bulls-cows/yy-create-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`。