my-create-skill

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

✅ 触发条件

必须同时满足：

1. 用户明确说出"使用 my-create-skill"或"启动 my-create-skill"，或显式引用 @my-create-skill
2. 用户提供了 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: 意图确认

确认以下信息：

1. 功能 — 这个 skill 解决什么问题？
2. 名称 — kebab-case，动词/动名词优先
3. 触发词 — 用户会说什么话时用到它？
4. 存储位置 — 个人全局还是项目级？
   • Codex: ~/.codex/skills/ 或项目 .agents/skills/
   • Claude Code: ~/.claude/skills/ 或项目 .claude/skills/
   • Cursor: ~/.cursor/skills/ 或项目 .cursor/skills/
   • 其他编辑器: 查阅对应文档
5. 是否需要脚本/参考/资源 — 基于场景判断

如果有对话上下文已包含这些信息，直接复用，不用重复提问。

Phase 2: 结构设计

根据意图决定目录结构：

场景	结构
纯知识型 skill	只需 SKILL.md
需要可执行工具	加 scripts/
有深度参考内容	加 references/
需要输出模板	加 assets/

不要预设所有目录都需要，按需创建。

Phase 3: 编写

按顺序编写：

1. Frontmatter — name + description，严格遵循上方格式
2. 触发约束段落 — 复制上方模板，替换 skill-name
3. 正文 — 从核心指令开始，保持精简
4. 脚本/参考/资源 — 仅在 Phase 2 决定需要时创建

写作原则：

• 解释 why，不是只写 MUST/NEVER — LLM 理解意图后会做得更好
• 给一个优秀示例 > 给五个平庸示例
• 提供默认方案 + 逃生口，不是列出一堆选项让用户选

写作时自检：

• 举例是否过于具体？（如 find material/ → 改为 find {相关目录}）
• 指标是否固定要求？（如"必须统计API调用" → 改为可选维度）
• 步骤是否有执行方法？（如"识别相关目录" → 补充具体方法：关键词推断、查看CLI入口）
• 是否假设项目结构？（如"infra/" → 改为通用表述"现有服务/模块"）

Phase 4: 校验

校验清单：

格式检查：

• name 是 kebab-case，≤64 字符
• description 是第三人称，≤1024 字符
• description 包含触发声明（手动触发词或自动触发条件）
• 没有非标准 frontmatter 字段
• 手动触发 skill：触发约束段落存在且格式正确
• ⛔ 场景第一条针对此 skill 定制过
• SKILL.md body ≤ 500 行
• 所有文件引用是一层深度
• 全文使用祈使句，无第二人称

内容质量检查：

• 举例用通用占位符（无具体项目目录名）
• 指标用可选维度（无固定要求）
• 每个步骤有执行方法（agent 知道怎么做）
• 无空占位符内容

Phase 5: agent 视角检查（可选）

触发条件：skill 涉及多步骤流程或技术细节时执行。

模拟执行：

1. 模拟触发场景（用户说什么话触发）
2. 按步骤逐一执行
3. 检查每个步骤是否有足够信息执行：
   • 有具体方法？（不是只有步骤名）
   • 有输入输出说明？
   • 有验收标准？
4. 发现问题时补充方法或模板

输出格式示例：

模拟执行发现问题：
- Phase 1 "识别相关目录" 缺少具体方法
  补充：关键词推断 → 查看CLI入口 → 查看数据结构

不符合时修正，符合时跳过此环节。

Phase 6: 存档

1. 写出创建好的 skill 文件路径
2. 提醒用户：需安装到对应编辑器的 skill 目录才能生效
   • Codex: ~/.codex/skills/ 或项目 .agents/skills/
   • Claude Code: ~/.claude/skills/ 或项目 .claude/skills/
   • Cursor: ~/.cursor/skills/ 或项目 .cursor/skills/
3. 建议用户将 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/"）	用通用表述（如"现有服务/模块"、"命令入口"）