| name | skill-generator |
| description | 当用户提出想根据某个需求、工作流、角色职责或项目约定创建一个全新的 Agent skill 时使用；先深度理解用户目标、触发场景、输入输出、执行边界和质量标准，在需求不清时主动追问，最终生成结构清晰、触发准确、流程可执行、可维护的 `.ai/skills/<skill-name>/SKILL.md`。 |
| when_to_use | 当用户说'帮我生成一个 skill'、'创建一个 skill'、'把这个流程沉淀成 skill'、'根据我的需求写一个 skill'、'做一个用于 X 的 skill'，或希望把某类重复工作、项目流程、规范约束、文档生成流程、代码执行流程固化为可复用 Agent 能力时激活。若用户是优化已有 skill，转 skill-optimizer；若用户只是要执行某项业务任务而不是沉淀 skill，则按对应业务 skill 或普通实现流程执行。 |
Skill Generator
1. 定位
本 skill 用于把用户的原始想法、工作流、项目规范或重复任务，沉淀为一个新的 Agent skill。
生成的 skill 必须让另一个 Agent 在未来遇到同类任务时能够：
- 准确判断何时触发
- 理解任务目标与不做什么
- 识别哪些信息缺失必须追问
- 按清晰步骤执行
- 产出固定位置、固定结构、可验收的交付物
- 与本项目已有
.ai/skills/、AGENTS.md、文档阶段流转保持一致
它不负责：
- 优化已有 skill（转
skill-optimizer）
- 替用户直接完成业务实现，除非用户明确要求同时创建 skill 并执行一次
- 创建 README、CHANGELOG、安装说明等非 skill 必需文件
2. 强制原则
2.1 先理解需求，再写 skill
创建文件前必须先从用户请求中提取：
- 这个 skill 要解决什么重复问题
- 未来由谁触发、在什么场景触发
- 输入材料来自哪里
- 输出产物是什么、落在哪里
- 是否会修改代码、文档、配置、数据库或外部系统
- 哪些需求已确认，哪些只是推测
- 与现有 skill 是否重叠、冲突或前后衔接
不得只根据 skill 名称或一句模糊描述直接写文件。
2.2 不确定就追问
以下任一情况出现时，必须先问用户，不得直接落文件：
- 无法确定新 skill 的名称或主要用途
- 不清楚输出是只展示草案，还是写入
.ai/skills/
- 不清楚 skill 是创建全新能力，还是优化已有 skill
- 输出路径、模板、阶段状态或文档目录会影响项目流程
- skill 会要求 Agent 修改代码、提交、迁移数据库、操作外部服务等高影响动作
- 触发条件可能与现有 skill 大量重叠
提问规则：
- 每轮优先问 1 个最阻塞的问题。
- 问题必须说明为什么影响后续生成。
- 用户明确说"按你的判断直接生成"时，可以基于项目现有约定做保守假设，并在最终回复中说明。
2.3 写成可执行规则，不写空泛提示词
新 skill 不应只写"深入分析""保证质量""灵活处理"等泛化表达。每个关键要求都要转化为：
- 明确进入条件
- 明确停止条件
- 明确文件位置
- 明确执行步骤
- 明确输出模板或章节
- 明确质量门禁
3. 必读上下文
创建新 skill 前至少读取：
AGENTS.md.ai/skills/ 下与目标能力相近的 skill- 若用户要求参考某个历史 skill，必须读取该 skill 的
SKILL.md
按需读取：
.ai/prompts/project.mdproject_info.md- 相关 docs 目录、模板文件、阶段产物
- 与 skill 目标相关的真实代码入口或配置
只读取支撑 skill 设计的最小上下文，不做无关代码审查。
4. 输出位置与结构
默认输出位置：
.ai/skills/<skill-name>/SKILL.md
命名规则：
<skill-name> 使用小写英文、数字和短横线- 名称要表达能力边界，不使用过宽名称，例如
assistant-helper
- 若用户只给中文名称，应转换为稳定英文 slug，并在正文标题保留可读名称
默认只创建 SKILL.md。
只有在确有必要时才创建附加资源：
templates/ 或单个模板文件：当输出文档有固定格式references/：当详细参考内容过长，需要按需读取scripts/：当有可复用、确定性的脚本逻辑
不得创建无关的 README.md、QUICK_START.md、CHANGELOG.md。
5. SKILL.md 必备结构
新 skill 至少包含以下内容。
5.1 Frontmatter
---
name: <skill-name>
description: <一句话说明何时触发、做什么、输出什么>
when_to_use: "<典型触发语句、适用场景、排除场景>"
---
要求：
description 是触发入口，必须写清"何时使用"。when_to_use 覆盖典型用户说法和不适用场景。- 不把关键触发条件只藏在正文里。
5.2 正文推荐章节
# <Skill Title>
## 1. 定位
说明 skill 负责什么、不负责什么、最终帮助 Agent 产出什么。
## 2. 触发边界
### 2.1 适合使用
- ...
### 2.2 不适合使用
- ...
## 3. 输入前提
- ...
## 4. 必读文件 / 上下文
- ...
## 5. 输出位置
```text
...
```
## 6. 输出内容要求
- ...
## 7. 工作步骤
### 步骤 1：...
### 步骤 2：...
## 8. 质量门禁
- ...
## 9. 与其他 skill 的衔接
- ...
可根据任务删减或增补章节，但必须保留"定位、触发边界、工作步骤、输出要求、质量门禁"。
6. 生成流程
步骤 1：识别用户真实目标
把用户的自然语言需求整理为：
- 目标能力
- 典型触发语句
- 输入材料
- 输出产物
- 执行动作
- 约束与禁止事项
- 待确认问题
如果目标能力本质上是在优化已有 skill，停止并转 skill-optimizer。
步骤 2：检查现有 skill
在 .ai/skills/ 中查找相近能力：
- 是否已有可复用或可扩展 skill
- 是否需要新增，还是应该修改已有 skill
- 新 skill 的触发条件是否会与已有 skill 冲突
- 是否需要在"与其他 skill 的衔接"中写明转交关系
若新增 skill 会明显重复已有 skill，先向用户说明并确认。
步骤 3：确定 skill 契约
在写文件前形成简短契约：
- skill 名称
- 使用场景
- 输入前提
- 输出位置
- 关键执行步骤
- 质量门禁
如果用户已明确要求直接生成，契约可以内化为编辑前判断；如果存在阻塞性不确定，必须先问。
步骤 4：编写 SKILL.md
写作要求：
- 使用项目现有中文风格和章节编号
- frontmatter 简洁但触发条件完整
- 正文以可执行流程为主，不写提示词工程理论
- 对模糊需求设置"必须追问"的规则
- 输出模板要足够明确，但不要臃肿
- 与项目目录、阶段、文档同步规则保持一致
步骤 5：自检
创建后逐项检查：
- YAML frontmatter 是否完整且可解析
description 是否能准确触发when_to_use 是否包含排除场景- 是否明确"适合 / 不适合使用"
- 是否定义输入前提、输出位置和工作步骤
- 是否定义不确定时的追问规则
- 是否有质量门禁
- 是否与已有 skill 重叠或冲突
- 是否创建了多余文件
步骤 6：交付说明
最终回复说明：
- 新增了哪个 skill
- 它解决什么问题
- 保存路径
- 是否存在假设或后续可补充点
7. 质量门禁
生成的新 skill 出现以下任一情况即不合格，必须继续修订：
- 触发条件含糊，未来容易误触发或漏触发
- 只写原则，没有可执行步骤
- 没有说明输出位置或输出结构
- 没有说明何时必须追问用户
- 没有与已有 skill 的边界说明
- 把未确认推测写成事实
- 创建了 README、安装说明等无关文件
- 章节过度臃肿，大量重复通用提示词表达
8. 与其他 skill 的衔接
- 创建新 skill：使用本 skill。
- 优化已有 skill：转
skill-optimizer。
- 创建需求 brief：转
brief-generator。
- 生成验收契约：转
acceptance-generator。
- 生成技术方案：转
technical-design。
- 按方案实现代码：转
implementation-execution。
如果用户同时要求"创建 skill 并用它处理一次任务"，应先创建 skill，再按新 skill 的规则执行该任务；若执行任务前仍有关键需求不明确，先追问。
