--- title: "SKILL.md 完整模板" wiki: skills category: "结构规范" slug: B-SKILL.md完整模板 url: https://learnagent.wiki/skills/cards/B-SKILL.md完整模板 tags: ["SKILL.md", "模板", "结构规范", "写作"] last_updated: 2026-04-11 reading_time: 22 --- > > 附录 B：SKILL.md 完整填空模板 # Skill 从小白到高手系列课 > 附录 B：SKILL.md 完整填空模板 > > 复制适合你水平的模板，填入 `[占位符]` 部分即可。 > 每个模板后面都有详细解释，告诉你为什么这样写。 --- ## 最小模板（5 行搞定） 适合场景：快速验证想法、内部自用、逻辑简单的任务。 ```yaml --- name: [your-skill-name] description: "[做什么]。当用户需要[什么时候用]时使用。" --- [用自然语言写操作指令，告诉AI怎么完成任务] ``` ### 逐字段解释 **name** —— 这是你的 Skill 的身份证号。 - 为什么重要：AI 在加载时会优先匹配 name，好的 name 能让 AI 更快找到你的 Skill。 - 只能小写字母、数字、连字符，1-64 字符。 - 必须和你创建的文件夹名称完全一致。 **description** —— 这是 AI 决定"要不要加载"的唯一依据。 - 为什么重要：AI 看到用户的问题后，会拿 description 和问题做匹配。匹配度高才加载。 - 必须说清楚两件事：做什么 + 什么时候用。 - 限 1024 字符，但建议控制在 100 字以内，越精炼越好。 **正文指令** —— 这是 AI 加载后实际执行的步骤。 - 用自然语言写就行，不需要编程语法。 - 越具体越好。"写一篇文章"是差的指令，"写一篇 500 字的小红书种草笔记，风格口语化，包含 3 个 emoji"是好的指令。 ### 完整使用示例：生成 Git 提交信息 ```yaml --- name: commit-helper description: "生成规范的 Git 提交信息。当用户需要写 commit message、提交代码、描述改动时使用。" --- 根据当前 git diff 的内容，生成一条规范的提交信息。 格式要求：type(scope): description type 只用 feat/fix/docs/style/refactor/test/chore 之一。 description 用中文，不超过 50 字符。 ``` 这个例子虽然只有 5 行，但已经覆盖了关键信息： - name 清晰表达功能 - description 包含了多个触发词（"提交信息""commit message""描述改动"） - 正文指令给出了明确的格式要求和约束 --- ## 标准模板（推荐新手用） 适合场景：需要控制输出格式、有一定复杂度的任务、分享给团队使用。 ```yaml --- name: [your-skill-name] description: "[做什么]。当用户需要[触发词1]、[触发词2]、[触发词3]时使用。输出包含[输出包含什么]。" --- ## 操作步骤 1. [第一步：理解用户要什么] 2. [第二步：怎么做] 3. [第三步：输出什么格式] ## 输出格式 [描述期望的输出样子，越具体越好] - 字数要求：[如300-500字] - 结构要求：[如标题+正文+标签] - 风格要求：[如口语化/专业/幽默] ## 示例 [给AI看一个好的输出样例] ``` ### 逐字段解释 **description（标准版）** —— 相比最小模板，这里需要更多触发词和输出说明。 - 触发词为什么重要：用户可能用不同的方式描述同一个需求。有人会说"帮我写文案"，有人会说"帮我发一篇小红书"。多写几个触发词，覆盖面更广。 - 输出说明为什么重要：AI 在决定是否加载时也会参考输出类型。如果你的 Skill 输出的是表格，但用户要的是一段文字，AI 就不应该加载。 **操作步骤** —— 把任务拆成步骤，AI 执行时不容易遗漏。 - 为什么不直接写一段话：步骤式写法让 AI 逐条执行，出错概率更低。尤其是多步骤任务，1-2-3-4 的结构比一整段文字效果好得多。 - 每一步只需要一句话，说清楚"做什么"，不需要解释"为什么"。 **输出格式** —— 这是控制 AI 输出质量的关键。 - 字数：给出范围比给固定数字好。"300-500 字"比"400 字"更灵活。 - 结构：列出必须包含的部分，AI 就不会遗漏。 - 风格：AI 默认输出比较正式，如果你要口语化的内容，必须明确说。 **示例** —— 一个好的示例顶一百句描述。 - 为什么重要：AI 从示例中学习的能力非常强。给出一个你满意的输出样本，AI 会模仿它的风格和结构。 - 示例不需要很长，但必须代表你期望的质量标准。 ### 完整使用示例：小红书种草笔记 ```yaml --- name: xiaohongshu-seeding-note description: "生成小红书种草笔记。当用户需要写小红书、种草推荐、产品推荐笔记、好物分享时使用。输出包含标题、正文、标签。" --- ## 操作步骤 1. 确认用户要推荐的产品或服务，以及目标人群 2. 如果用户没有给出具体卖点，从产品的 3 个核心优势出发构思 3. 按照下面的输出格式生成笔记 ## 输出格式 - 字数要求：正文 300-600 字 - 结构要求： - 标题：15 字以内，包含一个吸引眼钩的词（如"绝了""太香了""后悔没早买"） - 正文：开头抛痛点 → 中间讲体验 → 结尾给建议 - 标签：5-8 个，包含品类标签和场景标签 - 风格要求：口语化、亲切、像在跟闺蜜聊天 - emoji：每段 1-2 个，不要过多 ## 示例 **标题**：这个平价面霜太香了 干皮姐妹冲 **正文**： 作为一个大干皮，冬天真的是我的噩梦。脸上起皮、卡粉，涂什么都不服帖。 直到我发现了这个宝藏面霜！质地像冰淇淋一样，上脸秒吸收，完全不油腻。我一般晚上厚涂一层当睡眠面膜用，第二天早上脸软软嫩嫩的。 最让我惊喜的是它的保湿持久度。以前到下午脸就开始紧绷，现在一整天都很水润。而且这个价格，学生党也完全没压力。 推荐给所有干皮姐妹，秋冬必备！ **标签**：#平价面霜 #干皮救星 #护肤好物 #学生党护肤 #秋冬必备 #保湿面霜 ``` --- ## 完整模板（带反模式和检查清单） 适合场景：高要求任务、AI 容易犯错的场景、需要稳定输出的生产环境。 ```yaml --- 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 "不要做什么"，比告诉它"做什么"更重要。 - 为什么重要：AI 很擅长模仿，但不擅长判断边界。不给反模式，它可能会把 80% 做对了，但剩下 20% 完全跑偏。 - 常见的反模式写法： - "不要使用过于专业的术语"（风格约束） - "不要编造不存在的数据或案例"（准确性约束） - "不要在输出中重复用户的原始问题"（格式约束） - "不要添加未经用户要求的内容"（范围约束） **检查清单** —— 让 AI 在输出前做一次自检。 - 为什么重要：AI 生成内容后，可以让它对照清单检查一遍。这个简单的动作能显著提升输出质量。 - 检查项应该是可量化的：字数是否在范围内？是否包含所有必要部分？是否符合风格要求？ ### 完整使用示例：代码审查 ```yaml --- 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。 ## 反模式（不要做什么） - 不要只说"这段代码不好"而不给具体原因 - 不要忽略安全问题，即使看起来不太严重 - 不要给出模糊的修复建议（如"优化一下"），必须给出具体方案 - 不要修改与问题无关的代码风格 ## 检查清单（AI输出前自查） - [ ] 每个问题都有严重程度评级吗？ - [ ] 每个问题都有具体的修复建议吗？ - [ ] 安全问题是否全部覆盖（注入、XSS、敏感数据暴露）？ - [ ] 修复建议中的代码是否可直接使用？ ``` --- ## 带脚本的模板（进阶） 适合场景：需要执行复杂逻辑、调用外部工具、处理文件的场景。 ### 目录结构 ``` [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 ``` ```yaml --- 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`：标准分析报告的模板结构 ``` --- ## name 命名规则详解 ### 规则总览 | 规则 | 正确示例 | 错误示例 | |------|----------|----------| | 小写字母+数字+连字符 | `commit-message-writer` | — | | 不能包含大写字母 | — | ~~`CommitWriter`~~ | | 不能用下划线 | — | ~~`commit_writer`~~ | | 不能以连字符开头或结尾 | — | ~~`-writer`~~、~~`writer-`~~ | | 不能有连续连字符 | — | ~~`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-markdown` --- ## description 写作规则详解 ### 核心公式 ``` description = "做什么 + 什么时候用 + 输出包含什么" ``` 三要素缺一不可： - **做什么**：AI 需要知道这个 Skill 的核心功能 - **什么时候用**：AI 需要知道在什么场景下触发 - **输出包含什么**：AI 需要知道输出类型是否匹配用户需求 ### 写作规则 **规则 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 代码的性能问题，它会仔细检查 每一行代码，找出可能导致性能下降的 地方，然后给出非常详细的优化建议……" ``` --- ## 常见错误模板 以下是新手常犯的错误，以及对应的修正版本。 ### 错误 1：description 只有一个词 ```yaml # 错误 --- name: writer description: "写作" --- ``` AI 看到这个 description，完全不知道什么时候该用它。用户的任何文字需求都可能触发，也可能都不触发。 ```yaml # 修正 --- name: blog-post-writer description: "撰写技术博客文章。当用户需要写博客、写技术文章、发布博文、写教程时使用。输出包含标题、正文和摘要。" --- ``` ### 错误 2：正文指令太笼统 ```yaml # 错误 --- name: translator description: "翻译文本。当用户需要翻译时使用。" --- 帮用户翻译内容。 ``` 翻译什么语言？保持什么风格？专业术语怎么处理？全都没说。AI 只能自由发挥，输出质量不可控。 ```yaml # 修正 --- name: chinese-to-english description: "将中文翻译为自然流畅的英文。当用户需要中翻英、翻译成英语、英文翻译时使用。" --- ## 操作步骤 1. 确认用户要翻译的中文内容 2. 翻译为地道英文，不要逐字直译 3. 专业术语保留英文原文，不翻译 ## 输出格式 - 先给出完整翻译 - 然后列出 3-5 个翻译时的关键选择及理由 - 风格：正式商务英语，简洁有力 ``` ### 错误 3：没有输出格式约束 ```yaml # 错误 ## 操作步骤 1. 分析用户的代码 2. 找出 bug 3. 给出建议 ``` "给出建议"是多大的建议？一句话？还是详细方案？AI 不知道。 ```yaml # 修正 ## 输出格式 - 问题总结：1-3 句话 - 详细分析：每个问题包含以下信息 - 所在位置（文件名 + 行号） - 问题描述（1-2 句话） - 修复方案（包含可直接使用的代码） - 严重程度：[CRITICAL/HIGH/MEDIUM/LOW] ``` ### 错误 4：name 和文件夹名不一致 ``` # 文件夹名叫 translator/ # 但 SKILL.md 里写的是 name: chinese-translator # 结果：AI 找不到这个 Skill ``` 这是最常见的"我写好了 Skill 但不生效"的原因。name 必须和文件夹名一模一样。 ### 错误 5：在 description 里写操作步骤 ```yaml # 错误 description: "先读取用户的文件，然后分析内容， 接着生成报告，最后输出 PDF。" ``` description 的作用是让 AI 判断要不要加载，不是告诉 AI 怎么做。操作步骤写在正文里。 ```yaml # 修正 description: "分析数据文件并生成报告。当用户需要数据分析、 生成报告、查看数据趋势时使用。输出包含分析结论和建议的文本报告。" ``` --- ## 快速检查清单 写完 SKILL.md 后，逐项检查： - [ ] name 是否全小写、用连字符、1-64 字符？ - [ ] name 是否和文件夹名完全一致？ - [ ] description 是否说了"做什么 + 什么时候用 + 输出什么"？ - [ ] description 是否包含至少 3 个触发词？ - [ ] description 是否在 50-150 字之间？ - [ ] 正文是否有明确的操作步骤？ - [ ] 是否有输出格式约束（字数、结构、风格）？ - [ ] 是否有示例？ - [ ] 如果任务容易出错，是否有反模式？ - [ ] 如果对输出质量要求高，是否有检查清单？ --- *Source: https://learnagent.wiki/skills/cards/B-SKILL.md完整模板* *Markdown mirror of https://learnagent.wiki, served as text/markdown for LLM ingestion.*