如何编写 Agent Skill

在 AI Agent 框架中Skill是一个可重用的、结构化的程序它定义了 AI Agent 如何使用工具和集成MCP connectors、API 等来可靠地完成特定任务。一个 Skill 不仅仅是知识更重要的是逐步执行的逻辑。本文将详细介绍如何编写一个合格的 Agent Skill。为什么需要 Agent SkillAI Agent 本身具备推理和规划能力但它往往不知道如何调用特定的工具或执行特定的工作流。Skill 就是为了让 Agent 具备以下能力调用特定的 API 或服务执行多步骤的工作流使用特定的工具完成特定任务保持执行的一致性和可靠性正如 Vercel 工程师 Eric Dodds 和 Andrew Qu 在博客中所说Agent skills fix this. They are a simple, open format that packages instructions, scripts, and resources LLMs and agents can discover and use automatically, increasing output accuracy.翻译Agent Skills 解决了这个问题。它们是一种简单、开放的格式将指令、脚本和资源打包LLM 和 Agent 可以自动发现和使用从而提高输出准确性。Agent Skill 的基本结构一个标准的 Agent Skill 通常包含以下文件my-skill/ ├── SKILL.md # Skill 的核心描述文件必需 ├── src/ # 源代码目录可选 │ └── index.ts # 入口文件 ├── scripts/ # 可执行脚本可选 ├── references/ # 参考文档可选 └── assets/ # 资源文件可选SKILL.md 文件详解SKILL.md是 Skill 的核心它定义了 Skill 的元信息和使用方式。YAML Frontmatter文件开头必须包含 YAML 格式的元信息--- name: my-skill # Skill 标识符建议使用 kebab-case description: 这是 Skill 的描述说明它能做什么以及何时触发。 trigger: 关键词1, 关键词2, 关键词3 # 触发关键词 ---核心字段说明nameSkill 的名称建议使用 kebab-case 格式description这是最关键的字段是 AI 决定是否调用该 Skill 的主要依据。描述应该包含Skill 能完成什么任务如何使用工具和集成具体的触发场景根据最佳实践描述要写得具体且有场景感。例如❌ 弱Query weather data.✅ 强Query weather data. Use this whenever the user asks about weather, temperature, or forecasts for any location. The skill uses the weather API to fetch current conditions and forecasts, then formats the results in a human-readable way.trigger触发关键词当用户消息中包含这些词时AI 会考虑调用这个 Skill。Markdown 主体在 frontmatter 之后是 Skill 的详细说明文档# 我的技能名称 这是技能的详细描述。 ## 概述 简要说明这个技能的目的和功能。 ## 使用工具 列出这个 Skill 会用到的工具和集成 - API 服务 - MCP connectors - 其他工具 ## 执行步骤 这是 Skill 的核心必须包含**逐步执行的逻辑**而不是仅仅描述做什么。 1. 第一步xxx 2. 第二步xxx 3. 第三步xxx ## 输出格式 描述输出的格式要求。 ## 示例 提供具体的对话示例帮助 AI 理解何时调用。 ## 注意事项 列出任何需要注意的边界情况或限制。编写步骤第一步明确任务在编写 Skill 之前先回答以下问题这个 Skill 要让 Agent 完成什么任务Agent 需要调用哪些工具或 API执行的逻辑步骤是什么期望的输出格式是什么第二步编写 SKILL.md关键点必须包含逐步执行的逻辑一个好的 Skill 应该清楚地告诉 Agent什么时候应该调用这个 Skill需要哪些工具/集成执行的步骤是什么第一步做什么第二步做什么...如何处理错误和边界情况渐进式披露原则保持 SKILL.md 在 500 行以内如果内容过多使用清晰的层级结构第三步实现功能可选如果 Skill 需要执行代码// src/index.ts export async function execute(param: string) { // 实现具体逻辑 return result; }第四步Bundle 重复工作如果在多个测试用例中 Agent 重复做相同的工作应该把这个工作封装成脚本放在scripts/目录下。最佳实践描述要具体且pushy明确列出触发场景让 Agent 知道什么时候该调用这个 Skilldescription: 浏览网页。当用户提到网络搜索、搜索、查查看等操作时调用。执行步骤要清晰这是最重要的部分不要只告诉 Agent做什么要告诉它怎么做## 执行步骤 1. **解析用户需求**确定用户想要执行什么操作创建、查询、更新、删除 2. **准备数据**根据操作类型准备需要的数据 3. **调用 API**使用 feishu_bitable_app_table_record 工具执行操作 4. **处理结果**解析返回结果格式化输出 5. **错误处理**如果出错提供友好的错误信息示例要实用用户说帮我创建一个记录时 1. 确认要操作的多维表格从上下文或询问用户获取 2. 准备记录数据 3. 调用创建记录接口 4. 返回成功信息总结编写 Agent Skill 的核心在于准确的定义— 明确 Skill 能完成什么任务逐步执行的逻辑— 这是 Skill 与普通知识库的本质区别不仅要告诉 Agent 做什么更要告诉它怎么做清晰的工具集成— 说明白会用到哪些工具和 API具体的触发场景— 让 Agent 知道什么时候该调用这个 Skill错误处理— 考虑边界情况和错误处理掌握了这些要点你就可以为任何 Agent 框架编写 Skill让 AI Agent 从能思考变成能干活。学习资源推荐如果你想更深入地学习大模型以下是一些非常有价值的学习资源这些资源将帮助你从不同角度学习大模型提升你的实践能力。一、全套AGI大模型学习路线AI大模型时代的学习之旅从基础到前沿掌握人工智能的核心技能​因篇幅有限仅展示部分资料需要点击文章最下方名片即可前往获取二、640套AI大模型报告合集这套包含640份报告的合集涵盖了AI大模型的理论研究、技术实现、行业应用等多个方面。无论您是科研人员、工程师还是对AI大模型感兴趣的爱好者这套报告合集都将为您提供宝贵的信息和启示​因篇幅有限仅展示部分资料需要点击文章最下方名片即可前往获取三、AI大模型经典PDF籍随着人工智能技术的飞速发展AI大模型已经成为了当今科技领域的一大热点。这些大型预训练模型如GPT-3、BERT、XLNet等以其强大的语言理解和生成能力正在改变我们对人工智能的认识。 那以下这些PDF籍就是非常不错的学习资源。因篇幅有限仅展示部分资料需要点击文章最下方名片即可前往获取四、AI大模型商业化落地方案作为普通人入局大模型时代需要持续学习和实践不断提高自己的技能和认知水平同时也需要有责任感和伦理意识为人工智能的健康发展贡献力量。