Skill 拆解

Skill 的完整结构

my-skill/
├── SKILL.md          # [必需] 核心定义
├── scripts/          # [可选] 可执行脚本
│   ├── process.py
│   └── upload.js
├── references/       # [可选] 详细参考文档
│   ├── guide.md
│   └── examples.md
├── assets/           # [可选] 静态资源
│   ├── template.json
│   └── config.yaml
└── agents/           # [可选] 平台扩展配置
    └── openai.yaml   # OpenAI/Codex 的界面、调用策略和依赖元数据

SKILL.md 详解

Frontmatter（元数据）

---
name: code-reviewer               # [可选] 唯一标识符，默认为目录名
description: |                    # 触发条件和功能描述（最重要的字段）
  审查代码是否符合团队规范。
  使用场景：用户请求 review 代码、提交 PR 前、或提到"代码审查"时。
when_to_use: |                    # [可选] 补充触发条件，追加到 description 之后
  当用户提到"review"、"代码检查"、"PR 审查"时触发。
---

关键字段说明：

name（可选）

小写字母、数字和连字符，最长 64 字符
省略时默认使用目录名
简短且描述性

示例：

✅ code-reviewer
✅ multi-platform-adapter
❌ Code Reviewer（有空格）
❌ cr（太简短）

description（必需）

这是最重要的字段，决定 AI 什么时候调用这个 Skill。 Frontmatter 会被加载到系统提示词中，AI 根据 description 来判断当前任务是否需要调用这个 Skill。

写好 description 的三条原则：

同时说明"做什么"和"什么时候用" — 缺一不可
包含用户实际会说的话（触发词） — 包括技术术语和口语表达
控制长度，不超过 1536 字符 — 过长会占用上下文窗口，2-4 句话即可

禁止事项：

不能包含 XML 尖括号 < >，会导致解析错误
name 不能有空格或大写，只能用小写字母、数字和连字符

示例对比：

❌ 不好的 description：

description: Review code

太简短，AI 不知道什么时候用
没有触发关键词

❌ 不好的 description：

description: 帮助处理项目。

太模糊，几乎任何任务都能匹配

✅ 好的 description：

description: |
  审查代码的安全性、性能和代码风格。
  使用场景：
  - 用户请求 review 代码
  - 提交 PR 前的检查
  - 提到"代码审查"、"code review"、"检查代码"时
  重点关注：SQL 注入、XSS、性能瓶颈、命名规范

✅ 好的 description（含负向说明，避免过度触发）：

description: |
  用于 CSV 文件的高级数据分析（统计建模、回归分析、聚类）。
  不适用于简单数据查询（请使用 data-viz Skill）。

会员专属文章试读

试读结束，开通会员后继续阅读

完整内容还有更多实操细节、踩坑记录和可直接复用的清单。开通会员就能继续看。

登录后开通查看会员权益

支付成功后回到文档即可阅读全文。