Agent Skills 智能体技能格式规范：从定义到实战

1. 引言随着大语言模型LLM能力的持续增强智能体Agent系统已经从单一的对话问答演进为能够自主规划、调用工具、执行复杂任务的综合平台。在这一演进过程中如何让智能体稳定、高效地复用和编排各种能力成为工程落地的关键问题。Agent Skills智能体技能正是为解决这一问题而提出的标准化方案。本文将围绕 Agent Skills 的格式规范展开从核心概念、目录结构、清单文件、技能定义、参数声明到代码实例逐步拆解一套可落地的技能格式规范帮助读者在自己的智能体项目中快速上手。2. 什么是 Agent SkillsAgent Skills 是一种将智能体可复用的能力单元进行标准化封装的方式。每个技能通常包含技能元数据名称、描述、版本、作者等基本信息。技能逻辑实际执行的代码或指令模板。输入输出契约声明技能接收哪些参数、返回什么结果。依赖与资源技能运行所需的依赖包、配置文件或外部服务。通过统一的格式规范智能体可以在运行时动态发现、加载和调用技能从而实现能力的即插即用。3. 技能目录结构规范一个标准的 Agent Skill 通常以独立目录形式存在推荐结构如下my-skill/ ├── SKILL.md # 技能清单文件必选 ├── skill.yaml # 技能元数据定义可选推荐 ├── src/ # 技能源码目录 │ ├── main.py # 主逻辑入口 │ └── utils.py # 辅助工具 ├── assets/ # 静态资源图片、模板等 ├── tests/ # 单元测试 │ └── test_main.py ├── requirements.txt # Python 依赖 └── README.md # 使用说明目录命名建议使用小写字母和连字符kebab-case例如text-summarizer、image-resizer。每个技能目录必须包含SKILL.md作为入口清单。4. SKILL.md 清单文件规范SKILL.md是技能的核心描述文件采用 Markdown 格式编写包含 YAML Front Matter 作为元数据头。以下是一个标准示例--- name: text-summarizer description: 对输入文本进行摘要提取支持中英文可指定摘要长度。 version: 1.0.0 author: agent-team license: MIT tags: - nlp - summarization - text parameters: - name: text type: string required: true description: 待摘要的原始文本。 - name: max_length type: integer required: false default: 200 description: 摘要最大长度字符数。 - name: language type: string required: false default: auto description: 语言可选 zh、en、auto。 --- Text Summarizer 本技能对输入文本进行自动摘要提取适用于新闻、报告、论文等长文本场景。 使用方式 调用本技能时传入待处理文本和可选参数返回摘要结果。 示例 输入 人工智能正在深刻改变各行各业的生产方式... 输出 人工智能通过自动化与智能化手段显著提升了生产效率。其中 Front Matter 中的parameters字段用于声明技能的输入契约智能体运行时可根据该声明自动生成调用参数。5. skill.yaml 元数据定义除了SKILL.md推荐使用skill.yaml提供机器可读的元数据便于智能体在运行时快速解析。示例name: text-summarizer version: 1.0.0 description: 对输入文本进行摘要提取支持中英文。 entry: src/main.py runtime: python3.11 dependencies: - transformers - torch environment: PYTHONUNBUFFERED: 1 permissions: network: false filesystem: read-only其中entry字段指定技能的主入口文件runtime声明运行环境permissions用于声明技能运行所需的权限边界增强安全性。6. 技能主逻辑实现技能主逻辑通常实现为一个可被智能体调用的函数或类。以下是一个基于 Python 的摘要技能实现# src/main.py from typing import Optional from transformers import pipeline class TextSummarizer: 文本摘要技能主类。 def __init__(self, model_name: str facebook/bart-large-cnn): self._pipe pipeline(summarization, modelmodel_name) def run( self, text: str, max_length: int 200, language: Optional[str] auto, ) - dict: 执行摘要提取。 Args: text: 待摘要文本。 max_length: 摘要最大长度。 language: 语言zh / en / auto。 Returns: 包含摘要结果的字典。 if not text.strip(): return {error: 输入文本不能为空} result self._pipe( text, max_lengthmax_length, min_lengthmax(10, int(max_length * 0.3)), do_sampleFalse, ) summary result[0][summary_text] return {summary: summary, length: len(summary)} def main(): 命令行入口便于本地调试。 import sys text sys.stdin.read() skill TextSummarizer() output skill.run(text) print(output) if name main: main()技能类需要提供统一的run方法作为调用入口返回结构化的字典结果便于智能体解析。7. 技能调用协议智能体与技能之间的调用建议遵循统一的 JSON-RPC 风格协议。请求格式如下{ jsonrpc: 2.0, id: 1, method: skill.invoke, params: { skill: text-summarizer, arguments: { text: 人工智能正在深刻改变各行各业的生产方式..., max_length: 150, language: zh } } }响应格式{ jsonrpc: 2.0, id: 1, result: { summary: 人工智能通过自动化与智能化手段显著提升了生产效率。, length: 28 } }当技能执行出错时返回错误对象{ jsonrpc: 2.0, id: 1, error: { code: -32001, message: 技能执行失败, data: { skill: text-summarizer, reason: 输入文本为空 } } }8. 技能注册与发现为了让智能体能够发现并加载技能需要维护一个技能注册表。以下是一个简单的注册表实现# src/registry.py import json from pathlib import Path from typing import Dict, Optional class SkillRegistry: 技能注册表负责扫描、注册和查找技能。 def __init__(self, skills_dir: str): self._skills_dir Path(skills_dir) self._skills: Dict[str, dict] {} def scan(self) - None: 扫描技能目录加载所有 SKILL.md 元数据。 for skill_dir in self._skills_dir.iterdir(): if not skill_dir.is_dir(): continue skill_file skill_dir / SKILL.md if not skill_file.exists(): continue metadata self._parse_skill_file(skill_file) self._skills[metadata[name]] { path: str(skill_dir), metadata: metadata, } def get(self, name: str) - Optional[dict]: 按名称查找技能。 return self._skills.get(name) def list(self) - list: 列出所有已注册技能。 return [ {name: name, description: info[metadata][description]} for name, info in self._skills.items() ] staticmethod def _parse_skill_file(path: Path) - dict: 解析 SKILL.md 的 Front Matter 元数据。 text path.read_text(encodingutf-8) if not text.startswith(---): raise ValueError(f无效的 SKILL.md: {path}) _, front_matter, _ text.split(---, 2) # 简化解析实际可使用 pyyaml metadata {} for line in front_matter.strip().splitlines(): if : in line: key, value line.split(:, 1) metadata[key.strip()] value.strip().strip() return metadata9. 技能测试规范每个技能应配套单元测试确保核心逻辑可验证。以下是一个基于 pytest 的测试示例# tests/test_main.py import sys from pathlib import Path sys.path.insert(0, str(Path(file).parent.parent / src)) from main import TextSummarizer def test_summarizer_empty_input(): skill TextSummarizer() result skill.run() assert error in result def test_summarizer_normal_input(): skill TextSummarizer() text 人工智能正在深刻改变各行各业的生产方式提升效率并降低成本。 result skill.run(text, max_length50, languagezh) assert summary in result assert len(result[summary]) 0测试文件应覆盖正常输入、边界输入和异常输入三类场景。10. 技能打包与分发技能可以通过标准打包工具进行分发。推荐使用zip格式打包整个技能目录cd skills/ zip -r text-summarizer.skill text-summarizer/打包后的技能文件可通过 HTTP 或对象存储分发智能体在运行时下载并校验完整性。建议在打包时附带校验文件shasum -a 256 text-summarizer.skill text-summarizer.skill.sha25611. 安全与权限规范技能运行涉及代码执行必须建立安全边界。建议遵循以下规范最小权限原则技能默认无网络访问权限按需显式声明。文件系统隔离技能只能访问自身目录和临时目录。依赖锁定使用requirements.txt锁定依赖版本避免供应链攻击。输入校验所有外部输入必须经过类型和长度校验。超时控制技能执行必须设置超时上限防止资源耗尽。以下是一个带超时控制的调用示例import signal class TimeoutError(Exception): pass def timeout_handler(signum, frame): raise TimeoutError(技能执行超时) def invoke_with_timeout(skill_func, timeout_seconds30, *args, **kwargs): 带超时控制的技能调用包装器。 signal.signal(signal.SIGALRM, timeout_handler) signal.alarm(timeout_seconds) try: return skill_func(*args, **kwargs) finally: signal.alarm(0)12. 总结Agent Skills 智能体技能格式规范的核心在于通过统一的目录结构、清单文件、元数据声明和调用协议将智能体的能力单元标准化、可复用化。本文从目录结构、SKILL.md、skill.yaml、主逻辑实现、调用协议、注册发现、测试、打包分发到安全规范给出了完整的落地参考。在实际项目中建议团队根据自身技术栈制定内部规范并配套脚手架工具和 CI 校验流程确保每个技能都符合格式要求。随着智能体生态的成熟标准化的技能格式将成为能力复用的重要基石。