Lyirs的小屋

主题

智能体技能 ​

Agent Skills

Skills 是由 Anthropic 于 2025 年 6 月 推出的新一代智能体能力协议，是一种轻量级、开放的格式，用于通过专业知识和工作流来扩展 AI 智能体的能力。如果说 MCP 定义了"AI 如何连接外部工具"，那么 Skills 则定义了 "AI 如何学习和执行复杂任务"

您的浏览器不支持 SVG

基本结构 ​

一个 Skill 的核心就是一个包含 SKILL.md 文件的文件夹。该文件包含元数据（至少需要 name 和 description）以及指导智能体执行特定任务的说明。Skills 还可以捆绑脚本、模板和参考资料。

skill-name/
└── SKILL.md          # 必需

提示

你可以选择性地包含附加目录，如 scripts/、references/ 和 assets/ 来支持你的 Skill。

工作原理 ​

Skills 采用渐进式披露（Progressive Disclosure） 机制来高效管理上下文：

Skills 应该结构化以高效使用上下文：

阶段内容大小建议加载时机
1. 元数据name 和 description 字段~100 tokens启动时为所有技能加载
2. 说明完整的 SKILL.md 正文< 5000 tokens技能激活时加载
3. 资源scripts/、references/、assets/ 中的文件按需仅在需要时加载

建议

将主 SKILL.md 保持在 500 行以下。将详细的参考材料移到单独的文件中。

三阶段执行流程 ​

阶段名称说明
1发现（Discovery）启动时，智能体仅加载每个可用 Skill 的名称和描述——刚好足够判断何时可能需要它
2激活（Activation）当任务匹配某个 Skill 的描述时，智能体将完整的 SKILL.md 说明读入上下文
3执行（Execution）智能体按照说明执行，根据需要加载引用的文件或执行捆绑的代码

设计优势

这种方式让智能体保持快速响应，同时能够按需获取更多上下文信息。

SKILL.md 格式 ​

SKILL.md 文件必须包含 YAML frontmatter，后跟 Markdown 内容。

markdown
---
name: pdf-processing
description: 从 PDF 文件中提取文本和表格，填写表单，合并文档。
---

# PDF 处理

## 何时使用此技能
当用户需要处理 PDF 文件时使用此技能...

## 如何提取文本
1. 使用 pdfplumber 进行文本提取...

## 如何填写表单
...

包含可选字段的完整示例：

yaml
---
name: pdf-processing
description: 从 PDF 文件中提取文本和表格，填写表单，合并文档。
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

字段说明 ​

字段是否必需约束条件
name是最多 64 个字符。仅限小写字母、数字和连字符。不能以连字符开头或结尾。
description是最多 1024 个字符。非空。描述技能的功能及使用场景。
license否许可证名称或捆绑许可证文件的引用。
compatibility否最多 500 个字符。指示环境要求（目标产品、系统包、网络访问等）。
metadata否任意键值映射，用于附加元数据。
allowed-tools否空格分隔的预批准工具列表。（实验性功能）
必需的 name 字段： ​
  • 必须为 1-64 个字符
  • 只能包含 Unicode 小写字母数字字符和连字符（a-z 和 -）
  • 不能以 - 开头或结尾
  • 不能包含连续连字符（--）
  • 必须与父目录名称匹配
yaml
name: pdf-processing
必需的 description 字段： ​
  • 必须为 1-1024 个字符
  • 应描述技能的功能和使用场景
  • 应包含帮助智能体识别相关任务的特定关键词
yaml
description: 从 PDF 文件中提取文本和表格，填写 PDF 表单，合并多个 PDF。当处理 PDF 文档或用户提及 PDF、表单或文档提取时使用。
可选的 license 字段： ​
  • 指定应用于该技能的许可证
  • 建议保持简短（许可证名称或捆绑许可证文件的名称）
yaml
license: Proprietary. LICENSE.txt has complete terms
可选的 compatibility 字段： ​
  • 如果提供，必须为 1-500 个字符
  • 仅在技能有特定环境要求时才应包含
  • 可以指示目标产品、所需系统包、网络访问需求等
yaml
compatibility: Designed for Claude Code (or similar products)

注意

大多数 Skills 不需要 compatibility 字段。

可选的 metadata 字段： ​
  • 从字符串键到字符串值的映射
  • 客户端可以使用它来存储 Agent Skills 规范未定义的附加属性
  • 建议使键名足够唯一以避免意外冲突
yaml
metadata:
  author: example-org
  version: "1.0"
可选的 allowed-tools 字段： ​
  • 空格分隔的预批准运行工具列表
  • 实验性功能。不同智能体实现对此字段的支持可能有所不同
yaml
allowed-tools: Bash(git:*) Bash(jq:*) Read

提示

Markdown 正文包含实际的说明内容，对结构或内容没有特定限制。

注意

智能体在决定激活技能后会加载整个文件。考虑将较长的 SKILL.md 内容拆分到引用文件中。

可选目录 ​

scripts/ ​

包含智能体可以运行的可执行代码。脚本应该：

  • 自包含或清楚地记录依赖项
  • 包含有用的错误消息
  • 优雅地处理边缘情况

支持的语言取决于智能体实现。常见选项包括 Python、Bash 和 JavaScript。

references/ ​

包含智能体在需要时可以读取的附加文档：

  • REFERENCE.md - 详细的技术参考
  • FORMS.md - 表单模板或结构化数据格式
  • 特定领域的文件（finance.md、legal.md 等）

提示

保持单个引用文件的专注性。智能体按需加载这些文件，因此较小的文件意味着较少的上下文使用。

assets/ ​

包含静态资源：

  • 模板（文档模板、配置模板）
  • 图片（图表、示例）
  • 数据文件（查找表、模式）

验证 ​

使用 skills-ref 参考库来验证你的 Skills：

bash
skills-ref validate ./my-skill

这会检查你的 SKILL.md frontmatter 是否有效，并遵循所有命名约定。