Agent Skills 最近讨论度很高但很多人可能还是一知半解它和 Function Calling 有什么区别一个 Skill 到底长什么样代码怎么写这期内容直接按“是什么 - 怎么跑 - 怎么自己写 - 怎么集成”的顺序来把 Agent Skills 从入门到实战完整拆一遍。这篇文章不是讲概念就完事的那种会直接写一个可运行的最小 Skill再带大家把它升级成带批量处理和 API 接口的工程化模块。看完之后你就可以照着代码自己改一个符合业务需求的 Agent Skills 出来。1. Agent Skills 核心能力速览开头先给结论。无论你是刚接触 Agent 开发还是已经在做 Agent 工具链Agent Skills 这个东西最核心的价值就是把“给模型灌提示词和工具”这件事标准化、文件化、可复用。能力项说明技术定义一种以“技能包”形式封装提示词、脚本、示例和元数据的 Agent 扩展机制核心理念将 Agent 的专项能力模块化用文件目录和描述文件让模型自动理解并调用核心组成SKILL.md 描述文件、可执行脚本、示例输入输出、可选的依赖清单开发语言以 Python 为主也支持 Shell、Node.js 等任何可被调用的脚本显卡要求无需本地 GPUSkill 运行在模型 API 之上纯本地小模型也可以配合跑平台适配支持 Anthropic Claude 官方工作流也适配 LangChain / Semantic Kernel 等 Agent 框架启动方式非独立服务通常随 Agent 主程序加载也可编译为 API 子服务是否支持 API支持Skill 可以包装成 REST API供其他系统调用是否支持批量任务支持通过脚本循环或任务队列实现适合人群Agent 应用开发者、Prompt Engineer、RAG 应用开发者、AI 工具产品经理从这张表能看出Agent Skills 不是一个需要“部署”的大模型服务它更像是一个“代码资产 提示词资产”的标准打包方式。理解了这一点后续的开发思路就顺了。2. 适用场景与使用边界2.1 什么场景适合用 Agent SkillsAgent Skills 最适合解决的是“模型能力够但稳定性和复用性不够”的问题。举个例子你的 Agent 需要经常解析用户上传的报表并生成摘要如果每次都在主提示词里写“请分析报表并提取关键数据”结果很容易飘。把这件事固化为一个“报表分析 Skill”模型就知道先做什么、后做什么、输出什么格式。典型适用场景包括企业文档处理合同审核、财报抽取、简历筛选。数据分析助手让 Agent 调用 Pandas 脚本做数据处理而不是让模型自己“想象”数据。内容生产工具统一的文章结构、风格调整、SEO 关键词提取。个人知识库助手把 RAG 检索和总结流程标准化。多工具协同把搜索、计算、代码执行封装成不同 Skill按需组合。这类场景的共同点是流程固定、输出格式要求高、会被反复调用。这正是 Skill 比普通提示词更合适的地方。2.2 使用边界与合规提醒Agent Skills 不是万能的。纯开放域聊天、需要模型自由发挥创意、需要低延迟实时响应的场景不建议过度封装 Skill——封装之后反而限制模型的灵活度。另外要特别提醒如果 Skill 涉及读取用户私有数据、人脸图片、语音录音或版权文本使用前必须确认授权链完整。批量处理数据时如果包含个人信息需要做脱敏处理并在项目文档中写清数据保留策略。涉及商用项目还要确认模型服务商的使用条款和输出内容可商用范围。3. 环境准备与前置条件开发 Agent Skills 不需要 GPU也不需要昂贵的本地推理环境但需要准备好一套 Python 开发环境和可用的模型 API 访问权限。3.1 环境清单依赖项说明操作系统Windows / macOS / Linux 均可不影响 Skill 结构Python 版本建议 3.10 或以上方便使用新版类型注解和异常处理模型 API需要可用的 Anthropic API Key或兼容 OpenAI 格式的模型服务Agent 框架可选初期可以不用框架直接测试 Skill 的提示词和脚本代码编辑器推荐 VS Code 或 Cursor方便查看目录结构和调试脚本版本管理GitSkill 文件本质上是代码资产应该纳入版本管理3.2 确认模型 API 是否可用在开始写 Skill 之前先确认模型 API 可以正常调用避免后面把问题混在一起排查。# test_api.py import os from anthropic import Anthropic client Anthropic(api_keyos.environ.get(ANTHROPIC_API_KEY)) response client.messages.create( modelclaude-sonnet-4-5, max_tokens100, messages[{role: user, content: 说一句Agent Skills 环境正常}] ) print(response.content[0].text)这里用到的模型名称claude-sonnet-4-5只是示例具体模型名以你账户可用的模型列表为准。API Key 不建议硬编码在代码里建议通过环境变量或.env文件管理。export ANTHROPIC_API_KEY你的API Key确认能返回文本后再继续下一步。这个前置检测能省掉很多后面排查的时间。4. 手把手实战一个最小可运行的 Agent Skill这一节直接写一个能运行的 Skill。以“商品评论情感分析”为例——假设你是一个电商运营经常需要把一组商品评论批量分类为“正面 / 负面 / 中性”并且提取高频问题关键词。这个场景非常适合做成 Skill。4.1 定义 Skill 目录结构一个标准的 Skill 建议这样组织sentiment_analysis_skill/ ├── SKILL.md ├── scripts/ │ ├── analyze.py │ └── requirements.txt ├── examples/ │ ├── input_example.txt │ └── output_example.json └── assets/ └── 说明文档或参考图片目录里最重要的是SKILL.md和scripts/analyze.py。4.2 编写 SKILL.md 描述文件SKILL.md是让模型“知道有这个技能、什么时候用、怎么用”的关键文件。它应该包含技能名称、触发条件、详细流程、注意事项和示例。--- name: sentiment_analysis description: 对电商商品评论进行情感分类并提取高频问题关键词。 when_to_use: 当用户提供多条评论文本并要求分析情感或总结问题类型时。 --- # 商品评论情感分析 ## 功能说明 本技能将用户提供的评论批量标记为 - POSITIVE正面评价包含满意、推荐、质量好等表达 - NEGATIVE负面评价包含质量差、退货、失望等表达 - NEUTRAL中性评价或无法判断 输出格式为 JSON 数组按评论原始顺序排列。 ## 执行步骤 1. 检查用户评论数量如果超过 50 条提醒用户分批。 2. 对每条评论调用 scripts/analyze.py 进行文本分类。 3. 汇总 JSON 结果并返回。 ## 边界与注意 - 只处理文本评论不处理图片或音频。 - 不修改原始评论内容。 - 如果评论语言不是中文先翻译为中文再分析或直接按“正面/负面/中性”标签体系输出英文结果。SKILL.md写得越清晰模型调用 Skill 的成功率越高。尤其是when_to_use字段能直接减少误触发。4.3 编写执行脚本analyze.py的作用是实际完成分类。这里提供一个不依赖大模型的轻量规则脚本方便本地直接跑通。如果需要更高精度可以把脚本里的规则判断替换为调用模型的分类逻辑。# scripts/analyze.py import json import re import sys POSITIVE_WORDS [好, 推荐, 满意, 不错, 超值, 喜欢, 好评, 性价比高] NEGATIVE_WORDS [差, 退货, 失望, 垃圾, 慢, 坏, 差评, 不值, 客服不理] NEUTRAL_WORDS [一般, 还行, 普通, 不知道, 不评价] def classify_one(comment: str) - str: pos_score sum(1 for w in POSITIVE_WORDS if w in comment) neg_score sum(1 for w in NEGATIVE_WORDS if w in comment) neu_score sum(1 for w in NEUTRAL_WORDS if w in comment) if pos_score neg_score and pos_score neu_score: return POSITIVE if neg_score pos_score and neg_score neu_score: return NEGATIVE return NEUTRAL def main(): # 支持从 stdin 读取 JSON 数组例如[评论1,评论2] raw sys.stdin.read().strip() if not raw: print(json.dumps([])) return comments json.loads(raw) results [{comment: c, label: classify_one(c)} for c in comments] print(json.dumps(results, ensure_asciiFalse, indent2)) if __name__ __main__: main()echo [这手机拍照效果很好推荐购买, 发货太慢了客服也不理我, 一般般吧] | python scripts/analyze.py这个脚本演示的是“Skill 脚本如何被调用”。在实际的 Agent 工作流中模型会读取 SKILL.md然后把用户评论整理成 JSON调用脚本得到分类结果最后把 JSON 改写成更容易阅读的回复。这种“模型负责理解 脚本负责执行”的组合就是 Agent Skills 的基本运行模式。4.4 让 Skill 真正被模型使用如果是在 Anthropic 的 Agent 工作流中通常在 Agent 主程序里把 Skill 目录挂载为可访问的工具。不同框架的挂载方式不一样但思路一致将SKILL.md作为系统提示的一部分将scripts/analyze.py作为可执行命令暴露给 Agent。# agent_with_skill.py import subprocess import json import os from anthropic import Anthropic client Anthropic(api_keyos.environ.get(ANTHROPIC_API_KEY)) # 读取 SKILL.md拼入系统提示 skill_md open(sentiment_analysis_skill/SKILL.md, encodingutf-8).read() user_comments [ 这个包质量很好颜色也正满意, 物流太慢了等了一周差评, 性价比一般没什么特别的感觉 ] # 调用模型让它决定是否调用分析脚本 resp client.messages.create( modelclaude-sonnet-4-5, max_tokens1024, systemf这是一个支持商品评论分析技能的 Agent。技能说明\n{skill_md}, messages[{role: user, content: f请分析这些评论{json.dumps(user_comments, ensure_asciiFalse)}}] ) print(resp.content[0].text)注意实际项目中Agent 的“工具调用”通常需要配合模型服务商提供的 function calling 或 tool use 机制不是简单把脚本路径写进系统提示就能自动执行。上面代码演示的是“把 Skill 描述塞给模型”的基本思路更严谨的版本应该使用官方的 tool use 格式。具体格式以你使用的模型平台文档为准。5. 从“能跑”到“好用”批量任务与中断恢复实际工作中评论分析往往不是几条而是几百上千条。这时候有两个问题要解决一是批量处理的速度和稳定性二是中途失败时能否断点续跑。5.1 批量任务设计把上一次的“单次调用”改成“批量队列模式”。# batch_analyze.py import json import subprocess import time from pathlib import Path INPUT_FILE reviews.jsonl OUTPUT_FILE output_labels.jsonl BATCH_SIZE 20 def load_reviews(path): reviews [] with open(path, encodingutf-8) as f: for line in f: line line.strip() if line: reviews.append(json.loads(line)) return reviews def run_skill_batch(batch): payload json.dumps([r[text] for r in batch], ensure_asciiFalse) # 这里复用 analyze.py而不是重新调用模型 proc subprocess.run( [python, sentiment_analysis_skill/scripts/analyze.py], inputpayload, capture_outputTrue, textTrue, encodingutf-8 ) if proc.returncode ! 0: raise RuntimeError(fSkill 脚本执行失败{proc.stderr}) return json.loads(proc.stdout) def main(): reviews load_reviews(INPUT_FILE) print(f共 {len(reviews)} 条评论批量大小 {BATCH_SIZE}) results [] for i in range(0, len(reviews), BATCH_SIZE): batch reviews[i:i BATCH_SIZE] try: batch_results run_skill_batch(batch) results.extend(batch_results) print(f已处理第 {i 1} 到 {i len(batch)} 条) except Exception as e: print(f批次 {i // BATCH_SIZE} 处理失败{e}) # 保留断点允许后续重跑 break # 写入结果 with open(OUTPUT_FILE, w, encodingutf-8) as f: for item in results: f.write(json.dumps(item, ensure_asciiFalse) \n) print(f完成输出文件{OUTPUT_FILE}) if __name__ __main__: main()这个批量脚本的思路是把数据拆成小批次每个批次调用一次 Skill 脚本失败了就停下来保留已处理结果。严谨的工程版本还应该加入“已处理行数记录”实现真正的断点续跑。5.2 任务队列化当批量任务变大比如上万条评论直接 for 循环可能不够用。生产环境建议用 Redis RQ 或 Celery 做任务队列每个任务处理 50 到 100 条评论任务执行完成后把结果写回数据库并标记状态。任务队列的伪代码如下# tasks.py假想的项目结构 from redis import Redis from rq import Queue q Queue(connectionRedis.from_url(redis://localhost:6379)) def process_review_batch(batch_id, review_ids): # 从数据库读取该批次评论 # 调用 Skill 脚本 # 写回结果 return {batch_id: batch_id, status: done} # 入队 for batch_id in range(0, 40): q.enqueue(process_review_batch, batch_id, [101, 102, 103])使用队列的好处是单条任务失败不会影响整批可以单独重试也方便做并发限制避免把 API 配额打爆。6. 接口 API 调用示例把 Skill 包装成服务如果 Skill 要提供给前端、Excel 插件或第三方工具调用直接跑脚本就不够方便了。更通用的方式是把 Skill 包装成 HTTP API。6.1 用 FastAPI 包装 Skill# api.py import json import subprocess from fastapi import FastAPI from pydantic import BaseModel app FastAPI(titleAgent Skill API, version0.1.0) class AnalyzeRequest(BaseModel): comments: list[str] class AnalyzeResponse(BaseModel): results: list[dict] app.post(/api/sentiment, response_modelAnalyzeResponse) async def analyze_comments(req: AnalyzeRequest): payload json.dumps(req.comments, ensure_asciiFalse) proc subprocess.run( [python, sentiment_analysis_skill/scripts/analyze.py], inputpayload, capture_outputTrue, textTrue, encodingutf-8 ) if proc.returncode ! 0: raise RuntimeError(f脚本执行失败{proc.stderr}) results json.loads(proc.stdout) return AnalyzeResponse(resultsresults)启动服务pip install fastapi uvicorn uvicorn api:app --host 127.0.0.1 --port 8000调用测试curl -X POST http://127.0.0.1:8000/api/sentiment \ -H Content-Type: application/json \ -d {comments: [质量很好性价比高, 客服差退货麻烦]}返回结果{ results: [ {comment: 质量很好性价比高, label: POSITIVE}, {comment: 客服差退货麻烦, label: NEGATIVE} ] }6.2 用 Python 请求调用接口import requests url http://127.0.0.1:8000/api/sentiment payload {comments: [快递很快质量也不错, 不喜欢退了]} response requests.post(url, jsonpayload, timeout30) print(response.status_code) print(response.json())包装成 API 后这个 Skill 就可以被任意上游系统调用Excel 插件批量选中文档、内部运营后台、流程自动化机器人都能复用同一个接口。7. 资源占用与性能观察思路Agent Skills 本身不依赖 GPU所以资源占用的重点不是显存而是下面几个维度7.1 关注三个关键指标指标观察方式说明API Token 消耗模型平台后台查看Skill 描述越长、调用频率越高token 消耗越大脚本执行耗时代码里打印 time.time()规则脚本毫秒级模型调用秒级队列积压情况Redis 队列长度积压太多说明消费速度跟不上7.2 性能优化建议减少每次调用的评论条数控制在 20 到 50 条避免单个请求耗时过长。对高频固定场景可以设置结果缓存相同评论直接返回历史结果不再调用模型。如果用的是规则脚本 模型混合方式先跑规则脚本只把低置信度的样本交给模型判断能省大量 token。并发数建议从小到大逐步调先并发 5 个确认 API 不报限流再把并发调大。8. 常见问题与排查方法问题现象可能原因排查方式解决方案模型不触发 SkillSKILL.md 描述不清晰或when_to_use写的范围太窄检查 SKILL.md 内容确认关键词能被模型识别扩写触发条件增加典型示例Skill 脚本执行报错Python 版本不一致、依赖缺失、编码问题单独在终端运行脚本看报错信息补齐 requirements.txt统一 Python 版本API 一直返回 401API Key 无效或未正确设置环境变量打印 os.environ.get(ANTHROPIC_API_KEY) 是否为 None重新配置环境变量JSON 解析失败模型返回了 Markdown 格式的 JSON或脚本输出多余字符打印原始返回内容对返回内容做正则提取或让模型只输出 JSON批量任务中途卡住单条请求超时、API 限流检查日志中的超时记录和网络状态增加超时重试退避策略输出结果质量不稳定规则脚本关键词覆盖不足或模型幻觉抽样人工验证统计准确率将低置信度样本交给更强的模型复核Skill 目录结构混乱脚本、示例、文档混在一起查看目录结构是否统一按 SKILL.md/scripts/examples 三层结构重新整理接口服务启动失败端口被占用或 FastAPI 依赖缺失检查端口占用和 pip list更换端口或重新安装依赖遇到问题最重要的是先拆层次是 Skill 描述层的问题、脚本层的问题、API 层的问题还是模型本身的问题。逐层排查效率最高。9. 最佳实践与使用建议9.1 Skill 开发建议第一次写 Skill不要追求一步到位。建议先从一个小到不能再小的功能开始跑通“模型识别 Skill - 调用脚本 - 返回结果”的完整链路再逐步加功能。先把规则脚本做出来再考虑是否引入模型二次判断。命名规范也很重要。SKILL.md的name字段建议用英文小写加下划线和目录名保持一致。description控制在两到三句话以内重点说清楚“什么时候用”而不是“怎么做”。9.2 工程化管理建议每个 Skill 必须有README或SKILL.md否则三个月后你自己也想不起来这个 Skill 是干嘛的。脚本要有异常处理不能直接把堆栈抛给模型。Skill 的输入输出尽量用 JSON方便对接其他系统。模型 API Key 不要提交到 Git 仓库使用环境变量或密钥管理服务。批量任务必须加日志输出每批处理的起始位置、条数和耗时。发布或商用前对 Skill 的输出结果做采样人工复核确认准确率达到业务要求。9.3 版权与合规建议批量处理评论、文档、图片时要确认这些数据你有权限使用。特别是涉及个人信息、人脸、语音、版权文本的数据必须进行脱敏处理并保留授权记录。涉及商用场景还要确认模型服务商的使用条款允许你的用途。10. 总结与下一步这一篇从 Agent Skills 的基本概念开始写了一个最小可运行的商品评论情感分析 Skill然后把它升级为批量任务脚本再包装成 HTTP API。这套流程就是 Agent Skills 从入门到实战的完整路径先做一个小功能跑通流程再考虑工程化。几个核心要点再强调一遍Agent Skills 不是新框架而是一种组织和调用 Agent 能力的规范。SKILL.md 是灵魂描述得越清晰模型越不容易乱来。脚本负责确定性执行模型负责理解和生成两者结合才稳定。批量任务和 API 集成是生产落地的关键单次调用跑通只是第一步。最优先验证的功能建议先写一个你日常最常让 Agent 做的事把它做成 Skill测试触发效率和输出稳定性。最容易踩的坑是以为 Skill 写完之后模型就会自动准确调用。实际上要让 Agent 在正确时机调用正确的 Skill需要反复调整SKILL.md里的触发条件和示例。下一步建议试试这几个方向把一个 RAG 检索流程封装成 Skill把复杂的数据分析步骤封装成 Skill把一个内部工具的 API 调用封装成 Skill。跑通之后你会明显感觉到 Agent 开发的效率提升。建议收藏备用开发的时候对照着目录结构和代码框架来写能省不少时间。