如何编写 Agent Skill在 AI Agent 框架中，Skill 是一个可重用的、结构化的程序，它定义了 AI

在 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 之前，先回答以下问题：

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

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

执行步骤要清晰

这是最重要的部分！不要只告诉 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 从"能思考"变成"能干活"。

如何编写 Agent Skill