AI Skill 使用教程从写好 SKILL.md 到让智能体正确调用适合人群使用 AI Agent 的新手、开发者和团队成员。本文介绍一种常见的 Agent Skill 组织方式用SKILL.md写清楚可复用的工作流程再按需附上参考资料、模板或脚本。不同产品的安装目录、发现机制和调用方式可能不同使用前请查看对应工具的说明。一、Skill 是什么可以把 Skill 理解为一份给 AI Agent 使用的“专项工作手册”。它说明遇到哪类任务时应该采用什么流程、遵守什么规则、输出什么结果。需要时还可以带上参考资料、模板或脚本。例如一个“会议纪要整理”Skill 可以规定先提取会议结论和待办负责人或日期缺失时标注“未说明”将原文事实与推测分开按统一格式输出。Skill 本身通常不会自动赋予 Agent 新能力。它可以告诉 Agent 如何使用已经可用的工具是否能读写文件、搜索网页或连接应用取决于当前运行环境提供的权限和工具。二、Skill、提示词和工具有什么区别内容主要作用示例提示词描述当前这一轮任务“总结这份会议记录”Skill保存可反复使用的任务流程和约定每次整理会议纪要都按同一结构输出工具让 Agent 能执行具体操作读取文件、搜索网页、运行脚本一句话理解提示词说明这次要做什么Skill 提供稳定的做法工具提供执行能力。三、一个常见的 Skill 文件结构许多支持 Agent Skills 的工具使用SKILL.md作为入口文件。简单的 Skill 只需要这个文件复杂流程可以把材料分开放meeting-notes/ ├── SKILL.md # 必需用途、触发条件和步骤 ├── references/ │ └── style-guide.md # 可选团队写作规范 ├── assets/ │ └── meeting-template.md # 可选输出模板 └── scripts/ └── validate.py # 可选重复性校验脚本常见分工SKILL.md保留必要说明、工作步骤和结果要求references/放较长的背景材料或规范assets/放输出模板、示例文件等静态素材scripts/放可重复运行的脚本或校验程序。刚开始不需要把所有目录都建出来先写清楚一个可用流程即可。四、编写第一个 Skill下面以“整理会议纪要”为例。新建一个名为meeting-notes的文件夹并在其中创建SKILL.md--- name: meeting-notes description: 根据会议记录整理结论、待办事项和未决问题。用户要求整理、归纳或规范化会议记录时使用。 --- # 会议纪要整理 ## 目标 把用户提供的会议记录整理成易检查的结构化纪要。 ## 工作步骤 1. 识别会议主题、日期和参会人原文没有的信息标记“未提供”。 2. 提取明确达成的结论不把讨论中的设想写成已决定事项。 3. 提取待办事项并记录负责人和截止日期。 4. 将尚未解决的问题单独列出。 5. 检查姓名、数字、日期和行动项是否能在原文中找到依据。 ## 输出格式 - 会议主题与日期 - 已确认结论 - 待办事项事项负责人截止日期 - 未决问题 ## 边界 - 只依据用户提供的材料不补造事实。 - 缺少负责人或日期时写“未说明”。 - 不发送会议纪要不修改原始文件。 - 如果材料中包含相互矛盾的信息列出矛盾并请用户确认。这里的name是便于系统识别的短名称description要说明 Skill 做什么以及何时应该使用。只写“帮助整理”太宽泛Agent 不容易判断适用时机。五、怎样让 Skill 更容易被正确调用1. 一个 Skill 对准一个明确目标不要把“写文章、调试代码、分析表格、整理会议”全部塞进一个 Skill。任务目标差别太大时分别建立 Skill触发条件会更明确规则也更容易维护。2. 在 description 里写触发场景可以用这个结构[产出或处理什么]。当用户要求[具体任务或场景]时使用。例如根据用户提供的 CSV 生成数据摘要和异常项清单。当用户要求分析、汇总或检查 CSV 文件时使用。3. 用步骤替代模糊要求“认真分析并给出好结果”无法指导具体行动。更好的写法是先检查字段、再处理空值、然后计算指标、最后说明限制条件。4. 写出停止条件告诉 Agent 什么时候需要停下来询问例如材料不足、出现矛盾、需要外部发送或操作可能修改原始数据。六、怎样安装和使用 SkillSkill 的文件格式可以相近但每个平台的安装位置和加载方式并不完全相同。通用步骤如下查看正在使用的 Agent 是否支持SKILL.md或 Agent Skills 格式。按对应平台的说明把 Skill 文件夹放进指定目录、工作区或运行环境。检查 Agent 是否能发现该 Skill部分工具会自动根据name和description判断是否调用。直接描述具体任务如果需要明确指定可以在请求中写“请使用meeting-notesSkill”。检查输出是否符合 Skill 的步骤和格式并根据遗漏调整说明。以 OpenAI 的 Agent Skills 文档为例Skill 由包含SKILL.md的目录构成可带参考文件、脚本和素材在 API 执行环境中的挂载方式取决于使用 hosted shell、local shell 或 Agents API。不要把某个平台的安装路径直接套用到另一个工具。七、用真实任务迭代 Skill第一次写出的 Skill 通常只是初稿。可以用几种不同输入检查规则是否清楚标准情况信息完整的会议记录缺项情况没有写日期或负责人矛盾情况两个段落对截止时间写法不同边界情况用户只要求提取某一部分不适用情况用户问的是会议邀请邮件而不是整理会议记录。观察 Agent 是否在正确任务中调用 Skill是否按格式输出以及遇到缺失信息时有没有乱猜。然后只修改不清楚或容易误用的说明并再次检查。八、常见问题排查Skill 没有被调用检查description是否包含实际触发场景在任务中明确说“使用某某 Skill”确认 Skill 已放在正确位置并且当前环境支持这种加载方式。Agent 只遵循了一部分规则把重要要求改写成编号步骤或检查清单。把主要流程放在SKILL.md不要只藏在未被读取的附加文件中。SKILL.md 越写越长把详细规范、示例或背景资料移到references/并在主文件中说明何时读取。主文件优先保留任务目标、触发条件、关键步骤、输出格式和边界。不同平台上的表现不一致检查该工具支持的 front matter 字段、目录约定和加载方式。相同的SKILL.md内容不代表每个平台都会以相同方式加载或调用。九、安全使用 SkillSkill 文件会影响 Agent 的判断和工具使用方式。使用别人提供的 Skill 前先检查它的指令、脚本和引用文件有没有要求上传或泄露本地资料有没有运行来源不明的命令或下载程序有没有要求绕过权限、确认步骤或安全限制脚本会读取、覆盖或删除哪些文件是否会把信息发送给外部服务只使用任务所需的最小权限。涉及发送、发布、支付、删除、生产环境修改等高影响操作时应保留人工审核和明确确认。十、本节小结一个好用的 Skill 不在于写得很长而在于目标明确、触发条件清楚、步骤可执行、输出能检查、边界写完整。先从一个重复的小任务开始用实际结果不断修订再考虑增加参考资料、模板或脚本。参考资料OpenAI Agent Skills 文档OpenAIBuild skillsAgent Skills 开放规范本文关键词AI Skill、Agent Skills、SKILL.md、AI Agent、智能体工作流、提示词 AI-Skill使用教程-从SKILL-md到智能体调用
AI Skill 使用教程从写好 SKILL.md 到让智能体正确调用适合人群使用 AI Agent 的新手、开发者和团队成员。本文介绍一种常见的 Agent Skill 组织方式用SKILL.md写清楚可复用的工作流程再按需附上参考资料、模板或脚本。不同产品的安装目录、发现机制和调用方式可能不同使用前请查看对应工具的说明。一、Skill 是什么可以把 Skill 理解为一份给 AI Agent 使用的“专项工作手册”。它说明遇到哪类任务时应该采用什么流程、遵守什么规则、输出什么结果。需要时还可以带上参考资料、模板或脚本。例如一个“会议纪要整理”Skill 可以规定先提取会议结论和待办负责人或日期缺失时标注“未说明”将原文事实与推测分开按统一格式输出。Skill 本身通常不会自动赋予 Agent 新能力。它可以告诉 Agent 如何使用已经可用的工具是否能读写文件、搜索网页或连接应用取决于当前运行环境提供的权限和工具。二、Skill、提示词和工具有什么区别内容主要作用示例提示词描述当前这一轮任务“总结这份会议记录”Skill保存可反复使用的任务流程和约定每次整理会议纪要都按同一结构输出工具让 Agent 能执行具体操作读取文件、搜索网页、运行脚本一句话理解提示词说明这次要做什么Skill 提供稳定的做法工具提供执行能力。三、一个常见的 Skill 文件结构许多支持 Agent Skills 的工具使用SKILL.md作为入口文件。简单的 Skill 只需要这个文件复杂流程可以把材料分开放meeting-notes/ ├── SKILL.md # 必需用途、触发条件和步骤 ├── references/ │ └── style-guide.md # 可选团队写作规范 ├── assets/ │ └── meeting-template.md # 可选输出模板 └── scripts/ └── validate.py # 可选重复性校验脚本常见分工SKILL.md保留必要说明、工作步骤和结果要求references/放较长的背景材料或规范assets/放输出模板、示例文件等静态素材scripts/放可重复运行的脚本或校验程序。刚开始不需要把所有目录都建出来先写清楚一个可用流程即可。四、编写第一个 Skill下面以“整理会议纪要”为例。新建一个名为meeting-notes的文件夹并在其中创建SKILL.md--- name: meeting-notes description: 根据会议记录整理结论、待办事项和未决问题。用户要求整理、归纳或规范化会议记录时使用。 --- # 会议纪要整理 ## 目标 把用户提供的会议记录整理成易检查的结构化纪要。 ## 工作步骤 1. 识别会议主题、日期和参会人原文没有的信息标记“未提供”。 2. 提取明确达成的结论不把讨论中的设想写成已决定事项。 3. 提取待办事项并记录负责人和截止日期。 4. 将尚未解决的问题单独列出。 5. 检查姓名、数字、日期和行动项是否能在原文中找到依据。 ## 输出格式 - 会议主题与日期 - 已确认结论 - 待办事项事项负责人截止日期 - 未决问题 ## 边界 - 只依据用户提供的材料不补造事实。 - 缺少负责人或日期时写“未说明”。 - 不发送会议纪要不修改原始文件。 - 如果材料中包含相互矛盾的信息列出矛盾并请用户确认。这里的name是便于系统识别的短名称description要说明 Skill 做什么以及何时应该使用。只写“帮助整理”太宽泛Agent 不容易判断适用时机。五、怎样让 Skill 更容易被正确调用1. 一个 Skill 对准一个明确目标不要把“写文章、调试代码、分析表格、整理会议”全部塞进一个 Skill。任务目标差别太大时分别建立 Skill触发条件会更明确规则也更容易维护。2. 在 description 里写触发场景可以用这个结构[产出或处理什么]。当用户要求[具体任务或场景]时使用。例如根据用户提供的 CSV 生成数据摘要和异常项清单。当用户要求分析、汇总或检查 CSV 文件时使用。3. 用步骤替代模糊要求“认真分析并给出好结果”无法指导具体行动。更好的写法是先检查字段、再处理空值、然后计算指标、最后说明限制条件。4. 写出停止条件告诉 Agent 什么时候需要停下来询问例如材料不足、出现矛盾、需要外部发送或操作可能修改原始数据。六、怎样安装和使用 SkillSkill 的文件格式可以相近但每个平台的安装位置和加载方式并不完全相同。通用步骤如下查看正在使用的 Agent 是否支持SKILL.md或 Agent Skills 格式。按对应平台的说明把 Skill 文件夹放进指定目录、工作区或运行环境。检查 Agent 是否能发现该 Skill部分工具会自动根据name和description判断是否调用。直接描述具体任务如果需要明确指定可以在请求中写“请使用meeting-notesSkill”。检查输出是否符合 Skill 的步骤和格式并根据遗漏调整说明。以 OpenAI 的 Agent Skills 文档为例Skill 由包含SKILL.md的目录构成可带参考文件、脚本和素材在 API 执行环境中的挂载方式取决于使用 hosted shell、local shell 或 Agents API。不要把某个平台的安装路径直接套用到另一个工具。七、用真实任务迭代 Skill第一次写出的 Skill 通常只是初稿。可以用几种不同输入检查规则是否清楚标准情况信息完整的会议记录缺项情况没有写日期或负责人矛盾情况两个段落对截止时间写法不同边界情况用户只要求提取某一部分不适用情况用户问的是会议邀请邮件而不是整理会议记录。观察 Agent 是否在正确任务中调用 Skill是否按格式输出以及遇到缺失信息时有没有乱猜。然后只修改不清楚或容易误用的说明并再次检查。八、常见问题排查Skill 没有被调用检查description是否包含实际触发场景在任务中明确说“使用某某 Skill”确认 Skill 已放在正确位置并且当前环境支持这种加载方式。Agent 只遵循了一部分规则把重要要求改写成编号步骤或检查清单。把主要流程放在SKILL.md不要只藏在未被读取的附加文件中。SKILL.md 越写越长把详细规范、示例或背景资料移到references/并在主文件中说明何时读取。主文件优先保留任务目标、触发条件、关键步骤、输出格式和边界。不同平台上的表现不一致检查该工具支持的 front matter 字段、目录约定和加载方式。相同的SKILL.md内容不代表每个平台都会以相同方式加载或调用。九、安全使用 SkillSkill 文件会影响 Agent 的判断和工具使用方式。使用别人提供的 Skill 前先检查它的指令、脚本和引用文件有没有要求上传或泄露本地资料有没有运行来源不明的命令或下载程序有没有要求绕过权限、确认步骤或安全限制脚本会读取、覆盖或删除哪些文件是否会把信息发送给外部服务只使用任务所需的最小权限。涉及发送、发布、支付、删除、生产环境修改等高影响操作时应保留人工审核和明确确认。十、本节小结一个好用的 Skill 不在于写得很长而在于目标明确、触发条件清楚、步骤可执行、输出能检查、边界写完整。先从一个重复的小任务开始用实际结果不断修订再考虑增加参考资料、模板或脚本。参考资料OpenAI Agent Skills 文档OpenAIBuild skillsAgent Skills 开放规范本文关键词AI Skill、Agent Skills、SKILL.md、AI Agent、智能体工作流、提示词