如果你最近刷到过那套标题为“从安装到 Skills 实战再到多 Agent 协作”的 5 小时 Agent Skills 教程应该会注意到一个现象真正值钱的内容不是某个框架的 API 怎么调而是“如何把一个能力做成可复用的 Skill”。评论区最常见的提问不是“这段代码什么意思”而是“为什么我的 Agent 就是不调用这个 Skill”。这不是个例。过去一年AI Agent 的开发模式正在从“堆 Prompt 堆工具函数”切换到“能力模块化”。模型负责思考Skill 负责执行Agent 负责编排。这篇文章就围绕这条主线展开先讲清楚 Agent、Tool、Skill 的区别再带你从零搭建一个可用的 Skill 项目最后用一个多 Agent 协作示例说明 Skill 在生产项目里该怎么组织。读完你应该能回答三个问题Agent Skills 到底解决什么问题一个合格的 Skill 目录结构长什么样多 Agent 场景下Skill 的边界应该划在哪里。1. 为什么 Agent Skills 值得专门花时间研究1.1 先看一个真实的开发痛点很多团队把大模型接进业务后初期效果惊艳一个月后却陷入维护泥潭业务规则放在 system prompt 里改一次规则要重新调一遍所有对话工具函数写了上百个模型经常在相似函数之间选错同一个“代码审查”逻辑在 A 项目的 Agent 里实现一遍在 B 项目里又要重写多 Agent 协作时每个 Agent 各写一套处理逻辑换人接手直接看不懂。这些问题本质上是同一个能力没有模块化。Agent 的“决策外壳”和“执行能力”绑得太紧。1.2 Skill 化之后发生了什么把能力抽成 Skill 之后变化发生在三个层面复用层一个代码审查 Skill可以被主 Agent、审查 Agent、代码生成 Agent 共用维护层修改规则只需要改 Skill 内部文件不需要动 Agent 的决策逻辑评测层Skill 有固定输入和输出可以单独跑一组测试用例验证质量。换句话说Agent Skills 不是某个厂商的专属功能而是 Agent 工程化的一种组织方式。它把“让模型知道怎么做”和“让系统真正能执行”分开来管理。1.3 什么样的读者最需要这篇文章已经跑通过一个 Agent Demo但不知道怎么接真实业务在多 Agent 项目里发现无法协作想找一套拆解任务的思路想系统学习 Agent 开发但被各种框架术语绕晕。对完全没有接触过 Agent 的读者本文也尽量从最小概念讲起所有代码示例都可以直接复制跑通。2. 先搞清楚三个概念Agent、Tool、Skill写 Agent Skills 最容易踩的第一个坑是分不清这三个词。网上很多教程把 Tool 和 Skill 混着用导致模型调用逻辑越来越乱。2.1 概念对比维度Tool工具Skill技能Agent智能体本质单个可执行函数一组能力包指令 脚本 示例具备感知、规划、行动的执行体粒度最小中等跨多个步骤最大负责完整任务是否包含使用说明通常只有函数签名包含描述、步骤和示例不直接包含执行细节是否自己决策否否等待被调用是典型示例调用天气查询 API代码审查、数据清洗、报表生成需求拆解 Agent、编码 Agent2.2 一句话区分Tool 是“手”能执行一个具体动作但它不知道什么时候该动手Skill 是“一套动作 使用手册”告诉模型在什么场景用、按什么步骤做、用什么脚本执行Agent 是“大脑 调度器”分析任务、选择调用哪个 Skill、决定什么时候停。用一个现实类比Agent 是餐厅店长Skill 是后厨的标准化菜谱Tool 是单个灶台或一把刀。店长不会直接去切菜但必须知道哪道菜该交给哪个后厨、按什么菜谱做。2.3 Skill 和 Function Calling 的区别很多人在实际开发中会混淆 Skill 与 Function Calling。这两者有联系但有本质区别Function Calling 是模型输出结构化参数、由系统调用函数的一种机制更偏向协议层面Skill 是比函数更高一层的“能力封装”它可能依赖多个函数、可能包含执行步骤、可能还附带示例输入输出一个 Skill 内部完全可以封装 Function Calling但反过来不行。这种分层设计的好处是即使底层大模型从一个厂商切换到另一个厂商只要 Skill 的接口不变Agent 的调度逻辑就基本不需要动。另外有的框架把 Agent 周围负责编排、上下文管理的那一层称为 harness 或 orchestrator。它属于 Agent 的“骨架”负责连接模型与 Skill。理解这个分层再去看各种框架文档会轻松很多。3. Skill 的典型应用场景与选型判断3.1 适合用 Skill 的场景从实际项目看以下场景用 Skill 化收益最明显固定流程类代码审查、SQL 生成与校验、单元测试生成、数据报表输出领域知识类财务税务计算、医疗文本结构化、法律条款核对多步操作类先读取文件、再清洗、再建模、最后输出报告团队协作类多个 Agent 共享同一套领域规则。这些场景有一个共同点步骤相对固定、规则变化频繁、需要统一维护。近期吴恩达在多个 Agent 公开课程里反复强调的也是这个方向——把 agentic workflow 拆成可复用的技能单元而不是把全部逻辑塞进提示词。3.2 不适合用 Skill 的场景反过来如果任务每次都是全新的、几乎没有重复逻辑强行 Skill 化只会增加维护成本。例如一次性数据分析探索纯闲聊型对话完全依赖模型临场发挥的头脑风暴。Skill 的价值在于“重复”没有重复就没有必要封装。3.3 选型建议框架还是自行实现现在各大厂商和开源社区都提供了 Agent Skills 相关实现有的以插件形式存在有的以标准目录结构加脚本的形式存在。对学习阶段更推荐先自行实现一个最小版本原因有两个能理解 Skill 的本质而不是被框架 API 带偏最小实现只有几十行代码出了问题容易排查。框架带来的收益主要在工程化层面比如请求重试、上下文管理、并发控制。这些可以等最小版本跑通后再引入。4. 环境准备与前置条件本文的示例使用 Python选择 Python 是因为它在 Agent 生态里资料最全、排错最容易。示例代码不依赖任何特定大模型 API核心逻辑可以独立运行。4.1 本地环境要求操作系统Windows / macOS / Linux 均可Python 版本建议 3.10 及以上代码用到了 pathlib 和标准库不需要额外安装第三方包命令行能执行python或python3。4.2 创建项目目录mkdir agent-skills-demo cd agent-skills-demo python -m venv .venv source .venv/bin/activateWindows 下激活虚拟环境执行.venv\Scripts\activate。4.3 整体目录规划agent-skills-demo/ ├── skills/ │ └── code_review/ │ ├── SKILL.md │ ├── review.py │ └── examples/ │ └── bad_demo.py ├── agent_core.py └── main.py说明skills/存放所有可复用 Skill每个 Skill 一个子目录SKILL.md是 Skill 的“使用手册”供模型读取review.py是 Skill 的“执行引擎”agent_core.py负责加载 Skillmain.py演示多 Agent 协作流程。5. 从零实现一个代码审查 Skill为了把概念落到能跑的代码上我们实现一个“代码审查 Skill”。这个 Skill 解决一个真实场景多 Agent 协作生成代码后需要一个统一、可复用、规则可维护的检查环节。5.1 第一步编写 SKILL.mdSKILL.md是整个 Skill 的灵魂。它不仅是给人看的文档更是模型决定“要不要调用这个 Skill”的依据。# 文件路径skills/code_review/SKILL.md --- name: code_review description: - 对一份源代码执行静态审查输出风险点、风险等级和修复建议。 当用户要求“审查代码”“检查 Bug”“Review 代码”“评估代码质量”时使用。 调用前需要拿到目标文件路径 target_path。 --- # Code Review Skill ## 输入 - target_path: 待审查的源文件路径可以是绝对路径或相对路径 ## 执行步骤 1. 确认 target_path 存在且为文本文件 2. 调用 review.py 对文件做 AST 静态分析 3. 按 review.py 返回的结果生成 markdown 审查报告 4. 如果发现高风险问题必须额外给出修复示例 ## 注意事项 - 只分析代码内容不执行目标代码 - 如果文件无法解析在报告中说明原因不中断整个流程关键点在于description字段。模型通过 description 决定是否调用这个 Skill描述里必须包含触发场景、必要参数以及调用前需要准备什么。很多 Agent 不调用 Skill一半以上是 description 写得不像“使用场景说明”而像“功能简介”。5.2 第二步实现执行脚本 review.py执行脚本负责真正的静态检查。这里用 Python 标准库自带的ast模块解析被审查代码不执行目标代码保证安全性。# 文件路径skills/code_review/review.py import ast import sys from pathlib import Path def analyze_file(target_path: str) - dict: 对指定 Python 文件做启发式静态审查 source_code Path(target_path).read_text(encodingutf-8) tree ast.parse(source_code) risks [] for node in ast.walk(tree): # 规则 1裸 try/except 会吞掉异常风险等级中 if isinstance(node, ast.Try): for handler in node.handlers: if handler.type is None and handler.name is None: risks.append({ line: node.lineno, type: 裸 except 吞掉异常, level: 中, suggestion: 捕获具体异常类型并记录 error 日志, }) # 规则 2函数分支过多说明可读性差风险等级低 if isinstance(node, ast.FunctionDef): branch_count sum( 1 for child in ast.walk(node) if isinstance(child, (ast.If, ast.While, ast.For)) ) if branch_count 5: risks.append({ line: node.lineno, type: 函数分支过多, level: 低, suggestion: 拆分为多个小函数, }) return { file: target_path, risk_count: len(risks), risks: risks, } if __name__ __main__: if len(sys.argv) ! 2: print(用法: python review.py 源文件路径) sys.exit(1) result analyze_file(sys.argv[1]) print(result)这段代码展示了 Skill 的一个核心设计规则集中在脚本里便于单独测试和维护。想要增加审查规则只需要在analyze_file中追加ast节点判断逻辑。这里真正容易踩坑的地方是 AST 输出行号与源文件行号对齐的问题。ast.parse在语法错误时会直接抛异常所以脚本里建议后续捕获SyntaxError避免因为一个文件解析失败导致整个 Agent 流程中断。5.3 第三步写一个故意有问题的示例为了验证 Skill 生效建一个带问题的示例文件。# 文件路径skills/code_review/examples/bad_demo.py def divide(a, b): try: return a / b except: return None这个文件有一个明显问题裸except会吞掉所有异常包括键盘中断和系统退出。用我们的 Skill 至少能检查出这个问题。5.4 第四步实现 Skill 加载器 agent_core.pyAgent 需要一个统一入口加载 Skill。加载器把SKILL.md里的描述和脚本里的函数绑定在一起。# 文件路径agent_core.py import importlib.util import re from pathlib import Path class SkillRegistry: 简化版 Skill 注册表负责发现、加载和缓存 Skill def __init__(self, skills_root: Path): self.skills_root Path(skills_root) self._skills {} def discover(self): for skill_dir in self.skills_root.iterdir(): if not skill_dir.is_dir(): continue md_path skill_dir / SKILL.md if not md_path.exists(): continue self._load_one(skill_dir, md_path) return self._skills def get(self, name: str) - dict: if name not in self._skills: raise KeyError(fSkill 未注册: {name}) return self._skills[name] def _load_one(self, skill_dir: Path, md_path: Path): text md_path.read_text(encodingutf-8) name_match re.search(r^name:\s*(\S), text, re.MULTILINE) if not name_match: raise ValueError(f{md_path} 缺少 name 字段) name name_match.group(1) script_path skill_dir / review.py if not script_path.exists(): raise FileNotFoundError(f{skill_dir} 缺少执行脚本 review.py) spec importlib.util.spec_from_file_location(f{name}_impl, script_path) module importlib.util.module_from_spec(spec) spec.loader.exec_module(module) self._skills[name] { name: name, description: self._parse_description(text), analyze_file: module.analyze_file, } staticmethod def _parse_description(text: str) - str: match re.search( r^description:\s*\s*\n(.*?)^---, text, re.MULTILINE | re.DOTALL, ) if not match: return return .join( line.strip() for line in match.group(1).splitlines() if line.strip() )这个注册表的职责很简单扫描skills/目录、解析SKILL.md元信息、动态加载脚本。真实项目中这里会变成框架的插件机制但核心思想一样。6. 多 Agent 协作Skill 如何支撑复杂任务有了可复用的 Skill多 Agent 协作才有意义。如果每个 Agent 都自己实现一套审查逻辑协作就变成了代码复制大赛。6.1 协作模式编排者 角色 Agent在真实项目中多 Agent 协作最常见的模式是一个编排者Orchestrator负责拆解任务、分配子任务多个角色 Agent需求 Agent、编码 Agent、审查 Agent分别处理自己的环节每个角色 Agent 内部调用对应的 Skill 完成具体执行。在这种结构里Skill 是角色 Agent 的“专业能力”。审查 Agent 的决策逻辑只有一小段真正的专业能力都在code_reviewSkill 里。6.2 完整协作示例 main.py下面用一个最小可运行的流程演示需求拆解 Agent 把任务拆成步骤编码 Agent 生成代码审查 Agent 调用code_reviewSkill 检查结果。# 文件路径main.py import json from pathlib import Path from agent_core import SkillRegistry def role_decompose(task: str) - list[str]: 需求拆解 Agent将主任务拆成子步骤 生产环境这里调用大模型接口演示环境用固定规则 return [编写实现代码, 执行代码审查, 输出修复建议] def role_coder(task_step: str) - str: 编码 Agent生成代码并落盘 生产环境由大模型生成演示环境写入一段固定样例代码 code ( def divide(a, b):\n try:\n return a / b\n except:\n return None\n ) target Path(tmp_work/target.py) target.parent.mkdir(exist_okTrue) target.write_text(code, encodingutf-8) return str(target) def role_reviewer(registry: SkillRegistry, file_path: str) - dict: 审查 Agent调用 code_review Skill 执行检查 skill registry.get(code_review) return skill[analyze_file](file_path) def main_flow(task: str) - dict: registry SkillRegistry(Path(skills)) registry.discover() steps role_decompose(task) report None target None for step in steps: if 编码 in step or 实现 in step: target role_coder(step) if 审查 in step or 检查 in step: report role_reviewer(registry, target) return report if __name__ __main__: result main_flow(实现一个除法函数并执行代码审查) print(json.dumps(result, ensure_asciiFalse, indent2))注意演示代码里刻意没有接真实大模型因为本文的重点是 Skill 的工程结构而不是某个模型的 API。真实项目中role_decompose、role_coder都会替换成大模型调用但role_reviewer这段调用 Skill 的代码基本保持不变。这就是 Skill 化带来的稳定性模型的输出可以不稳定但审查规则是确定的。6.3 分工的边界在多 Agent 场景里划分 Skill 边界有三条原则按能力域划分不按 Agent 划分比如“代码审查”是一个能力域而不是“审查 Agent 的私有逻辑”一个 Skill 只做一件事审查就是审查不要顺手做格式化、部署Skill 之间不要互相调用协作应该发生在 Agent 层而不是 Skill 内部。否则会形成难以排查的调用链。7. 运行验证与结果判断代码写完不代表结束Skill 工程化最重要的一步是验证。7.1 单独验证 Skill先不启动整个流程单独运行review.py验证 Skill 本身是否可用。python skills/code_review/review.py skills/code_review/examples/bad_demo.py预期输出不同 Python 版本下字典顺序可能有差异但结构一致{file: skills/code_review/examples/bad_demo.py, risk_count: 1, risks: [{line: 3, type: 裸 except 吞掉异常, level: 中, suggestion: 捕获具体异常类型并记录 error 日志}]}如果能看到risk_count: 1说明 Skill 的执行脚本工作正常。7.2 验证 Skill 加载器python -c from agent_core import SkillRegistry; from pathlib import Path; r SkillRegistry(Path(skills)); print(r.discover().keys())预期输出dict_keys([code_review])。如果为空检查skills/目录结构和SKILL.md的name字段是否拼写正确。7.3 验证多 Agent 协作流程python main.py预期输出是一份包含file、risk_count、risks的 JSON。这里最容易出现的错误是agent execution terminated due to error.这类运行时中断。出现时不要先怀疑模型先检查三层脚本路径、模块导入、函数名是否匹配。7.4 判断成功与否的标准一个 Skill 算不算合格可以从四个维度判断能被发现注册表能扫到它能被描述模型读 description 后能理解使用场景能被调用执行脚本输出稳定结果能被复用在多个 Agent 流程中都能调用同一个函数。生产级别还要加第五条能被评测。给 Skill 准备一组固定测试用例每次修改后跑一遍防止改出回归问题。8. 常见问题与排查方法学习和实战中最常遇到的问题集中在描述不清、加载失败、流程中断和安全越权四个方面。问题现象可能原因排查方式解决方案Agent 从不调用某个 Skilldescription写得像功能简介没有触发场景检查 SKILL.md 的描述是否包含关键词和调用条件重写 description加入触发场景、必要参数、前置条件SKILL.md 解析失败注册表为空YAML frontmatter 缺少结束符或name字段写错用命令直接读取前 20 行检查格式确保前后---闭合name和description严格缩进agent execution terminated due to error.脚本路径错误或函数导入失败先单独运行 review.py再检查 agent_core.py 的导入逻辑确认文件路径存在函数名和_load_one中调用一致Skill 输出结果不稳定脚本内部使用了非确定性逻辑或解析了错误文件对同一输入运行多次对比输出把规则写成纯函数输入输出保持确定性多 Agent 场景互相干扰Skill 内部依赖全局变量或共享文件检查是否有全局状态观察并发调用现象Skill 内只使用局部变量文件写入使用隔离目录Skill 执行了危险操作脚本包含删除、执行外部命令等高风险逻辑审查 Skill 脚本的文件操作和系统调用收敛权限禁止高风险调用增加沙箱隔离9. 最佳实践与工程建议9.1 配置文件级守护SKILL.md 是给模型看的写 Skill 时最容易忽略的是description的语义质量。一个合格的描述应该回答三个问题何时用、怎么用、需要什么输入。可以参考下面的模板--- name: 技能名称 description: - 在[具体业务场景]中当用户[触发条件]时使用。 需要提供[必要参数]执行[关键动作]输出[产出物]。 ---如果发现模型经常在多个 Skill 之间选错大概率是 description 里的触发词重叠太多。这时要明确区分边界比如“审查”与“重构”不要同时出现在两个 Skill 的描述开头。9.2 保持单一职责一个 Skill 只负责一个能力域。宁可多建几个 Skill也不要在一个 Skill 里塞进“审查 格式化 部署”三件事。单一职责直接决定了 Skill 的可维护性和可复用性。9.3 规则代码与决策逻辑分离这一点在本文示例里体现得很明确审查规则写在review.py模型决策在main.py的 Agent 层。规则层应该完全确定性决策层可以接受不确定性。这种分离让测试变得容易也让非算法工程师也能维护规则。9.4 安全问题Skill 就是攻击面Skill 本质上是把大模型输出的“文本意图”翻译成“系统动作”因此它天然是攻击面。实际项目中要特别注意最小权限Skill 进程只授予完成任务所需的最小文件、网络和系统权限沙箱隔离涉及文件写入、命令执行时在独立沙箱或容器中运行审计日志记录谁在什么时候调用了哪个 Skill、传入了什么参数输入校验目标文件路径做白名单校验防止路径穿越禁止高危操作默认禁止删除文件、修改全局配置、执行未经验证的 shell 命令。9.5 版本管理与评测Skill 的规则会频繁变化建议像管理代码一样管理 Skill每个 Skill 目录纳入 Git 版本管理修改规则必须同步更新示例和测试用例发布前跑一遍 Skill 的回归用例在团队中建立“Skill 变更评审”流程避免规则被悄悄改坏。9.6 不要过早框架化很多初学者一上来就引入大型 Agent 框架结果被配置项淹没。更务实的学习路径是先用最小实现跑通一个 Skill理解目录结构、描述加载、脚本调用这三件事再引入框架的插件机制、并发控制和上下文管理最后再设计多 Agent 协作方案。10. 总结与后续学习方向Agent Skills 的流行本质上是 Agent 从 Demo 走向生产的必然结果。模型的思考能力再强如果没有稳定、可复用、可维护的执行能力Agent 就永远只是聊天机器人。Skill 化把“能力”从“决策”中剥离出来用一套统一的标准组织复杂任务这正是多 Agent 协作能够落地的前提。本文用一个最小可运行的代码审查示例走完了 Skill 从设计、编写、加载到多 Agent 复用的全过程。下一步你可以做三件事把code_review的规则扩展成自己业务里的检查项比如接口参数校验、SQL 注入风险扫描把role_decompose和role_coder替换成真实大模型调用感受模型决策与 Skill 执行分离的稳定性尝试拆分第二个 Skill然后观察多个 Skill 在同一个 Agent 流程里如何被调度。建议收藏这套目录结构和验证方法。后续无论切换到哪个框架、哪个模型这份“规则确定性 决策灵活性”的设计思路都不会过时。 Agent Skills 实战：从 Tool 到多 Agent 协作的模块化设计
如果你最近刷到过那套标题为“从安装到 Skills 实战再到多 Agent 协作”的 5 小时 Agent Skills 教程应该会注意到一个现象真正值钱的内容不是某个框架的 API 怎么调而是“如何把一个能力做成可复用的 Skill”。评论区最常见的提问不是“这段代码什么意思”而是“为什么我的 Agent 就是不调用这个 Skill”。这不是个例。过去一年AI Agent 的开发模式正在从“堆 Prompt 堆工具函数”切换到“能力模块化”。模型负责思考Skill 负责执行Agent 负责编排。这篇文章就围绕这条主线展开先讲清楚 Agent、Tool、Skill 的区别再带你从零搭建一个可用的 Skill 项目最后用一个多 Agent 协作示例说明 Skill 在生产项目里该怎么组织。读完你应该能回答三个问题Agent Skills 到底解决什么问题一个合格的 Skill 目录结构长什么样多 Agent 场景下Skill 的边界应该划在哪里。1. 为什么 Agent Skills 值得专门花时间研究1.1 先看一个真实的开发痛点很多团队把大模型接进业务后初期效果惊艳一个月后却陷入维护泥潭业务规则放在 system prompt 里改一次规则要重新调一遍所有对话工具函数写了上百个模型经常在相似函数之间选错同一个“代码审查”逻辑在 A 项目的 Agent 里实现一遍在 B 项目里又要重写多 Agent 协作时每个 Agent 各写一套处理逻辑换人接手直接看不懂。这些问题本质上是同一个能力没有模块化。Agent 的“决策外壳”和“执行能力”绑得太紧。1.2 Skill 化之后发生了什么把能力抽成 Skill 之后变化发生在三个层面复用层一个代码审查 Skill可以被主 Agent、审查 Agent、代码生成 Agent 共用维护层修改规则只需要改 Skill 内部文件不需要动 Agent 的决策逻辑评测层Skill 有固定输入和输出可以单独跑一组测试用例验证质量。换句话说Agent Skills 不是某个厂商的专属功能而是 Agent 工程化的一种组织方式。它把“让模型知道怎么做”和“让系统真正能执行”分开来管理。1.3 什么样的读者最需要这篇文章已经跑通过一个 Agent Demo但不知道怎么接真实业务在多 Agent 项目里发现无法协作想找一套拆解任务的思路想系统学习 Agent 开发但被各种框架术语绕晕。对完全没有接触过 Agent 的读者本文也尽量从最小概念讲起所有代码示例都可以直接复制跑通。2. 先搞清楚三个概念Agent、Tool、Skill写 Agent Skills 最容易踩的第一个坑是分不清这三个词。网上很多教程把 Tool 和 Skill 混着用导致模型调用逻辑越来越乱。2.1 概念对比维度Tool工具Skill技能Agent智能体本质单个可执行函数一组能力包指令 脚本 示例具备感知、规划、行动的执行体粒度最小中等跨多个步骤最大负责完整任务是否包含使用说明通常只有函数签名包含描述、步骤和示例不直接包含执行细节是否自己决策否否等待被调用是典型示例调用天气查询 API代码审查、数据清洗、报表生成需求拆解 Agent、编码 Agent2.2 一句话区分Tool 是“手”能执行一个具体动作但它不知道什么时候该动手Skill 是“一套动作 使用手册”告诉模型在什么场景用、按什么步骤做、用什么脚本执行Agent 是“大脑 调度器”分析任务、选择调用哪个 Skill、决定什么时候停。用一个现实类比Agent 是餐厅店长Skill 是后厨的标准化菜谱Tool 是单个灶台或一把刀。店长不会直接去切菜但必须知道哪道菜该交给哪个后厨、按什么菜谱做。2.3 Skill 和 Function Calling 的区别很多人在实际开发中会混淆 Skill 与 Function Calling。这两者有联系但有本质区别Function Calling 是模型输出结构化参数、由系统调用函数的一种机制更偏向协议层面Skill 是比函数更高一层的“能力封装”它可能依赖多个函数、可能包含执行步骤、可能还附带示例输入输出一个 Skill 内部完全可以封装 Function Calling但反过来不行。这种分层设计的好处是即使底层大模型从一个厂商切换到另一个厂商只要 Skill 的接口不变Agent 的调度逻辑就基本不需要动。另外有的框架把 Agent 周围负责编排、上下文管理的那一层称为 harness 或 orchestrator。它属于 Agent 的“骨架”负责连接模型与 Skill。理解这个分层再去看各种框架文档会轻松很多。3. Skill 的典型应用场景与选型判断3.1 适合用 Skill 的场景从实际项目看以下场景用 Skill 化收益最明显固定流程类代码审查、SQL 生成与校验、单元测试生成、数据报表输出领域知识类财务税务计算、医疗文本结构化、法律条款核对多步操作类先读取文件、再清洗、再建模、最后输出报告团队协作类多个 Agent 共享同一套领域规则。这些场景有一个共同点步骤相对固定、规则变化频繁、需要统一维护。近期吴恩达在多个 Agent 公开课程里反复强调的也是这个方向——把 agentic workflow 拆成可复用的技能单元而不是把全部逻辑塞进提示词。3.2 不适合用 Skill 的场景反过来如果任务每次都是全新的、几乎没有重复逻辑强行 Skill 化只会增加维护成本。例如一次性数据分析探索纯闲聊型对话完全依赖模型临场发挥的头脑风暴。Skill 的价值在于“重复”没有重复就没有必要封装。3.3 选型建议框架还是自行实现现在各大厂商和开源社区都提供了 Agent Skills 相关实现有的以插件形式存在有的以标准目录结构加脚本的形式存在。对学习阶段更推荐先自行实现一个最小版本原因有两个能理解 Skill 的本质而不是被框架 API 带偏最小实现只有几十行代码出了问题容易排查。框架带来的收益主要在工程化层面比如请求重试、上下文管理、并发控制。这些可以等最小版本跑通后再引入。4. 环境准备与前置条件本文的示例使用 Python选择 Python 是因为它在 Agent 生态里资料最全、排错最容易。示例代码不依赖任何特定大模型 API核心逻辑可以独立运行。4.1 本地环境要求操作系统Windows / macOS / Linux 均可Python 版本建议 3.10 及以上代码用到了 pathlib 和标准库不需要额外安装第三方包命令行能执行python或python3。4.2 创建项目目录mkdir agent-skills-demo cd agent-skills-demo python -m venv .venv source .venv/bin/activateWindows 下激活虚拟环境执行.venv\Scripts\activate。4.3 整体目录规划agent-skills-demo/ ├── skills/ │ └── code_review/ │ ├── SKILL.md │ ├── review.py │ └── examples/ │ └── bad_demo.py ├── agent_core.py └── main.py说明skills/存放所有可复用 Skill每个 Skill 一个子目录SKILL.md是 Skill 的“使用手册”供模型读取review.py是 Skill 的“执行引擎”agent_core.py负责加载 Skillmain.py演示多 Agent 协作流程。5. 从零实现一个代码审查 Skill为了把概念落到能跑的代码上我们实现一个“代码审查 Skill”。这个 Skill 解决一个真实场景多 Agent 协作生成代码后需要一个统一、可复用、规则可维护的检查环节。5.1 第一步编写 SKILL.mdSKILL.md是整个 Skill 的灵魂。它不仅是给人看的文档更是模型决定“要不要调用这个 Skill”的依据。# 文件路径skills/code_review/SKILL.md --- name: code_review description: - 对一份源代码执行静态审查输出风险点、风险等级和修复建议。 当用户要求“审查代码”“检查 Bug”“Review 代码”“评估代码质量”时使用。 调用前需要拿到目标文件路径 target_path。 --- # Code Review Skill ## 输入 - target_path: 待审查的源文件路径可以是绝对路径或相对路径 ## 执行步骤 1. 确认 target_path 存在且为文本文件 2. 调用 review.py 对文件做 AST 静态分析 3. 按 review.py 返回的结果生成 markdown 审查报告 4. 如果发现高风险问题必须额外给出修复示例 ## 注意事项 - 只分析代码内容不执行目标代码 - 如果文件无法解析在报告中说明原因不中断整个流程关键点在于description字段。模型通过 description 决定是否调用这个 Skill描述里必须包含触发场景、必要参数以及调用前需要准备什么。很多 Agent 不调用 Skill一半以上是 description 写得不像“使用场景说明”而像“功能简介”。5.2 第二步实现执行脚本 review.py执行脚本负责真正的静态检查。这里用 Python 标准库自带的ast模块解析被审查代码不执行目标代码保证安全性。# 文件路径skills/code_review/review.py import ast import sys from pathlib import Path def analyze_file(target_path: str) - dict: 对指定 Python 文件做启发式静态审查 source_code Path(target_path).read_text(encodingutf-8) tree ast.parse(source_code) risks [] for node in ast.walk(tree): # 规则 1裸 try/except 会吞掉异常风险等级中 if isinstance(node, ast.Try): for handler in node.handlers: if handler.type is None and handler.name is None: risks.append({ line: node.lineno, type: 裸 except 吞掉异常, level: 中, suggestion: 捕获具体异常类型并记录 error 日志, }) # 规则 2函数分支过多说明可读性差风险等级低 if isinstance(node, ast.FunctionDef): branch_count sum( 1 for child in ast.walk(node) if isinstance(child, (ast.If, ast.While, ast.For)) ) if branch_count 5: risks.append({ line: node.lineno, type: 函数分支过多, level: 低, suggestion: 拆分为多个小函数, }) return { file: target_path, risk_count: len(risks), risks: risks, } if __name__ __main__: if len(sys.argv) ! 2: print(用法: python review.py 源文件路径) sys.exit(1) result analyze_file(sys.argv[1]) print(result)这段代码展示了 Skill 的一个核心设计规则集中在脚本里便于单独测试和维护。想要增加审查规则只需要在analyze_file中追加ast节点判断逻辑。这里真正容易踩坑的地方是 AST 输出行号与源文件行号对齐的问题。ast.parse在语法错误时会直接抛异常所以脚本里建议后续捕获SyntaxError避免因为一个文件解析失败导致整个 Agent 流程中断。5.3 第三步写一个故意有问题的示例为了验证 Skill 生效建一个带问题的示例文件。# 文件路径skills/code_review/examples/bad_demo.py def divide(a, b): try: return a / b except: return None这个文件有一个明显问题裸except会吞掉所有异常包括键盘中断和系统退出。用我们的 Skill 至少能检查出这个问题。5.4 第四步实现 Skill 加载器 agent_core.pyAgent 需要一个统一入口加载 Skill。加载器把SKILL.md里的描述和脚本里的函数绑定在一起。# 文件路径agent_core.py import importlib.util import re from pathlib import Path class SkillRegistry: 简化版 Skill 注册表负责发现、加载和缓存 Skill def __init__(self, skills_root: Path): self.skills_root Path(skills_root) self._skills {} def discover(self): for skill_dir in self.skills_root.iterdir(): if not skill_dir.is_dir(): continue md_path skill_dir / SKILL.md if not md_path.exists(): continue self._load_one(skill_dir, md_path) return self._skills def get(self, name: str) - dict: if name not in self._skills: raise KeyError(fSkill 未注册: {name}) return self._skills[name] def _load_one(self, skill_dir: Path, md_path: Path): text md_path.read_text(encodingutf-8) name_match re.search(r^name:\s*(\S), text, re.MULTILINE) if not name_match: raise ValueError(f{md_path} 缺少 name 字段) name name_match.group(1) script_path skill_dir / review.py if not script_path.exists(): raise FileNotFoundError(f{skill_dir} 缺少执行脚本 review.py) spec importlib.util.spec_from_file_location(f{name}_impl, script_path) module importlib.util.module_from_spec(spec) spec.loader.exec_module(module) self._skills[name] { name: name, description: self._parse_description(text), analyze_file: module.analyze_file, } staticmethod def _parse_description(text: str) - str: match re.search( r^description:\s*\s*\n(.*?)^---, text, re.MULTILINE | re.DOTALL, ) if not match: return return .join( line.strip() for line in match.group(1).splitlines() if line.strip() )这个注册表的职责很简单扫描skills/目录、解析SKILL.md元信息、动态加载脚本。真实项目中这里会变成框架的插件机制但核心思想一样。6. 多 Agent 协作Skill 如何支撑复杂任务有了可复用的 Skill多 Agent 协作才有意义。如果每个 Agent 都自己实现一套审查逻辑协作就变成了代码复制大赛。6.1 协作模式编排者 角色 Agent在真实项目中多 Agent 协作最常见的模式是一个编排者Orchestrator负责拆解任务、分配子任务多个角色 Agent需求 Agent、编码 Agent、审查 Agent分别处理自己的环节每个角色 Agent 内部调用对应的 Skill 完成具体执行。在这种结构里Skill 是角色 Agent 的“专业能力”。审查 Agent 的决策逻辑只有一小段真正的专业能力都在code_reviewSkill 里。6.2 完整协作示例 main.py下面用一个最小可运行的流程演示需求拆解 Agent 把任务拆成步骤编码 Agent 生成代码审查 Agent 调用code_reviewSkill 检查结果。# 文件路径main.py import json from pathlib import Path from agent_core import SkillRegistry def role_decompose(task: str) - list[str]: 需求拆解 Agent将主任务拆成子步骤 生产环境这里调用大模型接口演示环境用固定规则 return [编写实现代码, 执行代码审查, 输出修复建议] def role_coder(task_step: str) - str: 编码 Agent生成代码并落盘 生产环境由大模型生成演示环境写入一段固定样例代码 code ( def divide(a, b):\n try:\n return a / b\n except:\n return None\n ) target Path(tmp_work/target.py) target.parent.mkdir(exist_okTrue) target.write_text(code, encodingutf-8) return str(target) def role_reviewer(registry: SkillRegistry, file_path: str) - dict: 审查 Agent调用 code_review Skill 执行检查 skill registry.get(code_review) return skill[analyze_file](file_path) def main_flow(task: str) - dict: registry SkillRegistry(Path(skills)) registry.discover() steps role_decompose(task) report None target None for step in steps: if 编码 in step or 实现 in step: target role_coder(step) if 审查 in step or 检查 in step: report role_reviewer(registry, target) return report if __name__ __main__: result main_flow(实现一个除法函数并执行代码审查) print(json.dumps(result, ensure_asciiFalse, indent2))注意演示代码里刻意没有接真实大模型因为本文的重点是 Skill 的工程结构而不是某个模型的 API。真实项目中role_decompose、role_coder都会替换成大模型调用但role_reviewer这段调用 Skill 的代码基本保持不变。这就是 Skill 化带来的稳定性模型的输出可以不稳定但审查规则是确定的。6.3 分工的边界在多 Agent 场景里划分 Skill 边界有三条原则按能力域划分不按 Agent 划分比如“代码审查”是一个能力域而不是“审查 Agent 的私有逻辑”一个 Skill 只做一件事审查就是审查不要顺手做格式化、部署Skill 之间不要互相调用协作应该发生在 Agent 层而不是 Skill 内部。否则会形成难以排查的调用链。7. 运行验证与结果判断代码写完不代表结束Skill 工程化最重要的一步是验证。7.1 单独验证 Skill先不启动整个流程单独运行review.py验证 Skill 本身是否可用。python skills/code_review/review.py skills/code_review/examples/bad_demo.py预期输出不同 Python 版本下字典顺序可能有差异但结构一致{file: skills/code_review/examples/bad_demo.py, risk_count: 1, risks: [{line: 3, type: 裸 except 吞掉异常, level: 中, suggestion: 捕获具体异常类型并记录 error 日志}]}如果能看到risk_count: 1说明 Skill 的执行脚本工作正常。7.2 验证 Skill 加载器python -c from agent_core import SkillRegistry; from pathlib import Path; r SkillRegistry(Path(skills)); print(r.discover().keys())预期输出dict_keys([code_review])。如果为空检查skills/目录结构和SKILL.md的name字段是否拼写正确。7.3 验证多 Agent 协作流程python main.py预期输出是一份包含file、risk_count、risks的 JSON。这里最容易出现的错误是agent execution terminated due to error.这类运行时中断。出现时不要先怀疑模型先检查三层脚本路径、模块导入、函数名是否匹配。7.4 判断成功与否的标准一个 Skill 算不算合格可以从四个维度判断能被发现注册表能扫到它能被描述模型读 description 后能理解使用场景能被调用执行脚本输出稳定结果能被复用在多个 Agent 流程中都能调用同一个函数。生产级别还要加第五条能被评测。给 Skill 准备一组固定测试用例每次修改后跑一遍防止改出回归问题。8. 常见问题与排查方法学习和实战中最常遇到的问题集中在描述不清、加载失败、流程中断和安全越权四个方面。问题现象可能原因排查方式解决方案Agent 从不调用某个 Skilldescription写得像功能简介没有触发场景检查 SKILL.md 的描述是否包含关键词和调用条件重写 description加入触发场景、必要参数、前置条件SKILL.md 解析失败注册表为空YAML frontmatter 缺少结束符或name字段写错用命令直接读取前 20 行检查格式确保前后---闭合name和description严格缩进agent execution terminated due to error.脚本路径错误或函数导入失败先单独运行 review.py再检查 agent_core.py 的导入逻辑确认文件路径存在函数名和_load_one中调用一致Skill 输出结果不稳定脚本内部使用了非确定性逻辑或解析了错误文件对同一输入运行多次对比输出把规则写成纯函数输入输出保持确定性多 Agent 场景互相干扰Skill 内部依赖全局变量或共享文件检查是否有全局状态观察并发调用现象Skill 内只使用局部变量文件写入使用隔离目录Skill 执行了危险操作脚本包含删除、执行外部命令等高风险逻辑审查 Skill 脚本的文件操作和系统调用收敛权限禁止高风险调用增加沙箱隔离9. 最佳实践与工程建议9.1 配置文件级守护SKILL.md 是给模型看的写 Skill 时最容易忽略的是description的语义质量。一个合格的描述应该回答三个问题何时用、怎么用、需要什么输入。可以参考下面的模板--- name: 技能名称 description: - 在[具体业务场景]中当用户[触发条件]时使用。 需要提供[必要参数]执行[关键动作]输出[产出物]。 ---如果发现模型经常在多个 Skill 之间选错大概率是 description 里的触发词重叠太多。这时要明确区分边界比如“审查”与“重构”不要同时出现在两个 Skill 的描述开头。9.2 保持单一职责一个 Skill 只负责一个能力域。宁可多建几个 Skill也不要在一个 Skill 里塞进“审查 格式化 部署”三件事。单一职责直接决定了 Skill 的可维护性和可复用性。9.3 规则代码与决策逻辑分离这一点在本文示例里体现得很明确审查规则写在review.py模型决策在main.py的 Agent 层。规则层应该完全确定性决策层可以接受不确定性。这种分离让测试变得容易也让非算法工程师也能维护规则。9.4 安全问题Skill 就是攻击面Skill 本质上是把大模型输出的“文本意图”翻译成“系统动作”因此它天然是攻击面。实际项目中要特别注意最小权限Skill 进程只授予完成任务所需的最小文件、网络和系统权限沙箱隔离涉及文件写入、命令执行时在独立沙箱或容器中运行审计日志记录谁在什么时候调用了哪个 Skill、传入了什么参数输入校验目标文件路径做白名单校验防止路径穿越禁止高危操作默认禁止删除文件、修改全局配置、执行未经验证的 shell 命令。9.5 版本管理与评测Skill 的规则会频繁变化建议像管理代码一样管理 Skill每个 Skill 目录纳入 Git 版本管理修改规则必须同步更新示例和测试用例发布前跑一遍 Skill 的回归用例在团队中建立“Skill 变更评审”流程避免规则被悄悄改坏。9.6 不要过早框架化很多初学者一上来就引入大型 Agent 框架结果被配置项淹没。更务实的学习路径是先用最小实现跑通一个 Skill理解目录结构、描述加载、脚本调用这三件事再引入框架的插件机制、并发控制和上下文管理最后再设计多 Agent 协作方案。10. 总结与后续学习方向Agent Skills 的流行本质上是 Agent 从 Demo 走向生产的必然结果。模型的思考能力再强如果没有稳定、可复用、可维护的执行能力Agent 就永远只是聊天机器人。Skill 化把“能力”从“决策”中剥离出来用一套统一的标准组织复杂任务这正是多 Agent 协作能够落地的前提。本文用一个最小可运行的代码审查示例走完了 Skill 从设计、编写、加载到多 Agent 复用的全过程。下一步你可以做三件事把code_review的规则扩展成自己业务里的检查项比如接口参数校验、SQL 注入风险扫描把role_decompose和role_coder替换成真实大模型调用感受模型决策与 Skill 执行分离的稳定性尝试拆分第二个 Skill然后观察多个 Skill 在同一个 Agent 流程里如何被调度。建议收藏这套目录结构和验证方法。后续无论切换到哪个框架、哪个模型这份“规则确定性 决策灵活性”的设计思路都不会过时。