【人工智能:Agent】--Agent Skills详解

网址：Overview - Agent Skills

github：

GitHub - agentskills/agentskills: Specification and documentation for Agent Skills · GitHub

目录

1.Agent Skills--定义

2.Agent Skills--运行

3.Agent Skills--SKILL.md

3..1.前置元数据

3.2.name

3.3.description 字段

3.4.正文内容

3.5.渐进式披露

3.6.文件引用

3.7.验证

4.Agent Skills--客户端

5.Agent Skills--Cursor

6.Agent Skills--自定义skills

1.Agent Skills--定义

智能体技能是一种轻量级、开放的格式，用于通过专业知识和工作流程扩展智能体能力。

其核心，一个skill是一个包含SKILL.md文件的文件夹。

这个文件包括元数据（name和description，至少）以及指导智能体如何执行特定任务的指令。技能还可以捆绑脚本、模板和参考资料：

my-skill/ ├── SKILL.md # 必须的：说明 + 元数据 ├── scripts/ # 可选的：可执行代码 ├── references/ # 可选的：文档 └── assets/ # 可选：模板、资源 └── ... #任何其他文件或目录

2.Agent Skills--运行

Skills 使用渐进式披露来高效管理上下文：

1. 发现：启动时，智能体仅加载每个可用技能的名称和描述，仅足够知道何时可能相关。
2. 激活: 当一个任务与技能的描述相匹配时，智能体将完整的SKILL.md指令读入上下文中。
3. 执行: 智能体遵循指令，根据需要选择性地加载引用的文件或执行捆绑的代码。

这种方法使智能体保持快速，同时按需提供更多上下文访问。

3.Agent Skills--SKILL.md

每个技能都以一个SKILL.md文件开始，其中包含 YAML 前置文本和 Markdown 说明：

--- name: pdf-processing description: 提取 PDF 文本、填写表单、合并文件。处理 PDF 时请使用此技能。 --- # PDF 处理 ## 何时使用此技能 当用户需要处理 PDF 文件时，请使用此技能…… ## 如何提取文本 1. 使用 pdfplumber 进行文本提取…… ## 如何填写表单 ……

在SKILL.md的顶部需要以下前置文本：

• name: 简短的标识符
• description: 何时使用此技能

Markdown 正文包含实际指令，对结构或内容没有特定限制。这种简单的格式有一些关键优势：

• 自文档化：技能作者或用户可以阅读一个SKILL.md并理解它的作用，使技能易于审计和改进。
• 可扩展：技能的复杂度可以从纯文本指令到可执行代码、资源和模板不等。
• 便携式：技能只是文件，因此它们易于编辑、版本控制和共享。

3..1.前置元数据

--- name: pdf-processing description: 提取 PDF 文本、填写表单、合并文件。处理 PDF 时请使用此技能。 license: Apache-2.0 metadata: author: example-org version: "1.0" ---

3.2.name

必需的name字段：

• 必须为1-64个字符
• 只能包含 unicode 小写字母数字字符(a-z)和连字符(-)
• 不得以连字符（-）开头或结尾
• 不得包含连续的连字符（--）
• 必须与父目录名称匹配

有效示例：

name: pdf-processing

name:>3.3.description字段
所需description字段：
必须为 1-1024 个字符
应描述该技能的作用以及何时使用它
应包含特定关键词，帮助智能体识别相关任务
好的例子：
description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.
糟糕的例子：
description: Helps with PDFs.
3.4.正文内容
前文之后，Markdown 正文包含技能说明。没有格式限制。写任何有助于智能体有效执行任务的内容。推荐部分：
逐步说明
输入和输出的示例
常见边缘情况
请注意，智能体在决定激活一个技能时，会加载整个文件。建议将较长的SKILL.md内容拆分到引用的文件中。
scripts/包含智能体可以运行的执行代码。脚本应该：
自包含或明确记录依赖关系
包含有用的错误消息
优雅地处理边缘情况
支持的语言取决于智能体的实现。常见选项包括 Python、Bash 和 JavaScript。
references/包含智能体在需要时可以阅读的附加文档：
REFERENCE.md- 详细技术参考
FORMS.md- 表单模板或结构化数据格式
特定领域的文件（finance.md,legal.md, 等）
保持单个 参考文件 聚焦。智能体按需加载这些文件，因此较小的文件意味着更少的上下文使用。
assets/包含静态资源：
模板（文档模板、配置模板）
图片（图表、示例）
数据文件（查找表、模式）
3.5.渐进式披露
技能应针对上下文的有效使用进行结构化：
元数据(~100 个 token)：所有技能的name和description字段在启动时加载
说明(< 5000 个 token 推荐): 当技能被激活时，完整的SKILL.md主体将被加载
资源(按需使用): 文件（例如位于scripts/、references/或assets/中的文件）仅在需要时才被加载
保持你的主SKILL.md文件在 500 行以内。将详细的参考资料移到单独的文件中。
“渐进式披露”其实就是一种按需加载的策略，专门用来解决“上下文窗口”不够用的问题。
简单来说，它的核心思想是：不要一次性把所有信息都塞给 AI，而是根据 AI 当前的需要，分阶段、有层次地提供信息。
3.6.文件引用
在技能中引用其他文件时，请使用从技能根目录开始的相对路径：
SKILL.md
参见[ 参考指南 ](references/REFERENCE.md)了解详情。 运行提取脚本： scripts/extract.py
保持文件引用与SKILL.md保持一级深度，避免深层嵌套的引用链。
3.7.验证
使用 skills-ref 技能参考库来验证你的技能：
skills-ref validate ./my-skill
这检查您的SKILL.md是否有效并遵循所有命名约定。
4.Agent Skills--客户端
支持Agent Skills格式的智能体产品。
5.Agent Skills--Cursor
我们这里使用cursor为例子，进行实战：Agent Skills | Cursor Docs
Cursor 启动时，会自动从技能目录中发现并加载技能，并将它们提供给 Agent 使用。Agent 会看到所有可用技能，并根据当前上下文决定何时调用它们。
你也可以在 Agent 对话中输入/并搜索技能名称来手动调用技能。
5.1.技能目录
技能会自动从以下位置加载：
位置
作用域
.agents/skills/
项目级
.cursor/skills/
项目级
~/.cursor/skills/
用户级（全局）
为了兼容性，Cursor 还会从 Claude 和 Codex 目录加载技能：.claude/skills/、.codex/skills/、~/.claude/skills/和~/.codex/skills/。
每个技能应为一个包含SKILL.md文件的文件夹：
.agents/ └── skills/ └── my-skill/ └── SKILL.md
技能还可以包含脚本、参考文件和资源等可选目录：
.agents/ └── skills/ └── deploy-app/ ├── SKILL.md ├── scripts/ │ ├── deploy.sh │ └── validate.py ├── references/ │ └── REFERENCE.md └── assets/ └── config-template.json
我这里进入cursor创建这个每一个目录：
然后写入测试的技能skill
--- name: test-1.14 description: 使用随机数生成器掷骰子。当被要求掷骰子（d6、d20等）、掷骰子或生成随机骰子时使用。 --- 要滚动模具，请使用以下命令从1生成随机数 给定的边数： ```bash echo $((RANDOM % <sides> + 1)) ``` ```powershell Get-Random -Minimum 1 -Maximum (<sides> + 1) ``` `<sides>`替换为模具上的边数（例如，标准为6，20为d20）。
这里我们验证一下：
下载这个包：
git clone https://github.com/agentskills/agentskills.git
进入skills-ref目录：
cd skills-ref
安装：（使用虚拟环境）
python -m venv .venv .venv\Scripts\Activate.ps1 pip install -e .
pip show skills-ref
skills-ref validate D:\pythonProject\.agents\skills\test-1.14
报错：编码问题， File "D:\pythonProject\python--postgraduate\agent\agentskills\skills-ref\src\skills_ref\validator.py", line 172, in validate
修改成支持utf-8
content = skill_md.read_text(encoding='utf-8')
(.venv) PS D:\pythonProject\python--postgraduate\agent\agentskills\skills-ref> skills-ref validate D:\pythonProject\.agents\skills\test-1.14
Validation failed for D:\pythonProject\.agents\skills\test-1.14:
- Skill name 'test-1.14' contains invalid characters. Only letters, digits, and hyphens are allowed.
🚫 错误原因
报错信息明确指出：Skill name 'test-1.14' contains invalid characters.
问题点：名称中包含了点号.。
规则：技能名称（即文件夹名）只能包含小写字母、数字和连字符-。
我们修改成：test-1-14
(.venv) PS D:\pythonProject\python--postgraduate\agent\agentskills\skills-ref> skills-ref validate D:\pythonProject\.agents\skills\test-1-14
Valid skill: D:\pythonProject\.agents\skills\test-1-14
太棒了！🎉 恭喜你，验证通过了！
看到Valid skill的提示，意味着你的第一个 Agent Skill 已经成功创建并符合规范。这就像是给 AI 写了一本专属的“操作手册”，现在这本手册已经通过了格式检查。
查看：
skills-ref read-properties D:\pythonProject\.agents\skills\test-1-14
🚀 3. 生成提示词 XML
命令：skills-ref to-prompt path/to/skill-a path/to/skill-b
作用：这是“部署工具”。它会将一个或多个技能转换成XML 格式的字符串。这是最关键的一步，因为 AI 模型（如 Claude、GPT-4）通常通过 XML 标签来理解它拥有哪些工具。
使用场景：
配置 Agent 系统提示词：你需要把生成的 XML 复制到你的 System Prompt 的<available_skills>标签中。
批量管理：你可以一次性传入多个技能路径，工具会自动把它们打包成一个大的 XML 块。
<available_skills> <skill> <name>test-1-14</name> <description>这是一个用于测试的技能...</description> <!-- 其他元数据 --> </skill> <skill> <name>calculator</name> <description>一个简单的计算器...</description> </skill> </available_skills>
重启cursor，打开设置-rules，查看技能：
6.Agent Skills--自定义skills
那如果是通过代码的方式创建智能体，比如langchain架构，那我如何使用skills呢
本指南将介绍如何为 AI 智能体或开发工具添加智能体技能支持。它涵盖了完整生命周期：发现技能、向模型介绍它们、将它们的内容加载到上下文中，并随着时间的推移保持这些内容的有效性。无论您的智能体的架构如何，核心集成都是相同的。实现细节基于两个因素而有所不同：
技能在哪里存放？本地运行的智能体可以扫描用户的文件系统以查找技能目录。云托管或沙盒化的智能体需要一种替代的发现机制——一个 API、一个远程注册表或捆绑的资产。
模型如何访问技能内容？如果模型具有文件读取功能，它可以直接读取SKILL.md文件。否则，您将提供一个专用工具或通过编程将技能内容注入提示中。
指南指出了这些差异的重要性。你不需要支持每一种场景——选择适合你的智能体的路径。前提条件：熟悉智能体技能规范 ，它定义了SKILL.md文件格式、前文字段和目录约定。