这次我们来看一个最近热度非常高的方向Agent Skills。它并不是某个新模型而是一套让 Agent 能够“按标准方式调用外部能力”的工程规范。更直白地说如果大模型本身是大脑Agent Skills 就是给大脑配的一整套可插拔工具包数据处理、文档生成、批量执行、外部接口对接都可以封装成一个独立技能再交给 Agent 统一调度。这类能力最值得关注的点有三个第一是技能封装把重复性工作拆成可复用的模块第二是 Agent 调度让模型在多个技能之间自动或者显式地选择执行路径第三是项目落地不只是在演示环境跑通而是能接到真实项目和批量任务里。这套思路对自动化写作、数据分析、文档处理、代码生成、论文研究辅助等场景都很实用。本文会带读者完成一套完整的实操流程从环境准备开始搭建 Agent Skills 开发环境然后创建一个真实的技能讲解 SKILL.md 怎么写、脚本怎么组织、参数怎么定义接着做功能测试验证技能能否被正确识别和调用再演示 Agent 调度覆盖自动调度和显式调度两种方式最后给出接口 API 和批量任务的集成思路。适合正在学习 Agent 开发、想把自己的工具链标准化或者准备做多 Agent 项目的开发者阅读。1. 核心能力速览Agent Skills 本质上是一个开放、可扩展的工程模式下面把核心能力整理成速览表方便快速判断值不值得投入学习。能力项说明项目类型Agent 能力扩展与调度规范可配合 Claude Code、Anthropic Agent SDK 等环境使用主要功能技能封装、参数定义、依赖管理、自动/显式调度、批量任务、API 集成技能文件组成SKILL.md 元信息、脚本或程序、依赖声明、测试用例运行环境需要支持 Agent 的客户端或 SDK常见如 Claude Code、Anthropic SDK开发语言以 Python、JavaScript/TypeScript 为主其他语言按实际环境支持调度方式模型自动决策调度 用户/代码显式调度批量任务支持可以通过循环调用或任务队列实现API 能力依赖底层模型 API本身是工程层封装不限定具体接口适用场景文档生成、论文写作辅助、数据分析、代码生成、流程自动化、研究工作流从材料看这套模式的重点不在“模型能做什么”而在“怎么把能力标准化、可复用、可调度”。硬件门槛不是问题实话说它不要求本地显卡也不要求特殊服务器只要有能访问模型 API 的环境就可以开发。显存占用、GPU 推理这些概念在这里基本不涉及。实际开发中需要关注的反而是上下文长度、token 消耗和执行稳定性。如果读者之前接触过 ComfyUI 的工作流节点或者 LangChain 的 Tool 机制会发现 Agent Skills 的定位类似把一次性的提示词变成可复用、可测试、可组合的工程单元。但它更强调“模型可读的结构化描述 可执行的代码”所以落地性更强。2. 适用场景与使用边界Agent Skills 适合谁先给一个直接的结论适合需要把“大模型对话”升级为“大模型自动化流水线”的开发者。比如用模型批量生成产品文案每次都要重复给一堆背景材料用模型做数据分析每次都要重新描述数据格式和处理逻辑或者在做论文研究工作流时希望把文献检索、摘要提取、格式规范封装成固定步骤。这些都属于 Agent Skills 能解决的典型问题。一个比较典型的非编程场景是“Agent Skills 赋能人文社科混合研究方法论文写作”。这类任务通常包含多个环节研究问题拆解、文献综述、数据整理、混合方法分析、论文结构生成。如果把这些环节拆成多个独立技能再让 Agent 按顺序调度就能把一次性的论文协助过程变得可重复、可追踪。这也是为什么 Agent Skills 看起来偏工程但对非纯编程岗位也有实际价值。不过边界也要说清楚。Agent Skills 适合“规则相对明确、可拆解、可脚本化”的任务不适合需要长期记忆和复杂推理的开放式任务。例如让 Agent 做一篇完整论文的最终学术判断或者做需要人类价值观裁决的内容审核就不应该完全交给技能链。技能本身只是工具质量控制、合规审核和最终决策仍然由人来完成。另外涉及真实用户数据、版权材料、人脸声音素材时必须确认授权和隐私边界这点在后面的最佳实践里会展开。3. 环境准备与前置条件开发 Agent Skills 不需要重型硬件但需要准备好软件环境。下面给出一套通用检查清单具体版本以实际安装为准。首先操作系统建议使用 macOS 或 LinuxWindows 可以通过 WSL 运行但路径和虚拟环境管理会稍有差异。其次开发语言建议 Python 3.10 以上如果技能用 JavaScript 实现需要 Node.js 18 以上。依赖管理可以用 uv 或 pip强烈建议使用虚拟环境避免污染系统环境。然后是需要一个支持 Agent Skills 的运行时。以 Anthropic 生态为例可以安装 Claude Code或者使用 Agent SDK 进行编程式调用。不同工具对技能目录的识别方式不同但核心逻辑一致Agent 会在约定的目录中读取技能描述文件常见为 SKILL.md并根据描述决定何时调用。模型 API Key 是必要的开发测试阶段建议使用有额度限制的 Key避免意外消耗。安装基础工具的命令如下# 使用 uv 管理 Python 环境推荐 curl -LsSf https://astral.sh/uv/install.sh | sh # 安装 Claude Code以命令行工具为例 npm install -g anthropic-ai/claude-code # 创建项目目录 mkdir agent-skills-lab cd agent-skills-lab如果之前没有安装过 Node.js 或 Python先把这两个运行时装好。需要特别注意的是Agent Skills 不是独立运行的服务它必须搭配一个 Agent 环境。因此整个开发链路是编写技能文件 - 放入技能目录 - Agent 读取并调度。建议准备一个项目专用的技能目录例如.claude/skills/方便测试时快速定位问题。# 项目内技能目录结构 mkdir -p .claude/skills到这里环境准备就完成了。整个准备过程的关键就是三件事Python/Node 运行时、Agent 客户端/SDK、模型 API Key。不需要 GPU也不需要额外下载大模型权重文件。这一点对很多开发者来说反而比本地模型方案更轻量。4. 项目初始化与技能目录设计先启动一个最小可运行的项目。这里以agent-skills-lab作为演示目录实际项目中可以按自己的业务命名。# 初始化 Python 项目 uv init --python 3.11 uv add anthropic然后建立技能目录。Agent Skills 的目录结构可以按功能拆多个子目录每个技能一个目录内部包含元信息、脚本和测试。下面是一个通用结构agent-skills-lab/ ├── .claude/ │ └── skills/ │ ├── pdf-summary/ │ │ ├── SKILL.md │ │ ├── main.py │ │ └── requirements.txt │ └──>import argparse import json import re def build_summary(text: str, max_length: int 200) - dict: 简易文本摘要真实场景可替换为大模型接口调用。 text re.sub(r\s, , text).strip() sentences re.split(r[。], text) sentences [s.strip() for s in sentences if len(s.strip()) 5] selected sentences[:3] summary_text 。.join(selected) 。 if len(summary_text) max_length: summary_text summary_text[:max_length] …… return { summary: summary_text, sentence_count: len(sentences), source_length: len(text), } if __name__ __main__: parser argparse.ArgumentParser() parser.add_argument(--text, typestr, requiredTrue) parser.add_argument(--max-length, typeint, default200) args parser.parse_args() result build_summary(args.text, args.max_length) print(json.dumps(result, ensure_asciiFalse, indent2))第二步编写SKILL.md。这份文件是 Agent 理解技能的关键它需要包含技能名称、适用任务、输入格式、输出格式和使用示例。描述要直接、具体避免模糊用语。--- name: text-summary description: 为输入的长文本生成结构化摘要适合报告、论文段落、文章摘要等场景。 --- # Text Summary ## 功能说明 输入一段文本输出结构化摘要包含摘要正文、句子数量和原始长度。 ## 输入参数 - text: 需要摘要的文本内容 - max_length: 摘要最大长度默认 200 ## 输出格式 JSON 对象包含 summary、sentence_count、source_length 三个字段。 ## 使用示例 执行命令 bash python main.py --text 这里填写需要摘要的文本。 --max-length 150注意事项当输入文本很短时sentence_count 可能为 0。实际生产环境建议将文本摘要逻辑替换为模型接口调用以获得更好的语义理解。这里有一个容易被忽略的细节SKILL.md 中的括号、引号、反引号必须规范。如果描述格式错乱Agent 可能无法正确解析导致技能被跳过或者误调用。写完 SKILL.md 之后建议先用文本渲染工具检查一遍格式。 第三步添加依赖声明。脚本只用了 Python 标准库所以 requirements.txt 可以为空但如果真实技能依赖第三方库必须在该目录下单独声明。每个技能目录的依赖互相独立这样 Agent 调度时才不会出现版本冲突。 到这里一个最简单的技能封装就完成了。验证方法有两种一是手动运行脚本确认输出正确二是启动 Agent 环境看它是否能识别这个技能。下一节会给出更完整的验证流程。 ## 6. 功能测试与效果验证 技能封装完成后需要做一轮系统测试。这里建议按以下顺序执行。 ### 6.1 脚本层测试 先不经过 Agent直接运行脚本验证逻辑本身是否正确。 bash python .claude/skills/text-summary/main.py \ --text 这是一段测试文本。人工智能正在改变内容生产流程。Agent Skills 可以提升自动化程度。预期输出{ summary: 这是一段测试文本。人工智能正在改变内容生产流程。, sentence_count: 3, source_length: 42 }如果这一步能输出结构化 JSON说明脚本逻辑正常。接下来再看 Agent 能不能正确识别并调用。6.2 Agent 调度测试启动 Agent 环境并给出一段包含明确任务的自然语言指令请使用 text-summary 技能为下面的文本生成摘要 这里粘贴一段需要摘要的文章判断成功的标准有两条第一Agent 在回复中说明它使用了text-summary技能第二回复内容包含完整的 JSON 输出而不是一段“模拟摘要”。如果 Agent 没有调用技能而是直接凭模型知识给出摘要那就说明技能描述或者目录配置有问题。6.3 效果与稳定性观察测试阶段重点关注三个维度技能识别率连续测试 5 到 10 次观察 Agent 是否每次都选择了正确的技能。输出质量检查 JSON 结构是否稳定字段名是否始终一致。边界输入用空文本、超长文本、特殊字符分别测试确认脚本不会崩溃。从经验看大部分失败发生在“Agent 没有按预期调用技能”这一环。原因通常是SKILL.md描述含糊或者技能目录没有放在正确的路径下。排查时先确认目录再看描述格式最后看脚本本身是否有语法错误。7. Agent 调度显式调度与自动决策Agent 调度是 Agent Skills 从“单点工具”走向“工作流编排”的关键。这里介绍两种常见调度模式。7.1 显式调度显式调度适合流程固定的场景比如论文写作辅助中的“先检索后摘要再生成初稿”。在这种模式下开发者或用户在提示词中直接指定技能调用顺序。第一步使用 research-helper 技能整理研究问题 第二步使用 text-summary 技能对相关文献做摘要 第三步使用 essay-draft 技能生成论文初稿。显式调度的优点是可控性高缺点是需要人工指定步骤不适合大规模自动化运行。7.2 自动调度自动调度则依赖模型的工具调用能力。Agent 会在执行过程中阅读多个技能的SKILL.md然后根据当前任务自动选择调用哪个技能。例如用户只说“帮我写一份数据分析报告”Agent 可能自动调用数据读取、图表生成、报告排版三个技能。用户请求请根据这份销售数据生成一份分析报告。 Agent 可能执行 1. 调用>import asyncio from anthropic import Anthropic async def run_agent_task(prompt: str) - str: client Anthropic() # 实际参数以 SDK 文档为准 response client.messages.create( modelclaude-sonnet-4-5, max_tokens4096, tools[{type: skills, skills_dir: .claude/skills}], messages[{role: user, content: prompt}], ) return response.content[0].text if __name__ __main__: result asyncio.run(run_agent_task(请对以下文本生成摘要...)) print(result)这里不指定具体的模型版本和参数因为 SDK 更新较快实际开发时要查对应版本的文档。8.2 批量任务处理批量任务是 Agent Skills 最适合的生产场景之一。比如给一批论文段落生成摘要可以写一个遍历目录的脚本将任务逐个提交给 Agent并保存结果。批量处理时要注意增加失败重试和日志记录。import json import time import pathlib def batch_summary(input_dir: str, output_dir: str, retry: int 3) - None: input_path pathlib.Path(input_dir) output_path pathlib.Path(output_dir) output_path.mkdir(parentsTrue, exist_okTrue) for file in input_path.glob(*.txt): text file.read_text(encodingutf-8) for attempt in range(retry): try: # 原位置替换为真实 Agent 调用函数 result run_agent_task(f请对以下文本生成摘要\n{text}) output_file output_path / f{file.stem}.json output_file.write_text( json.dumps({source: file.name, result: result}, ensure_asciiFalse), encodingutf-8, ) break except Exception as e: print(f[{file.name}] 第 {attempt 1} 次失败: {e}) time.sleep(2 ** attempt)批量任务的关键不是并发拉满而是稳定。建议第一批先跑 5 到 10 条数据确认输出格式没问题再扩展到全量。中间任何一条任务失败都应该有日志记录方便事后重跑。8.3 接口访问边界当技能服务通过 API 对外提供时要限制访问范围。建议不直接把 Agent 客户端暴露到公网而是包一层自己的后端服务只开放必要的业务接口并增加鉴权、限流和请求日志。涉及内部数据或用户数据时还需要按数据合规要求做脱敏和访问控制。9. 资源占用与性能观察虽然 Agent Skills 对 GPU 没有要求但资源占用依然存在主要体现在三个方面token 消耗、API 延迟、磁盘与依赖体积。Token 消耗是最容易忽视的成本。每次技能调用都会消耗输入 token 和输出 token而技能描述本身也会占用一部分上下文。观察方法很简单在 Agent 日志里查看每次请求的 usage 字段记录输入 token 数和输出 token 数按模型单价折算成本。测试阶段建议设置单次任务预算上限防止异常循环导致费用飙升。API 延迟受模型响应速度和技能脚本执行时间共同影响。如果技能脚本处理很重比如大 PDF 解析、复杂数据分析建议先把结果缓存起来避免 Agent 重复执行同样计算。更极端的做法是把技能拆成同步和异步两部分同步接口快速返回“任务已接收”异步任务结束后再回调通知。磁盘和依赖方面每个技能目录的依赖独立体积会随数量增加。建议定期清理不再使用的技能目录并在项目 README 中记录每个技能的用途和依赖情况。虽然这不是硬性资源问题但多人协作时能省很多排查时间。10. 常见问题与排查方法下面是实际开发中比较高发的几个问题按现象、可能原因、排查方式和解决方案整理成表格。问题现象可能原因排查方式解决方案Agent 始终不调用技能SKILL.md 描述不清晰或技能目录路径错误确认技能目录是否在.claude/skills下检查描述是否包含明确的适用场景重写描述明确输入参数和输出格式把技能放到项目目录再测试技能被调用但脚本报错Python 依赖缺失或参数名不匹配手动运行脚本查看报错信息检查调用参数是否与 argparse 定义一致在技能目录内安装依赖统一参数命名API Key 未生效环境变量没有正确配置执行 envgrep ANTHROPIC 检查变量多个技能被误选技能描述过于接近检查各技能描述看是否存在语义重叠在描述中补充“什么时候不要使用本技能”批量任务卡住没有设置超时和重试机制查看日志中最后一条成功记录增加超时参数、失败重试和任务队列输出 JSON 结构不稳定模型直接生成输出而非调用技能查看 Agent 回复是否包含 JSON 代码块要求技能脚本负责输出 JSON减少模型自由生成增加输出校验逻辑上下文长度超限单次任务输入过多技能输出过大查看日志中的 token 数分块处理输入让技能输出精简结果这个表格不能覆盖所有问题但提供了排查思路。最重要的是先确认“卡在哪一层”是技能没被识别还是脚本执行失败还是模型输出格式不对。逐层排除通常很快就能定位。11. 最佳实践与使用建议经过前面的开发流程最后梳理几条对项目落地最有效的建议。第一第一次做技能时先跑最小可用版本。不需要一开始就设计复杂的参数体系一个技能目录、一个SKILL.md、一个脚本就够了。先验证 Agent 能识别和调用再逐步增加参数和功能。第二每个技能目录保持独立依赖显式声明。不要图省事把所有脚本堆在一个目录里否则后续调度会越来越难维护。第三给技能写清晰的使用边界。在SKILL.md里同时写清楚“适合做什么”和“不适合做什么”这能显著降低自动调度时的误选率。第四批量任务必须先小规模验证再全量运行。同时做好日志、超时、重试机制保证异常任务能恢复。第五涉及真实数据和人脸、声音、版权素材时必须确认授权。Agent Skills 本身是自动化工具但使用边界仍然由开发者控制不能因为“只是调用 API”就忽略合规问题。第六接口服务要限制访问范围。如果技能能力通过 API 对外开放建议放在后端服务之后增加鉴权、限流、日志避免直接暴露模型调用入口。12. 总结Agent Skills 最值得尝试的点是把“提示词技巧”升级为“工程化技能包”让模型能力可以被复用、测试和调度。整套开发流程并不复杂写一个技能脚本配一份 SKILL.md放进技能目录Agent 就能在需要的时候调用它。相比反复写长提示词这种方式的稳定性和可维护性都有明显提升。建议最先验证的是最基础的技能识别链路也就是创建技能后用一条自然语言指令测试 Agent 是否能正确调用。最容易踩的坑是技能描述不清和目录路径错误这两点占掉了大部分调试时间。后续可以继续扩展的方向包括把多个技能组合成复杂工作流、通过 API 接入现有系统、加入任务队列做大规模批量处理。先把第一个技能跑通再往深处扩展。 
长河君 · 2026/9/3 19:17:50 · 阅读 1.2k Agent Skills 实战：从技能封装到调度与批量任务集成
这次我们来看一个最近热度非常高的方向Agent Skills。它并不是某个新模型而是一套让 Agent 能够“按标准方式调用外部能力”的工程规范。更直白地说如果大模型本身是大脑Agent Skills 就是给大脑配的一整套可插拔工具包数据处理、文档生成、批量执行、外部接口对接都可以封装成一个独立技能再交给 Agent 统一调度。这类能力最值得关注的点有三个第一是技能封装把重复性工作拆成可复用的模块第二是 Agent 调度让模型在多个技能之间自动或者显式地选择执行路径第三是项目落地不只是在演示环境跑通而是能接到真实项目和批量任务里。这套思路对自动化写作、数据分析、文档处理、代码生成、论文研究辅助等场景都很实用。本文会带读者完成一套完整的实操流程从环境准备开始搭建 Agent Skills 开发环境然后创建一个真实的技能讲解 SKILL.md 怎么写、脚本怎么组织、参数怎么定义接着做功能测试验证技能能否被正确识别和调用再演示 Agent 调度覆盖自动调度和显式调度两种方式最后给出接口 API 和批量任务的集成思路。适合正在学习 Agent 开发、想把自己的工具链标准化或者准备做多 Agent 项目的开发者阅读。1. 核心能力速览Agent Skills 本质上是一个开放、可扩展的工程模式下面把核心能力整理成速览表方便快速判断值不值得投入学习。能力项说明项目类型Agent 能力扩展与调度规范可配合 Claude Code、Anthropic Agent SDK 等环境使用主要功能技能封装、参数定义、依赖管理、自动/显式调度、批量任务、API 集成技能文件组成SKILL.md 元信息、脚本或程序、依赖声明、测试用例运行环境需要支持 Agent 的客户端或 SDK常见如 Claude Code、Anthropic SDK开发语言以 Python、JavaScript/TypeScript 为主其他语言按实际环境支持调度方式模型自动决策调度 用户/代码显式调度批量任务支持可以通过循环调用或任务队列实现API 能力依赖底层模型 API本身是工程层封装不限定具体接口适用场景文档生成、论文写作辅助、数据分析、代码生成、流程自动化、研究工作流从材料看这套模式的重点不在“模型能做什么”而在“怎么把能力标准化、可复用、可调度”。硬件门槛不是问题实话说它不要求本地显卡也不要求特殊服务器只要有能访问模型 API 的环境就可以开发。显存占用、GPU 推理这些概念在这里基本不涉及。实际开发中需要关注的反而是上下文长度、token 消耗和执行稳定性。如果读者之前接触过 ComfyUI 的工作流节点或者 LangChain 的 Tool 机制会发现 Agent Skills 的定位类似把一次性的提示词变成可复用、可测试、可组合的工程单元。但它更强调“模型可读的结构化描述 可执行的代码”所以落地性更强。2. 适用场景与使用边界Agent Skills 适合谁先给一个直接的结论适合需要把“大模型对话”升级为“大模型自动化流水线”的开发者。比如用模型批量生成产品文案每次都要重复给一堆背景材料用模型做数据分析每次都要重新描述数据格式和处理逻辑或者在做论文研究工作流时希望把文献检索、摘要提取、格式规范封装成固定步骤。这些都属于 Agent Skills 能解决的典型问题。一个比较典型的非编程场景是“Agent Skills 赋能人文社科混合研究方法论文写作”。这类任务通常包含多个环节研究问题拆解、文献综述、数据整理、混合方法分析、论文结构生成。如果把这些环节拆成多个独立技能再让 Agent 按顺序调度就能把一次性的论文协助过程变得可重复、可追踪。这也是为什么 Agent Skills 看起来偏工程但对非纯编程岗位也有实际价值。不过边界也要说清楚。Agent Skills 适合“规则相对明确、可拆解、可脚本化”的任务不适合需要长期记忆和复杂推理的开放式任务。例如让 Agent 做一篇完整论文的最终学术判断或者做需要人类价值观裁决的内容审核就不应该完全交给技能链。技能本身只是工具质量控制、合规审核和最终决策仍然由人来完成。另外涉及真实用户数据、版权材料、人脸声音素材时必须确认授权和隐私边界这点在后面的最佳实践里会展开。3. 环境准备与前置条件开发 Agent Skills 不需要重型硬件但需要准备好软件环境。下面给出一套通用检查清单具体版本以实际安装为准。首先操作系统建议使用 macOS 或 LinuxWindows 可以通过 WSL 运行但路径和虚拟环境管理会稍有差异。其次开发语言建议 Python 3.10 以上如果技能用 JavaScript 实现需要 Node.js 18 以上。依赖管理可以用 uv 或 pip强烈建议使用虚拟环境避免污染系统环境。然后是需要一个支持 Agent Skills 的运行时。以 Anthropic 生态为例可以安装 Claude Code或者使用 Agent SDK 进行编程式调用。不同工具对技能目录的识别方式不同但核心逻辑一致Agent 会在约定的目录中读取技能描述文件常见为 SKILL.md并根据描述决定何时调用。模型 API Key 是必要的开发测试阶段建议使用有额度限制的 Key避免意外消耗。安装基础工具的命令如下# 使用 uv 管理 Python 环境推荐 curl -LsSf https://astral.sh/uv/install.sh | sh # 安装 Claude Code以命令行工具为例 npm install -g anthropic-ai/claude-code # 创建项目目录 mkdir agent-skills-lab cd agent-skills-lab如果之前没有安装过 Node.js 或 Python先把这两个运行时装好。需要特别注意的是Agent Skills 不是独立运行的服务它必须搭配一个 Agent 环境。因此整个开发链路是编写技能文件 - 放入技能目录 - Agent 读取并调度。建议准备一个项目专用的技能目录例如.claude/skills/方便测试时快速定位问题。# 项目内技能目录结构 mkdir -p .claude/skills到这里环境准备就完成了。整个准备过程的关键就是三件事Python/Node 运行时、Agent 客户端/SDK、模型 API Key。不需要 GPU也不需要额外下载大模型权重文件。这一点对很多开发者来说反而比本地模型方案更轻量。4. 项目初始化与技能目录设计先启动一个最小可运行的项目。这里以agent-skills-lab作为演示目录实际项目中可以按自己的业务命名。# 初始化 Python 项目 uv init --python 3.11 uv add anthropic然后建立技能目录。Agent Skills 的目录结构可以按功能拆多个子目录每个技能一个目录内部包含元信息、脚本和测试。下面是一个通用结构agent-skills-lab/ ├── .claude/ │ └── skills/ │ ├── pdf-summary/ │ │ ├── SKILL.md │ │ ├── main.py │ │ └── requirements.txt │ └──>import argparse import json import re def build_summary(text: str, max_length: int 200) - dict: 简易文本摘要真实场景可替换为大模型接口调用。 text re.sub(r\s, , text).strip() sentences re.split(r[。], text) sentences [s.strip() for s in sentences if len(s.strip()) 5] selected sentences[:3] summary_text 。.join(selected) 。 if len(summary_text) max_length: summary_text summary_text[:max_length] …… return { summary: summary_text, sentence_count: len(sentences), source_length: len(text), } if __name__ __main__: parser argparse.ArgumentParser() parser.add_argument(--text, typestr, requiredTrue) parser.add_argument(--max-length, typeint, default200) args parser.parse_args() result build_summary(args.text, args.max_length) print(json.dumps(result, ensure_asciiFalse, indent2))第二步编写SKILL.md。这份文件是 Agent 理解技能的关键它需要包含技能名称、适用任务、输入格式、输出格式和使用示例。描述要直接、具体避免模糊用语。--- name: text-summary description: 为输入的长文本生成结构化摘要适合报告、论文段落、文章摘要等场景。 --- # Text Summary ## 功能说明 输入一段文本输出结构化摘要包含摘要正文、句子数量和原始长度。 ## 输入参数 - text: 需要摘要的文本内容 - max_length: 摘要最大长度默认 200 ## 输出格式 JSON 对象包含 summary、sentence_count、source_length 三个字段。 ## 使用示例 执行命令 bash python main.py --text 这里填写需要摘要的文本。 --max-length 150注意事项当输入文本很短时sentence_count 可能为 0。实际生产环境建议将文本摘要逻辑替换为模型接口调用以获得更好的语义理解。这里有一个容易被忽略的细节SKILL.md 中的括号、引号、反引号必须规范。如果描述格式错乱Agent 可能无法正确解析导致技能被跳过或者误调用。写完 SKILL.md 之后建议先用文本渲染工具检查一遍格式。 第三步添加依赖声明。脚本只用了 Python 标准库所以 requirements.txt 可以为空但如果真实技能依赖第三方库必须在该目录下单独声明。每个技能目录的依赖互相独立这样 Agent 调度时才不会出现版本冲突。 到这里一个最简单的技能封装就完成了。验证方法有两种一是手动运行脚本确认输出正确二是启动 Agent 环境看它是否能识别这个技能。下一节会给出更完整的验证流程。 ## 6. 功能测试与效果验证 技能封装完成后需要做一轮系统测试。这里建议按以下顺序执行。 ### 6.1 脚本层测试 先不经过 Agent直接运行脚本验证逻辑本身是否正确。 bash python .claude/skills/text-summary/main.py \ --text 这是一段测试文本。人工智能正在改变内容生产流程。Agent Skills 可以提升自动化程度。预期输出{ summary: 这是一段测试文本。人工智能正在改变内容生产流程。, sentence_count: 3, source_length: 42 }如果这一步能输出结构化 JSON说明脚本逻辑正常。接下来再看 Agent 能不能正确识别并调用。6.2 Agent 调度测试启动 Agent 环境并给出一段包含明确任务的自然语言指令请使用 text-summary 技能为下面的文本生成摘要 这里粘贴一段需要摘要的文章判断成功的标准有两条第一Agent 在回复中说明它使用了text-summary技能第二回复内容包含完整的 JSON 输出而不是一段“模拟摘要”。如果 Agent 没有调用技能而是直接凭模型知识给出摘要那就说明技能描述或者目录配置有问题。6.3 效果与稳定性观察测试阶段重点关注三个维度技能识别率连续测试 5 到 10 次观察 Agent 是否每次都选择了正确的技能。输出质量检查 JSON 结构是否稳定字段名是否始终一致。边界输入用空文本、超长文本、特殊字符分别测试确认脚本不会崩溃。从经验看大部分失败发生在“Agent 没有按预期调用技能”这一环。原因通常是SKILL.md描述含糊或者技能目录没有放在正确的路径下。排查时先确认目录再看描述格式最后看脚本本身是否有语法错误。7. Agent 调度显式调度与自动决策Agent 调度是 Agent Skills 从“单点工具”走向“工作流编排”的关键。这里介绍两种常见调度模式。7.1 显式调度显式调度适合流程固定的场景比如论文写作辅助中的“先检索后摘要再生成初稿”。在这种模式下开发者或用户在提示词中直接指定技能调用顺序。第一步使用 research-helper 技能整理研究问题 第二步使用 text-summary 技能对相关文献做摘要 第三步使用 essay-draft 技能生成论文初稿。显式调度的优点是可控性高缺点是需要人工指定步骤不适合大规模自动化运行。7.2 自动调度自动调度则依赖模型的工具调用能力。Agent 会在执行过程中阅读多个技能的SKILL.md然后根据当前任务自动选择调用哪个技能。例如用户只说“帮我写一份数据分析报告”Agent 可能自动调用数据读取、图表生成、报告排版三个技能。用户请求请根据这份销售数据生成一份分析报告。 Agent 可能执行 1. 调用>import asyncio from anthropic import Anthropic async def run_agent_task(prompt: str) - str: client Anthropic() # 实际参数以 SDK 文档为准 response client.messages.create( modelclaude-sonnet-4-5, max_tokens4096, tools[{type: skills, skills_dir: .claude/skills}], messages[{role: user, content: prompt}], ) return response.content[0].text if __name__ __main__: result asyncio.run(run_agent_task(请对以下文本生成摘要...)) print(result)这里不指定具体的模型版本和参数因为 SDK 更新较快实际开发时要查对应版本的文档。8.2 批量任务处理批量任务是 Agent Skills 最适合的生产场景之一。比如给一批论文段落生成摘要可以写一个遍历目录的脚本将任务逐个提交给 Agent并保存结果。批量处理时要注意增加失败重试和日志记录。import json import time import pathlib def batch_summary(input_dir: str, output_dir: str, retry: int 3) - None: input_path pathlib.Path(input_dir) output_path pathlib.Path(output_dir) output_path.mkdir(parentsTrue, exist_okTrue) for file in input_path.glob(*.txt): text file.read_text(encodingutf-8) for attempt in range(retry): try: # 原位置替换为真实 Agent 调用函数 result run_agent_task(f请对以下文本生成摘要\n{text}) output_file output_path / f{file.stem}.json output_file.write_text( json.dumps({source: file.name, result: result}, ensure_asciiFalse), encodingutf-8, ) break except Exception as e: print(f[{file.name}] 第 {attempt 1} 次失败: {e}) time.sleep(2 ** attempt)批量任务的关键不是并发拉满而是稳定。建议第一批先跑 5 到 10 条数据确认输出格式没问题再扩展到全量。中间任何一条任务失败都应该有日志记录方便事后重跑。8.3 接口访问边界当技能服务通过 API 对外提供时要限制访问范围。建议不直接把 Agent 客户端暴露到公网而是包一层自己的后端服务只开放必要的业务接口并增加鉴权、限流和请求日志。涉及内部数据或用户数据时还需要按数据合规要求做脱敏和访问控制。9. 资源占用与性能观察虽然 Agent Skills 对 GPU 没有要求但资源占用依然存在主要体现在三个方面token 消耗、API 延迟、磁盘与依赖体积。Token 消耗是最容易忽视的成本。每次技能调用都会消耗输入 token 和输出 token而技能描述本身也会占用一部分上下文。观察方法很简单在 Agent 日志里查看每次请求的 usage 字段记录输入 token 数和输出 token 数按模型单价折算成本。测试阶段建议设置单次任务预算上限防止异常循环导致费用飙升。API 延迟受模型响应速度和技能脚本执行时间共同影响。如果技能脚本处理很重比如大 PDF 解析、复杂数据分析建议先把结果缓存起来避免 Agent 重复执行同样计算。更极端的做法是把技能拆成同步和异步两部分同步接口快速返回“任务已接收”异步任务结束后再回调通知。磁盘和依赖方面每个技能目录的依赖独立体积会随数量增加。建议定期清理不再使用的技能目录并在项目 README 中记录每个技能的用途和依赖情况。虽然这不是硬性资源问题但多人协作时能省很多排查时间。10. 常见问题与排查方法下面是实际开发中比较高发的几个问题按现象、可能原因、排查方式和解决方案整理成表格。问题现象可能原因排查方式解决方案Agent 始终不调用技能SKILL.md 描述不清晰或技能目录路径错误确认技能目录是否在.claude/skills下检查描述是否包含明确的适用场景重写描述明确输入参数和输出格式把技能放到项目目录再测试技能被调用但脚本报错Python 依赖缺失或参数名不匹配手动运行脚本查看报错信息检查调用参数是否与 argparse 定义一致在技能目录内安装依赖统一参数命名API Key 未生效环境变量没有正确配置执行 envgrep ANTHROPIC 检查变量多个技能被误选技能描述过于接近检查各技能描述看是否存在语义重叠在描述中补充“什么时候不要使用本技能”批量任务卡住没有设置超时和重试机制查看日志中最后一条成功记录增加超时参数、失败重试和任务队列输出 JSON 结构不稳定模型直接生成输出而非调用技能查看 Agent 回复是否包含 JSON 代码块要求技能脚本负责输出 JSON减少模型自由生成增加输出校验逻辑上下文长度超限单次任务输入过多技能输出过大查看日志中的 token 数分块处理输入让技能输出精简结果这个表格不能覆盖所有问题但提供了排查思路。最重要的是先确认“卡在哪一层”是技能没被识别还是脚本执行失败还是模型输出格式不对。逐层排除通常很快就能定位。11. 最佳实践与使用建议经过前面的开发流程最后梳理几条对项目落地最有效的建议。第一第一次做技能时先跑最小可用版本。不需要一开始就设计复杂的参数体系一个技能目录、一个SKILL.md、一个脚本就够了。先验证 Agent 能识别和调用再逐步增加参数和功能。第二每个技能目录保持独立依赖显式声明。不要图省事把所有脚本堆在一个目录里否则后续调度会越来越难维护。第三给技能写清晰的使用边界。在SKILL.md里同时写清楚“适合做什么”和“不适合做什么”这能显著降低自动调度时的误选率。第四批量任务必须先小规模验证再全量运行。同时做好日志、超时、重试机制保证异常任务能恢复。第五涉及真实数据和人脸、声音、版权素材时必须确认授权。Agent Skills 本身是自动化工具但使用边界仍然由开发者控制不能因为“只是调用 API”就忽略合规问题。第六接口服务要限制访问范围。如果技能能力通过 API 对外开放建议放在后端服务之后增加鉴权、限流、日志避免直接暴露模型调用入口。12. 总结Agent Skills 最值得尝试的点是把“提示词技巧”升级为“工程化技能包”让模型能力可以被复用、测试和调度。整套开发流程并不复杂写一个技能脚本配一份 SKILL.md放进技能目录Agent 就能在需要的时候调用它。相比反复写长提示词这种方式的稳定性和可维护性都有明显提升。建议最先验证的是最基础的技能识别链路也就是创建技能后用一条自然语言指令测试 Agent 是否能正确调用。最容易踩的坑是技能描述不清和目录路径错误这两点占掉了大部分调试时间。后续可以继续扩展的方向包括把多个技能组合成复杂工作流、通过 API 接入现有系统、加入任务队列做大规模批量处理。先把第一个技能跑通再往深处扩展。