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

网址Overview - Agent SkillsgithubGitHub - agentskills/agentskills: Specification and documentation for Agent Skills · GitHub目录1.Agent Skills--定义2.Agent Skills--运行3.Agent Skills--SKILL.md3..1.前置元数据3.2.name3.3.description 字段3.4.正文内容3.5.渐进式披露3.6.文件引用3.7.验证4.Agent Skills--客户端5.Agent Skills--Cursor6.Agent Skills--自定义skills1.Agent Skills--定义智能体技能是一种轻量级、开放的格式用于通过专业知识和工作流程扩展智能体能力。其核心一个skill是一个包含SKILL.md文件的文件夹。这个文件包括元数据name和description至少以及指导智能体如何执行特定任务的指令。技能还可以捆绑脚本、模板和参考资料my-skill/ ├── SKILL.md # 必须的说明 元数据 ├── scripts/ # 可选的可执行代码 ├── references/ # 可选的文档 └── assets/ # 可选模板、资源 └── ... #任何其他文件或目录2.Agent Skills--运行Skills 使用渐进式披露来高效管理上下文发现启动时智能体仅加载每个可用技能的名称和描述仅足够知道何时可能相关。激活: 当一个任务与技能的描述相匹配时智能体将完整的SKILL.md指令读入上下文中。执行: 智能体遵循指令根据需要选择性地加载引用的文件或执行捆绑的代码。这种方法使智能体保持快速同时按需提供更多上下文访问。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是最多64个字符。仅限小写字母、数字和连字符。不能以连字符开头或结尾。description是最多1024个字符。非空。描述技能的作用以及何时使用它。license否许可证名称或对捆绑许可证文件的引用。compatibility否最大500字符。表示环境要求预期产品、系统软件包、网络访问等。metadata否任意键值映射以添加额外元数据。allowed-tools否以空格分隔的技能可能使用的预先批准的工具字符串。实验性--- 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-processingname:>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 DocsCursor 启动时会自动从技能目录中发现并加载技能并将它们提供给 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替换为模具上的边数例如标准为620为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-refskills-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-8content skill_md.read_text(encodingutf-8)(.venv) PS D:\pythonProject\python--postgraduate\agent\agentskills\skills-ref skills-ref validate D:\pythonProject\.agents\skills\test-1.14Validation 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-14Valid 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 nametest-1-14/name description这是一个用于测试的技能.../description !-- 其他元数据 -- /skill skill namecalculator/name description一个简单的计算器.../description /skill /available_skills重启cursor打开设置-rules查看技能6.Agent Skills--自定义skills那如果是通过代码的方式创建智能体比如langchain架构那我如何使用skills呢本指南将介绍如何为 AI 智能体或开发工具添加智能体技能支持。它涵盖了完整生命周期发现技能、向模型介绍它们、将它们的内容加载到上下文中并随着时间的推移保持这些内容的有效性。无论您的智能体的架构如何核心集成都是相同的。实现细节基于两个因素而有所不同技能在哪里存放本地运行的智能体可以扫描用户的文件系统以查找技能目录。云托管或沙盒化的智能体需要一种替代的发现机制——一个 API、一个远程注册表或捆绑的资产。模型如何访问技能内容如果模型具有文件读取功能它可以直接读取SKILL.md文件。否则您将提供一个专用工具或通过编程将技能内容注入提示中。指南指出了这些差异的重要性。你不需要支持每一种场景——选择适合你的智能体的路径。前提条件熟悉智能体技能规范 它定义了SKILL.md文件格式、前文字段和目录约定。