在 AI Agent 框架中，Skill 是一个可重用的、结构化的程序，它定义了 AI Agent 如何使用工具和集成（MCP connectors、API 等）来可靠地完成特定任务。一个 Skill 不仅仅是知识，更重要的是逐步执行的逻辑。

本文将详细介绍如何编写一个合格的 Agent Skill。

为什么需要 Agent Skill

AI 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"  # 触发关键词
---

核心字段说明：

• name：Skill 的名称，建议使用 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 之前，先回答以下问题：

1. 这个 Skill 要让 Agent 完成什么任务？
2. Agent 需要调用哪些工具或 API？
3. 执行的逻辑步骤是什么？
4. 期望的输出格式是什么？

第二步：编写 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 知道什么时候该调用这个 Skill：

description: "浏览网页。当用户提到：网络搜索、搜索、查查看等操作时调用。"

执行步骤要清晰

这是最重要的部分！不要只告诉 Agent"做什么"，要告诉它"怎么做"：

## 执行步骤

1. **解析用户需求**：确定用户想要执行什么操作（创建、查询、更新、删除）
2. **准备数据**：根据操作类型准备需要的数据
3. **调用 API**：使用 feishu_bitable_app_table_record 工具执行操作
4. **处理结果**：解析返回结果，格式化输出
5. **错误处理**：如果出错，提供友好的错误信息

示例要实用

用户说"帮我创建一个记录"时：
1. 确认要操作的多维表格（从上下文或询问用户获取）
2. 准备记录数据
3. 调用创建记录接口
4. 返回成功信息

总结

编写 Agent Skill 的核心在于：

1. 准确的定义 — 明确 Skill 能完成什么任务
2. 逐步执行的逻辑 — 这是 Skill 与普通知识库的本质区别！不仅要告诉 Agent 做什么，更要告诉它怎么做
3. 清晰的工具集成 — 说明白会用到哪些工具和 API
4. 具体的触发场景 — 让 Agent 知道什么时候该调用这个 Skill
5. 错误处理 — 考虑边界情况和错误处理

掌握了这些要点，你就可以为任何 Agent 框架编写 Skill，让 AI Agent 从"能思考"变成"能干活"。

   学习资源推荐

如果你想更深入地学习大模型，以下是一些非常有价值的学习资源，这些资源将帮助你从不同角度学习大模型，提升你的实践能力。

一、全套AGI大模型学习路线

AI大模型时代的学习之旅：从基础到前沿，掌握人工智能的核心技能！​

因篇幅有限，仅展示部分资料，需要点击文章最下方名片即可前往获取

二、640套AI大模型报告合集

这套包含640份报告的合集，涵盖了AI大模型的理论研究、技术实现、行业应用等多个方面。无论您是科研人员、工程师，还是对AI大模型感兴趣的爱好者，这套报告合集都将为您提供宝贵的信息和启示

​因篇幅有限，仅展示部分资料，需要点击文章最下方名片即可前往获取

三、AI大模型经典PDF籍

随着人工智能技术的飞速发展，AI大模型已经成为了当今科技领域的一大热点。这些大型预训练模型，如GPT-3、BERT、XLNet等，以其强大的语言理解和生成能力，正在改变我们对人工智能的认识。 那以下这些PDF籍就是非常不错的学习资源。

因篇幅有限，仅展示部分资料，需要点击文章最下方名片即可前往获取

四、AI大模型商业化落地方案

作为普通人，入局大模型时代需要持续学习和实践，不断提高自己的技能和认知水平，同时也需要有责任感和伦理意识，为人工智能的健康发展贡献力量。