提供一份可直接复用的 SKILL.md 完整模板,帮助你快速搭出 Skill 的标准结构。
内容摘要
> 附录 B:SKILL.md 完整填空模板
附录 B:SKILL.md 完整填空模板
复制适合你水平的模板,填入
[占位符]部分即可。 每个模板后面都有详细解释,告诉你为什么这样写。
适合场景:快速验证想法、内部自用、逻辑简单的任务。
---
name: [your-skill-name]
description: "[做什么]。当用户需要[什么时候用]时使用。"
---
[用自然语言写操作指令,告诉AI怎么完成任务]
name —— 这是你的 Skill 的身份证号。
description —— 这是 AI 决定"要不要加载"的唯一依据。
正文指令 —— 这是 AI 加载后实际执行的步骤。
---
name: commit-helper
description: "生成规范的 Git 提交信息。当用户需要写 commit message、提交代码、描述改动时使用。"
---
根据当前 git diff 的内容,生成一条规范的提交信息。
格式要求:type(scope): description
type 只用 feat/fix/docs/style/refactor/test/chore 之一。
description 用中文,不超过 50 字符。
这个例子虽然只有 5 行,但已经覆盖了关键信息:
适合场景:需要控制输出格式、有一定复杂度的任务、分享给团队使用。
---
name: [your-skill-name]
description: "[做什么]。当用户需要[触发词1]、[触发词2]、[触发词3]时使用。输出包含[输出包含什么]。"
---
## 操作步骤
1. [第一步:理解用户要什么]
2. [第二步:怎么做]
3. [第三步:输出什么格式]
## 输出格式
[描述期望的输出样子,越具体越好]
- 字数要求:[如300-500字]
- 结构要求:[如标题+正文+标签]
- 风格要求:[如口语化/专业/幽默]
## 示例
[给AI看一个好的输出样例]
description(标准版) —— 相比最小模板,这里需要更多触发词和输出说明。
操作步骤 —— 把任务拆成步骤,AI 执行时不容易遗漏。
输出格式 —— 这是控制 AI 输出质量的关键。
示例 —— 一个好的示例顶一百句描述。
---
name: xiaohongshu-seeding-note
description: "生成小红书种草笔记。当用户需要写小红书、种草推荐、产品推荐笔记、好物分享时使用。输出包含标题、正文、标签。"
---
## 操作步骤
1. 确认用户要推荐的产品或服务,以及目标人群
2. 如果用户没有给出具体卖点,从产品的 3 个核心优势出发构思
3. 按照下面的输出格式生成笔记
## 输出格式
- 字数要求:正文 300-600 字
- 结构要求:
- 标题:15 字以内,包含一个吸引眼钩的词(如"绝了""太香了""后悔没早买")
- 正文:开头抛痛点 → 中间讲体验 → 结尾给建议
- 标签:5-8 个,包含品类标签和场景标签
- 风格要求:口语化、亲切、像在跟闺蜜聊天
- emoji:每段 1-2 个,不要过多
## 示例
**标题**:这个平价面霜太香了 干皮姐妹冲
**正文**:
作为一个大干皮,冬天真的是我的噩梦。脸上起皮、卡粉,涂什么都不服帖。
直到我发现了这个宝藏面霜!质地像冰淇淋一样,上脸秒吸收,完全不油腻。我一般晚上厚涂一层当睡眠面膜用,第二天早上脸软软嫩嫩的。
最让我惊喜的是它的保湿持久度。以前到下午脸就开始紧绷,现在一整天都很水润。而且这个价格,学生党也完全没压力。
推荐给所有干皮姐妹,秋冬必备!
**标签**:#平价面霜 #干皮救星 #护肤好物 #学生党护肤 #秋冬必备 #保湿面霜
适合场景:高要求任务、AI 容易犯错的场景、需要稳定输出的生产环境。
---
name: [your-skill-name]
description: >
[做什么]。
当用户需要[触发词1]、[触发词2]、[触发词3]时使用。
输出包含[输出包含什么]。
---
## 操作步骤
1. [第一步]
2. [第二步]
3. [第三步]
4. [第四步(如果有)]
## 输出格式
[详细描述输出格式]
- 字数:[范围]
- 结构:[组成部分]
- 风格:[语气/调性]
- 特殊要求:[如使用Mermaid/表格/代码块]
## 示例
[好的输出样例1]
[好的输出样例2(可选)]
## 反模式(不要做什么)
- 不要[常见错误1]
- 不要[常见错误2]
- 不要[常见错误3]
## 检查清单(AI输出前自查)
- [ ] [检查项1]
- [ ] [检查项2]
description(完整版) —— 用 YAML 的 > 折叠语法,可以写多行。
> 而不是直接写:当 description 超过一行时,用 > 折叠更清晰。YAML 会把多行合并为一行,保持格式整洁。反模式 —— 告诉 AI "不要做什么",比告诉它"做什么"更重要。
检查清单 —— 让 AI 在输出前做一次自检。
---
name: code-reviewer
description: >
对代码进行专业审查,找出问题并给出改进建议。
当用户需要 code review、代码审查、检查代码质量、审查 PR 时使用。
输出包含问题列表、严重程度评级、修复建议。
---
## 操作步骤
1. 读取用户提供的代码(文件路径或代码片段)
2. 逐行检查以下维度:安全性、性能、可读性、可维护性、边界情况
3. 对每个发现的问题评级:CRITICAL(必须修复)/ HIGH(建议修复)/ MEDIUM(可以优化)/ LOW(仅供参考)
4. 按严重程度排序,给出输出
## 输出格式
- 结构要求:
- 总结段落:3-5 句话概述代码整体质量
- 问题列表:每个问题包含位置、严重程度、描述、修复建议
- 推荐改动:给出具体的代码修改建议(用 diff 格式)
- 风格要求:专业但友好,像资深同事在做 review
- 严重程度使用标签标注:[CRITICAL] [HIGH] [MEDIUM] [LOW]
## 示例
**总结**
这段代码实现了用户注册功能,整体逻辑清晰。主要风险在于 SQL 拼接可能导致注入攻击,以及密码处理缺少加盐步骤。
**问题列表**
[HIGH] 第 42 行:SQL 拼接存在注入风险
使用了字符串拼接构建 SQL 查询,攻击者可以通过构造恶意输入获取数据库信息。
建议使用参数化查询:
```python
# 修复前
query = f"SELECT * FROM users WHERE name = '{username}'"
# 修复后
query = "SELECT * FROM users WHERE name = ?"
cursor.execute(query, (username,))
[MEDIUM] 第 58 行:缺少输入长度校验 用户名和密码没有长度限制,过长的输入可能导致缓冲区问题或 DoS。
---
## 带脚本的模板(进阶)
适合场景:需要执行复杂逻辑、调用外部工具、处理文件的场景。
### 目录结构
[your-skill-name]/ ├── SKILL.md ← 用上面的完整模板 ├── scripts/ │ └── [script-name].py ← 可执行脚本 └── references/ └── [ref-name].md ← 参考文档
### 为什么需要脚本
有些事情光靠 AI 的文本能力做不到:
- 读取和处理文件(如 CSV、Excel)
- 调用外部 API(如获取天气数据)
- 执行数学运算或数据分析
- 操作数据库
### 为什么需要参考文档
有些信息太长,不适合放在 SKILL.md 正文里:
- API 文档
- 品牌调性指南
- 产品参数列表
- 历史内容模板库
把大块信息放到 references/ 目录,SKILL.md 中按需引用,可以减少 token 消耗。
### SKILL.md 模板
```yaml
---
name: [your-skill-name]
description: >
[做什么]。
当用户需要[触发词]时使用。
输出包含[输出包含什么]。
---
## 操作步骤
1. 读取用户提供的[输入]
2. 运行 `scripts/[script-name].py --input [参数]` 执行[操作]
3. 获取脚本输出
4. 按 `references/[ref-name].md` 的格式组织结果
## 脚本说明
- `scripts/[script-name].py`:[脚本功能描述]
- 输入:[接受的参数]
- 输出:[返回的数据格式]
- 依赖:[需要的库或工具]
## 参考文档
- `references/[ref-name].md`:[文档用途说明]
data-analyst/
├── SKILL.md
├── scripts/
│ └── analyze.py
└── references/
└── report-template.md
---
name: data-analyst
description: >
分析数据并生成可视化报告。
当用户需要分析数据、数据报告、数据可视化、看数据趋势时使用。
输出包含数据分析结论和可视化图表。
---
## 操作步骤
1. 确认用户提供的数据文件路径
2. 运行 `scripts/analyze.py --file [数据文件路径]` 进行数据分析
3. 获取分析结果(统计摘要 + 异常值 + 趋势)
4. 按 `references/report-template.md` 的格式组织报告
5. 用自然语言解释数据含义,让非技术人员也能理解
## 脚本说明
- `scripts/analyze.py`:读取 CSV/Excel 文件,输出统计摘要
- 输入:数据文件路径
- 输出:JSON 格式的统计结果(均值、中位数、标准差、异常值列表)
- 依赖:pandas, numpy
## 参考文档
- `references/report-template.md`:标准分析报告的模板结构
| 规则 | 正确示例 | 错误示例 |
|---|---|---|
| 小写字母+数字+连字符 | commit-message-writer | — |
| 不能包含大写字母 | — | CommitWriter |
| 不能用下划线 | — | commit_writer |
| 不能以连字符开头或结尾 | — | -writerwriter- |
| 不能有连续连字符 | — | commit--writer |
| 长度 1-64 字符 | pdf-helper | a |
| 必须和文件夹名一致 | 文件夹 pdf-helper/ = name pdf-helper | 文件夹 pdf/ 但 name pdf-helper |
commit-helper → 功能清晰,一看就懂
xiaohongshu-writer → 平台+功能,定位准确
code-reviewer → 简洁有力
data-analyst → 角色定义,通用性强
pdf-to-markdown → 动作+格式,直观
blog-post-generator → 输出物+动作
api-doc-writer → 领域+功能
security-scanner → 安全领域+扫描功能
skill1 → 太笼统,不知道干什么
my-awesome-skill → 只有自嗨,没有信息量
h → 单字母,毫无意义
this-is-a-very-long-name-that-nobody-can-remember
→ 太长,超出实际需要
xhs → 缩写不直观,别人看不懂
write → 动词太泛,write 什么?
选择以下公式之一,填入你的内容:
{做什么}-{详细功能} → commit-message-writer{平台或领域}-{功能} → xiaohongshu-seeding-note{角色名} → code-reviewer{源格式}-to-{目标格式} → pdf-to-markdowndescription = "做什么 + 什么时候用 + 输出包含什么"
三要素缺一不可:
规则 1:包含至少 3 个触发词
用户可能用不同方式描述同一个需求。触发词越多,匹配率越高。
好的写法:
"生成 Git 提交信息。当用户需要写 commit message、提交代码、
描述代码改动、生成提交说明时使用。"
这里包含 4 个触发词:commit message、提交代码、描述代码改动、提交说明。
差的写法:
"帮你写提交信息。"
只有一个触发词,覆盖面太窄。
规则 2:说清输出类型
好的:"输出包含一条符合 Conventional Commits 规范的提交信息。"
差的:"帮你处理提交。"
规则 3:避免过度宽泛或过度狭窄
过度宽泛(会导致 over-trigger):
"帮助你处理各种写作任务。" ← 什么写作?太宽了
过度狭窄(会导致 under-trigger):
"当用户说'请帮我用 Conventional Commits 规范写一条 feat 类型的提交信息'时使用。"
← 用户不可能说得这么精确
恰到好处:
"生成规范的 Git 提交信息。当用户需要写 commit message、
提交代码、描述改动时使用。"
规则 4:控制长度
建议 50-150 字。太短说不清,太长 AI 抓不住重点。
"分析 Python 代码的性能瓶颈。当用户说代码慢、需要优化性能、
查找性能问题、分析运行时间时使用。输出包含问题定位和优化建议。"
"将 Markdown 文件转换为微信公众号格式。当用户需要发公众号、
微信公众号排版、适配微信格式时使用。输出可直接复制到微信编辑器的 HTML。"
"一个很有用的工具。" ← 没说做什么,没说什么时候用
"帮你做所有事情。" ← 过度宽泛
"当用户输入 /analyze-python-perf 时" ← 过度狭窄,依赖特定命令
"这个 Skill 可以帮助开发者分析他们的 ← 啰嗦,200字描述一件简单的事
Python 代码的性能问题,它会仔细检查
每一行代码,找出可能导致性能下降的
地方,然后给出非常详细的优化建议……"
以下是新手常犯的错误,以及对应的修正版本。
# 错误
---
name: writer
description: "写作"
---
AI 看到这个 description,完全不知道什么时候该用它。用户的任何文字需求都可能触发,也可能都不触发。
# 修正
---
name: blog-post-writer
description: "撰写技术博客文章。当用户需要写博客、写技术文章、发布博文、写教程时使用。输出包含标题、正文和摘要。"
---
# 错误
---
name: translator
description: "翻译文本。当用户需要翻译时使用。"
---
帮用户翻译内容。
翻译什么语言?保持什么风格?专业术语怎么处理?全都没说。AI 只能自由发挥,输出质量不可控。
# 修正
---
name: chinese-to-english
description: "将中文翻译为自然流畅的英文。当用户需要中翻英、翻译成英语、英文翻译时使用。"
---
## 操作步骤
1. 确认用户要翻译的中文内容
2. 翻译为地道英文,不要逐字直译
3. 专业术语保留英文原文,不翻译
## 输出格式
- 先给出完整翻译
- 然后列出 3-5 个翻译时的关键选择及理由
- 风格:正式商务英语,简洁有力
# 错误
## 操作步骤
1. 分析用户的代码
2. 找出 bug
3. 给出建议
"给出建议"是多大的建议?一句话?还是详细方案?AI 不知道。
# 修正
## 输出格式
- 问题总结:1-3 句话
- 详细分析:每个问题包含以下信息
- 所在位置(文件名 + 行号)
- 问题描述(1-2 句话)
- 修复方案(包含可直接使用的代码)
- 严重程度:[CRITICAL/HIGH/MEDIUM/LOW]
# 文件夹名叫 translator/
# 但 SKILL.md 里写的是 name: chinese-translator
# 结果:AI 找不到这个 Skill
这是最常见的"我写好了 Skill 但不生效"的原因。name 必须和文件夹名一模一样。
# 错误
description: "先读取用户的文件,然后分析内容,
接着生成报告,最后输出 PDF。"
description 的作用是让 AI 判断要不要加载,不是告诉 AI 怎么做。操作步骤写在正文里。
# 修正
description: "分析数据文件并生成报告。当用户需要数据分析、
生成报告、查看数据趋势时使用。输出包含分析结论和建议的文本报告。"
写完 SKILL.md 后,逐项检查: