给 AI 装“技能”：Agent Skills 完全指南

给 AI 装“技能”：Agent Skills 完全指南

你的 AI 助手终于可以不只是“会说话”，而是真正“会做事”了

想象一下这个场景：

你：帮我处理一下这张发票 PDF，把里面的金额、日期、发票号提取出来。

通用 AI：我无法直接读取 PDF 文件，但你可以把内容粘贴给我……

装了“发票处理技能”的 AI：（自动识别任务 → 调用专用脚本 → 输出结果）

字段	值
发票号码	INV-2024-0123
价税合计	12,800.00
销售方	XX科技有限公司

这就是Agent Skills的魅力——它让你的 AI 从“只能聊天”进化到“能动手干活”。

2025年12月18日，Anthropic 将 Agent Skills 正式发布为开放标准。一套标准化的文件夹规范，让 agent 像装 App 一样加载专业技能。标准一出，行业跟进速度惊人——Microsoft 在 VS Code 和 GitHub 里直接集成，OpenAI 在 ChatGPT 和 Codex CLI 里采用了几乎一模一样的架构，Cursor、Goose 等编码工具也纷纷跟进。截至 2026 年初，Atlassian、Figma、Canva、Stripe、Notion、Zapier 等厂商都已经为自家平台构建了相应的 skills。

一、Agent Skills 是什么？

一句话定义：Agent Skills 是一套标准化格式，用于将 AI 指令、脚本和资源打包成可复用、可发现的模块。

如果你用过 AI 编程助手，可能遇到过这样的问题：今天让 AI 帮你生成了一份符合公司规范的 PPT，明天换了一个对话，AI 就“忘”了这些规范，你得从头再说一遍。Skills 解决的就是这个问题——它把“这件事该怎么做”的知识固化下来，让 AI 每次都能按同一套标准执行。

它和 MCP 是什么关系？

很多第一次接触 Skills 的人会问：“不是已经有 MCP 了吗？” 这两个概念确实容易混淆，但定位完全不同：

MCP 解决的是「模型能用什么」；Skills 解决的是「模型该怎么用」。

打个比方：

• MCP是“工具箱”——它给 AI 接上了手和眼，让 AI 能够连接数据库、调用 API、读写文件
• Skills是“操作手册”——它告诉 AI，拿到这个工具后应该按照什么流程、什么标准去用

两者是互补关系，不是替代关系。一个强大的 Agent = 通用模型 + MCP 连接外部工具 + Skills 提供操作流程。

核心设计：渐进式披露

Skills 最精妙的设计是渐进式披露（Progressive Disclosure）——它把信息分成三层，按需加载：

这意味着：即使你有 100 个 skills 安装在系统中，AI 启动时也只加载它们的元数据（每个 skill 仅 30-50 个 tokens），只有当某个 skill 被判定为“相关”时，才会加载它的完整内容。这种设计既保证了能力丰富，又避免了上下文窗口被撑爆。

二、一个 Skill 长什么样？

每个 Skill 就是一个文件夹，包含一个必需的SKILL.md文件和若干可选的资源文件：

my-invoice-skill/ # 技能根目录 ├── SKILL.md # 【必需】核心定义文件 ├── scripts/ # 【可选】可执行脚本 │ └── extract_invoice.py ├── references/ # 【可选】参考文档 │ └── field_mapping.md └── assets/ # 【可选】静态资源 └── output_template.xlsx

SKILL.md 文件结构

SKILL.md采用YAML Frontmatter + Markdown 正文的双层结构：

---name:invoice-extractor# 必需：技能唯一标识（小写字母+连字符，最长64字符）description:从 PDF 发票中提取关键字段。当用户需要“解析发票”或“提取账单信息”时使用。license:MIT# 可选：许可证声明compatibility:需要 python3 及 PyPDF2# 可选：运行环境要求allowed-tools:Bash(python:*)# 可选：授权使用的工具---

关于 license：license: MIT表示该技能以 MIT 开源许可证发布，任何人都可以免费使用、修改和分发。如果只是个人或公司内部使用，这行可以删除或改为Proprietary。

Frontmatter 之后是 Markdown 格式的技能说明，包括角色定位、核心流程、输出格式、异常处理和示例对话。接下来我们就看一个完整的示例。

三、完整示例：发票信息提取技能

以下是一个可直接运行的完整 Skill，它封装了一个 Python 脚本，用于从 PDF 中提取发票信息。

1. SKILL.md

--- name: invoice-extractor description: 从 PDF 发票中提取关键字段（发票号、日期、金额、销售方等）。当用户需要“解析发票”、“提取发票信息”或“识别 PDF 中的账单数据”时使用。 compatibility: 需要 python3 及依赖库 PyPDF2、pdfplumber allowed-tools: Bash(python:*) --- # 发票信息提取技能 ## 角色 你是一名专门处理财务文档的数据提取助手。你的任务是调用指定的 Python 脚本，从用户提供的发票 PDF 中提取结构化数据。 ## 核心流程 1. **确认文件路径**：获取用户要处理的 PDF 文件路径。 2. **执行提取脚本**：运行以下命令调用核心逻辑。 ```bash python scripts/extract_invoice.py --pdf <用户提供的文件路径> --output invoice_result.json

3. 读取结果：命令执行成功后，读取生成的invoice_result.json文件。
4. 呈现给用户：将 JSON 内容转换为易于阅读的 Markdown 表格。

输出格式要求

• 提取状态：明确告知用户解析是否成功。
• 数据表格：使用 Markdown 表格展示提取到的字段。

示例输出表格

异常处理

• 若脚本执行失败，请将错误信息原文告知用户，并建议检查 PDF 是否清晰可读或是否为扫描件。
• 若 JSON 中success字段为false，直接向用户显示error字段的内容。

示例对话

用户：帮我提取D:/发票/3月办公费.pdf里的发票信息。

助手：
好的，我现在使用发票提取技能处理该文件。
（内部执行：python scripts/extract_invoice.py --pdf "D:/发票/3月办公费.pdf" --output invoice_result.json）

处理完成，提取结果如下：

### 2. scripts/extract_invoice.py 脚本需要遵循**标准化接口**和**结构化输出**的规范，这样才能被 AI 可靠地调用： ```python #!/usr/bin/env python3 # scripts/extract_invoice.py import argparse import json import sys import os def main(): parser = argparse.ArgumentParser(description="提取 PDF 发票信息") parser.add_argument("--pdf", required=True, help="发票 PDF 文件路径") parser.add_argument("--output", default="invoice_result.json", help="输出 JSON 文件路径") args = parser.parse_args() # 检查输入文件是否存在 if not os.path.exists(args.pdf): result = {"success": False, "error": f"文件不存在：{args.pdf}"} with open(args.output, "w", encoding="utf-8") as f: json.dump(result, f, ensure_ascii=False, indent=2) print(json.dumps(result, ensure_ascii=False)) sys.exit(1) # ========== 在这里调用你的实际提取逻辑 ========== # 以下为模拟数据，请替换为真实的 PDF 解析代码 try: extracted_data = { "发票号码": "24332000000123456789", "开票日期": "2024-03-10", "价税合计": "3,580.00", "销售方名称": "晨光文具股份有限公司", "购买方名称": "上海XX信息技术有限公司" } result = {"success": True, "data": extracted_data} except Exception as e: result = {"success": False, "error": f"解析失败：{str(e)}"} # ============================================= # 输出结果到 JSON 文件 with open(args.output, "w", encoding="utf-8") as f: json.dump(result, f, ensure_ascii=False, indent=2) # 同时向 stdout 打印结果，方便 AI 直接读取 print(json.dumps(result, ensure_ascii=False)) if __name__ == "__main__": main()

关键规范：脚本输出必须是 JSON 格式，且必须包含success布尔字段。这样 AI 才能正确判断执行结果。日志输出请使用sys.stderr，避免污染 stdout。

四、如何部署和使用

部署位置

Skills 可以放在两个位置：

.claude/skills/ ├── invoice-extractor/ │ ├── SKILL.md │ └── scripts/ │ └── extract_invoice.py └── another-skill/ └── SKILL.md

调用方式

Skills 支持两种调用方式：

1. 自动触发：AI 根据description字段自动判断是否使用该技能。当用户说“帮我提取发票”时，AI 会自动加载invoice-extractor技能。
2. 手动调用：部分工具支持直接输入/加技能名来调用（如/invoice-extractor）。

常用工具

五、最佳实践与避坑指南

结合大量开发者的实践经验，以下是几个关键建议：

✅ 应该做的

1. description 写清楚“何时用”：这是 AI 判断是否触发 skill 的唯一依据，务必包含触发场景关键词。
2. 脚本输出必须是 JSON：AI 只能可靠地解析结构化数据。
3. 示例对话写一个：在 SKILL.md 中加入## 示例段落，能显著提升 AI 执行的准确度。
4. 大文档放到 references/：SKILL.md 正文推荐不超过 500 行，详细的参考文档放到 references 目录，在需要时用链接引用。
5. 解释“为什么”而不只是“做什么”：现代 AI 理解原理后能更好地应对边缘情况。

❌ 需要避免的

1. 指令塞太多：一次性把全部细节都写进 SKILL.md 正文，会导致 AI “晕掉”——信息过载反而降低执行质量。
2. 忽略安全校验：脚本中避免直接拼接用户输入执行rm -rf等危险命令，建议做路径白名单校验。
3. 日志污染 stdout：print("正在处理...")这类日志会混入 JSON 输出，导致 AI 解析失败。

六、总结

Agent Skills 让 AI 从“泛泛而谈”走向“专业做事”。它把领域知识、操作流程和执行脚本打包成一个可复用的模块，让 AI 每次都能按同一套高标准完成任务。

MCP 给 AI 装上了手脚，Skills 教会了 AI 怎么走路。

一个精心编写的 Skill，就像一份传承下来的“老师傅秘籍”——新人（AI）拿到它，就能立刻按最高标准干活。

现在，去创建你的第一个 Skill 吧！你会发现，让 AI 真正“会做事”，其实只需要一个文件夹和一个 Markdown 文件。