| 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/") | 用通用表述(如"现有服务/模块"、"命令入口") |