| name | my-create-skill |
| description | 引导创建符合团队约定的 SKILL.md 文件。 仅当用户明确说出"使用 my-create-skill"或"启动 my-create-skill"时触发。 不适用于任何隐式场景。 |
My Create Skill
引导用户创建高质量 skill，遵循团队统一约定。所有输出必须符合 AGENTS.md 规范。
触发约束
此 skill 仅通过显式调用触发。
⛔ 不触发的场景
- 用户提到"创建 skill"、"写个模板"等但未提及 my-create-skill
- 完成任务后"顺便"生成 skill
- 用户未显式引用 @my-create-skill
✅ 触发条件
必须同时满足：
- 用户明确说出"使用 my-create-skill"或"启动 my-create-skill"，或显式引用 @my-create-skill
- 用户提供了 skill 想法、草稿或明确需求
Skill 解剖
每个 skill 是一个目录，包含 SKILL.md 和可选资源：
skill-name/
├── SKILL.md 必需 — 主指令
├── scripts/ 可选 — 可执行脚本（确定性任务）
├── references/ 可选 — 深度参考文档
└── assets/ 可选 — 输出模板、图片等资源
三级渐进加载：元数据（常驻） → SKILL.md body（触发时） → 参考文件（按需）。
默认约定
以下是创建 skill 的默认方案，大部分情况适用。用户明确要求时可覆盖。
1. 触发方式
默认手动触发。 description 和 body 中默认声明手动触发条件。
用户明确要求自动触发时：
- 提醒风险：可能被意外调用、触发时机不可控
- 用户确认后，按用户要求创建自动触发 skill
2. Frontmatter 规范
只保留开放标准的 name + description，禁止 when_to_use、argument-hint、arguments 等非标准字段。
手动触发默认格式：
---
name: skill-name
description: >-
{1句话描述功能，第三人称，关键词密集}。
仅当用户明确说出"使用 {skill-name}"或"启动 {skill-name}"时触发。
不适用于任何隐式场景。
---
自动触发格式（用户明确要求时）：
---
name: skill-name
description: {1句话描述功能，第三人称，关键词密集}
---
在 body 中说明自动触发条件。
name：kebab-case，≤64 字符，小写字母+数字+连字符
description：≤1024 字符，必须包含 WHAT（功能）+ WHEN（触发声明，手动或自动）
3. 触发约束段落（手动触发时）
手动触发 skill，标题之后、正文之前，需包含：
## 触发约束
此 skill **仅通过显式调用触发**。
### ⛔ 不触发的场景
- 用户提到相关功能但未提及 {skill-name}
- 日常文档编辑、代码编写、完成任务后的"顺便"操作
- 用户未显式引用 @{skill-name}
### ✅ 触发条件
必须同时满足：
1. 用户明确说出"使用 {skill-name}"或"启动 {skill-name}"，或显式引用 @{skill-name}
2. 用户提供了明确需求或上下文
⛔ 场景第一条根据 skill 功能定制具体关键词。
4. 内容约束
- SKILL.md 正文 ≤ 500 行
- 文件引用不超过一层深度（相对路径，从 SKILL.md 出发）
- 用祈使句（动词优先），不用第二人称
- 不编造未验证的模式，不使用空占位符
- 举例用通用占位符（如
{相关目录}），不用具体项目目录名（如 material/）
- 指标用可选维度，不写固定要求（如"可选：规模/时间/质量维度"，不是"必须统计文件数量"）
创建流程
Phase 1: 意图确认
确认以下信息：
- 功能 — 这个 skill 解决什么问题？
- 名称 — kebab-case，动词/动名词优先
- 触发词 — 用户会说什么话时用到它？
- 存储位置 — 个人全局还是项目级？
- Codex:
~/.codex/skills/ 或项目 .agents/skills/
- Claude Code:
~/.claude/skills/ 或项目 .claude/skills/
- Cursor:
~/.cursor/skills/ 或项目 .cursor/skills/
- 其他编辑器: 查阅对应文档
- 是否需要脚本/参考/资源 — 基于场景判断
如果有对话上下文已包含这些信息，直接复用，不用重复提问。
Phase 2: 结构设计
根据意图决定目录结构：
| 场景 | 结构 |
|---|
| 纯知识型 skill | 只需 SKILL.md |
| 需要可执行工具 | 加 scripts/ |
| 有深度参考内容 | 加 references/ |
| 需要输出模板 | 加 assets/ |
不要预设所有目录都需要，按需创建。
Phase 3: 编写
按顺序编写：
- Frontmatter — name + description，严格遵循上方格式
- 触发约束段落 — 复制上方模板，替换 skill-name
- 正文 — 从核心指令开始，保持精简
- 脚本/参考/资源 — 仅在 Phase 2 决定需要时创建
写作原则：
- 解释 why，不是只写 MUST/NEVER — LLM 理解意图后会做得更好
- 给一个优秀示例 > 给五个平庸示例
- 提供默认方案 + 逃生口，不是列出一堆选项让用户选
写作时自检：
- 举例是否过于具体？（如
find material/ → 改为 find {相关目录}）
- 指标是否固定要求？（如"必须统计API调用" → 改为可选维度）
- 步骤是否有执行方法？（如"识别相关目录" → 补充具体方法：关键词推断、查看CLI入口）
- 是否假设项目结构？（如"infra/" → 改为通用表述"现有服务/模块"）
Phase 4: 校验
校验清单：
格式检查：
内容质量检查：
Phase 5: agent 视角检查（可选）
触发条件：skill 涉及多步骤流程或技术细节时执行。
模拟执行：
- 模拟触发场景（用户说什么话触发）
- 按步骤逐一执行
- 检查每个步骤是否有足够信息执行：
- 有具体方法？（不是只有步骤名）
- 有输入输出说明？
- 有验收标准？
- 发现问题时补充方法或模板
输出格式示例：
模拟执行发现问题：
- Phase 1 "识别相关目录" 缺少具体方法
补充：关键词推断 → 查看CLI入口 → 查看数据结构
不符合时修正，符合时跳过此环节。
Phase 6: 存档
- 写出创建好的 skill 文件路径
- 提醒用户：需安装到对应编辑器的 skill 目录才能生效
- Codex:
~/.codex/skills/ 或项目 .agents/skills/
- Claude Code:
~/.claude/skills/ 或项目 .claude/skills/
- Cursor:
~/.cursor/skills/ 或项目 .cursor/skills/
- 建议用户将 SKILL.md 同步到 skill 仓库存档
反模式
| 反模式 | 正确做法 |
|---|
| description 写成流程总结（"先做 X，再做 Y"） | 只写 WHAT + WHEN，流程放 body |
when_to_use、argument-hint 等非标准字段 | 只用 name + description |
| 把所有内容塞进 SKILL.md | 超过 500 行就拆分到 references/ |
| 给一堆选项让 agent 自己选 | 提供默认方案 + 逃生口 |
| 写 "Before August 2025" 类时间敏感内容 | 用 <details> 折叠旧方案 |
| 术语前后不一致 | 选定一个词全文统一 |
泛名如 helper、utils | 具体动词命名如 processing-pdfs |
举例用具体项目目录（如 find material/） | 用通用占位符（如 find {相关目录}） |
| 指标写成固定要求（如"必须统计API调用"） | 用可选维度（如"可选：规模/时间维度"） |
| 步骤只有名称（如"识别相关目录"） | 补充执行方法（关键词推断、查看CLI入口等） |
| 假设项目结构（如"infra/"、"cli/"） | 用通用表述（如"现有服务/模块"、"命令入口"） |
