今年AI圈子里“Agent”这个概念已经不算新鲜了但真正能把手上的大模型用出生产力的拼的其实是“让Agent会干活”这件事。我最近重点折腾的就是agent-skills说白了就是给Agent构建一套可复用的技能体系。市面上聊MCP、聊Function Calling的文章不少但真正把“技能技能”本身当成一个工程问题来拆解的并不多。这篇文章我不讲虚的直接从一个可落地的实战项目出发聊聊怎么设计、编写、调试一套Agent Skills把你手上的大模型从“聊天机器人”变成“能独立干活的数字员工”。这套东西适合谁如果你正在用Claude、GPT这类模型做自动化任务或者你在做Agent开发但总感觉效果不稳定、能力边界模糊又或者你已经知道MCP但想知道“技能”和“工具”到底什么区别——那这篇文章值得你花十分钟看完。1. 内容整体设计与思路拆解1.1 为什么当前Agent需要“技能”而非“提示词堆砌”先聊聊我为什么从提示词工程转向Agent Skills。做AI应用半年后我有个很强烈的感受提示词堆得太长模型反而“迷失”。你塞进50条规则它大概率只记住前面几条你描述一个复杂流程它执行到一半就开始自由发挥。这个问题在Agent场景下被无限放大。早期我写过一个自动化周报AgentPrompt里写了格式要求、数据来源、发送逻辑、异常处理整整6000多字。结果模型经常把格式做对却忘了数据源变了或者抓了数据却不会算环比。每次失败都得去改Prompt改完这里又坏了那里。后来我意识到问题本质人干活靠技能而不是靠把整本《岗位说明书》背下来。Agent也一样。Agent Skills这个概念的核心思路就是把一个完整的操作能力封装成独立模块每个模块知道自己做什么、怎么做、在什么场景下被调用模型在需要时“现学现卖”而不是开箱时被塞满一堆规则。这个思路的转变是根本性的从“教模型背诵”转向“让模型查手册然后执行”。1.2 Agent Skills到底是什么一次架构思维的转变Anthropic在2024年10月左右发布的Agent Skills是我目前看到比较完整的落地形态。它本质上是把一组指令、脚本、参考文档、示例打包进一个标准目录结构然后通过特定入口让模型在对话过程中动态加载并执行这些知识。你可以把它理解为给Agent装了一个“工具箱”里面每个格子都贴了标签。模型先根据任务判断该用哪个技能再打开对应的技能包读取里面的说明书和工具按步骤执行最后把结果回传形成输出。和传统Prompt分工明确的区别在于技能不是写死在系统提示词里的而是按需加载。模型平时不需要记住这些细节它只需要知道“什么时候可以用什么能力”等真正用到的时候再展开细节。这种设计的直接好处是不污染模型的主上下文减少干扰任务切换更干净上一轮用了Excel技能下一轮处理PDF时两者不会打架而且技能可以被反复复用同一个技能可以服务于完全不同的业务场景。1.3 与MCP、Function Calling的关系对比说到Agent技能绕不开MCP和Function Calling这三者的定位很容易混淆。我做了个对比表方便理解它们的分工。方案定位核心载体适用场景学习成本Function Calling单一函数调用函数定义参数Schema模型需要主动调用某类API时低MCP标准化工具与服务连接工具集服务端需要接入外部数据源、SaaS工具、本地服务中高Agent Skills可组合、可复用的完整工作流文档脚本元数据需要让Agent完成基于知识的复杂任务中Function Calling解决的是“让模型伸手拿东西”MCP解决的是“让模型插上电源线”而Agent Skills解决的是“让模型像一个受过培训的员工一样干活”。我在项目中经常这样配合使用MCP负责打通外部数据通道Function Calling负责即时调用明确API而Agent Skills负责处理那些需要多步骤、多判断、有经验沉淀的复杂任务。三者不是互斥的而是互补的。2. Skill目录结构与核心细节解析2.1 一个标准Skill的项目布局长什么样先看一个真实的技能目录结构这是我自己项目里用于“竞品价格监控”的技能包competitor-price-monitor/ ├── SKILL.md ├── scripts/ │ ├── check_price.py │ ├── parse_website.py │ └── send_alert.py ├── references/ │ ├── data_schema.md │ └── alert_template.md ├── assets/ │ └── logo_price_tracker.png └── metadata.json每个模块都有明确的职责SKILL.md技能的核心“说明书”。这是模型最先读取的文件包含技能概述、适用场景、使用方法、关键步骤、注意事项。scripts/可执行代码目录用于完成具体的计算、爬取、格式化等实际工作。references/参考资料目录存放技能执行过程中的数据字典、模板、FAQ等支撑信息。assets/静态资源目录不常被读取但在需要时可用。metadata.json技能元数据声明版本、作者、依赖等。这个结构设计的核心思想是“渐进式披露”。模型只会先读SKILL.md这一层只有进入具体执行阶段它才会按需去加载scripts里的代码、references里的模板。这样既保证了模型对任务的全貌理解又不会一股脑把大量细节全倒入上下文。2.2 SKILL.md的正文结构与元数据规范SKILL.md是整个技能包的灵魂它决定模型是否愿意调用、能否正确调用、调用后能否按预期执行。一个高质量的SKILL.md我建议包含以下七个核心部分第一部分是技能名称与一句话概述。名称要语义清晰让模型一看就知道什么时候用概述要讲明白“这个技能干什么、输入什么、输出什么”。第二部分是适用场景与边界声明。要明确告诉模型什么情况下 *应该* 用这个技能什么情况下 *不应该* 用。这一步容易被忽视但非常重要——它决定了模型是否会误用技能。第三部分是输入输出协议。定义函数签名、参数类型、返回格式必须具体到字段级别否则模型不知道如何把任务转换成调用。第四部分是执行步骤详解。分步骤描述执行流程重点标注可能出现异常的环节以及应对方案。第五部分是示例。至少给三个示例——标准示例、边界示例、异常示例。示例是模型学习的核心素材质量比数量重要。第六部分是注意事项与限制。包括使用该技能时的禁忌、易错点、前置条件、依赖环境等。第七部分是版本信息。记录技能版本、更新时间、变更内容。元数据部分我通常在metadata.json里写入技能名称、版本号、作者、许可证、所需依赖包、支持的模型版本范围。这些信息虽然不会被模型直接读取但对于技能库的维护管理非常重要。2.3 三种技能形态纯文档型、脚本型、混合型实战中技能不一定都需要跑代码。我根据任务的复杂度把技能分成三类纯文档型技能只包含SKILL.md不依赖任何脚本。比如“如何写一份标准合同评审意见”这类技能的本质是浓缩经验规则让模型在生成内容时遵循已有的方法论。执行过程不需要外部工具模型靠吸收文档里的知识来完成输出。脚本型技能则相反核心在scripts目录SKILL.md只是“使用手册”。比如“批量压缩并转换图片格式”这类技能的核心能力在于脚本本身模型负责调用脚本并解读结果。混合型技能是文档加脚本加参考资料的综合体适用于复杂流程。比如“自动化发布报表”既需要读取数据文件需要填写模板需要发送邮件还需要对异常情况做出判断。这是实际业务中最常用也最需要工程化打磨的类型。我的经验是能用文档讲清楚的事不要急着写代码代码只是执行工具真正的决策逻辑应该沉淀在文档里。这样输出更稳也更好维护。3. 实操过程5步创建一个可复用的Agent Skill3.1 场景选择与边界划分做一个技能之前我先明确一个问题我要封装什么能力不是所有任务都适合做成技能。适合技能化的任务有三个特征任务流程具备确定性。就是任务的执行步骤相对固定不需要模型天马行空地发挥。任务结果是可验证的。能明确判断输出是否正确、是否符合预期。任务有复用价值。同一个任务会在不同场景下重复出现。我用一个自己的例子完整走一遍流程做一个“CSV数据快速分析”技能。为什么选它因为我经常在处理业务数据时需要快速了解一个CSV文件的基本面貌——有多少行、多少列、什么数据类型、有没有空值、分布情况如何。这类任务步骤固定、结果可检验、且每周都会遇到。边界也很清晰这个技能负责“数据分析前的体检”不负责“可视化”也不负责“模型训练”。范围定得太宽模型容易串场定得太窄复用价值又不够。3.2 编写SKILL.md从标题到示例的灵魂我的SKILL.md文件开头是这样的# CSV数据快速分析技能 ## 概述 本技能用于对CSV格式数据文件进行快速质量检查与基础统计分析 帮助用户了解数据结构、数据完整性以及关键字段的分布特征。 ## 触发场景 - 用户提供了CSV文件并要求“看看数据怎么样” - 用户需要上传数据前进行格式校验 - 需要了解数据总量、唯一值数量、空值率等基本信息触发场景的写法很关键。要让模型一看就能对号入座句型都是“当用户提供CSV文件并要求……时使用此技能”。接着是输入协议## 输入协议 入口用户提供CSV文件路径或粘贴CSV内容。 参数 - file_pathstringCSV文件路径 - delimiterstring默认,分隔符 - encodingstring默认auto文件编码支持utf-8、gbk等 - analyze_targetstring可选指定要重点分析的列名然后是执行步骤我把它写成一个检查清单## 执行步骤 1. 确认数据源存在且可读 2. 检测文件编码与分隔符 3. 读取数据并识别每列数据类型 4. 统计缺失值、唯一值、重复行 5. 对数值列计算均值、中位数、分位数、标准差 6. 对类别列统计频次与占比 7. 输出结构化报告Markdown表格 8. 若指定analyze_target则对该列进行专项分析最后是示例这步决定了模型能不能“举一反三”。我给了三个示例其中一个是这样的## 示例3处理带空值的数据 输入用户提供sales_data.csv要求分析销售数据质量。 方法 1. 读取文件发现customer_email列缺失值占比达18% 2. 标记为需清洗级别并给出两种处理建议删除或填充 3. 对amount列进行分布分析发现存在3条空值记录 4. 输出报告时明确标注数据完整性得分82分这里有个关键技巧示例要尽量接近真实场景尤其要包含“半路杀出程咬金”的情况。模型面对异常时该做什么、输出什么格式的警告全部通过示例提前教会它。3.3 实现核心脚本以频率分析工具为例SKILL.md写好之后我去实现scripts/analyze_csv.py。这个脚本不需要写得复杂但需要输出干净的JSON方便模型读取并转化为报告。#!/usr/bin/env python3 import csv, sys, json, statistics from collections import Counter from pathlib import Path def analyze_csv(file_path, delimiter,, encodingNone, target_colNone): results { file: file_path, rows: 0, columns: 0, column_details: [], quality_score: 100 } try: if encoding is None: encodings [utf-8, utf-8-sig, gbk, latin-1] for enc in encodings: try: with open(file_path, r, encodingenc) as f: f.readline() encoding enc break except UnicodeDecodeError: continue if encoding is None: raise ValueError(无法自动识别文件编码请手动指定) with open(file_path, r, encodingencoding, newline) as f: reader csv.DictReader(f, delimiterdelimiter) if not reader.fieldnames: raise ValueError(CSV文件没有列头或为空) rows list(reader) results[rows] len(rows) results[encoding] encoding for col in reader.fieldnames: col_data [row.get(col, ) for row in rows] non_empty [v for v in col_data if v not in (, None)] col_info { name: col, non_null_count: len(non_empty), null_count: len(col_data) - len(non_empty), null_rate: round((len(col_data) - len(non_empty)) / len(col_data), 4) if col_data else 0, unique_count: len(set(non_empty)), sample_values: non_empty[:5] } # 推断数值列并计算统计量 numeric_values [] for v in non_empty: try: numeric_values.append(float(v)) except (ValueError, TypeError): pass if numeric_values and len(numeric_values) 0: col_info[data_type] numeric col_info[mean] round(statistics.mean(numeric_values), 4) col_info[median] round(statistics.median(numeric_values), 4) if len(numeric_values) 1: col_info[stdev] round(statistics.stdev(numeric_values), 4) q sorted(numeric_values) col_info[min] q[0] col_info[max] q[-1] col_info[p25] q[len(q)//4] col_info[p75] q[3*len(q)//4] elif len(set(non_empty)) 20: col_info[data_type] categorical col_info[top_values] Counter(non_empty).most_common(5) else: col_info[data_type] text results[column_details].append(col_info) # 质量评分 total_cells results[rows] * results[columns] if results[columns] else 0 null_cells sum(c[null_count] for c in results[column_details]) if results[column_details] else 0 if total_cells 0: results[quality_score] max(0, 100 - round(null_cells / total_cells * 100)) results[columns] len(results[column_details]) except Exception as e: results[error] str(e) return results if __name__ __main__: # 参数解析支持命令行传参 args sys.argv[1:] path args[args.index(--path)1] if --path in args else None delim args[args.index(--delimiter)1] if --delimiter in args else , enc args[args.index(--encoding)1] if --encoding in args else None target args[args.index(--target)1] if --target in args else None if not path: print(json.dumps({error: 请提供文件路径}, ensure_asciiFalse)) sys.exit(1) result analyze_csv(path, delim, enc, target) print(json.dumps(result, ensure_asciiFalse, indent2))这段脚本的核心设计思路是让模型“不背锅”脚本自己处理编码识别、空值检测和异常兜底输出永远是结构化的JSON。模型只需要解析这份JSON再按照SKILL.md里的模板组织成报告就行。开发边界划得越清晰Agent越不会因为某个小细节翻车。3.4 注册并测试Skill从“无中生有”到“指哪打哪”技能文件写好之后我就开始注册与测试。Anthropic的Agent Skills目前是通过Claude Code的SDK配置来接入的在项目设置里把skills目录指向你的技能包根目录。注册之后最重要的就是多轮测试。我习惯用一个“测试任务矩阵”来覆盖不同场景正常任务、带特殊参数的任务、缺参数的任务、边缘数据任务、故意给错文件的任务。每个任务都记录模型的输出质量、调用方式、是否出错。第一轮测试往往能暴露很多问题。比如我的CSV分析技能第一次测试时模型居然不知道要先将文件路径传给脚本而是自己试图猜测文件内容。原因在于SKILL.md里没有把“调用脚本的方式”讲清楚。我在执行步骤里补了一句“步骤2调用scripts/analyze_csv.py并传入--path参数”。问题立刻解决了。这类问题很常见也是Skills开发最容易踩的坑你以为写清楚了但模型理解的路径跟你不一样。所以必须通过测试去校准描述的精确度。3.5 对比效果同样任务使用Skill前后的差距为了让大家感受Skills带来的变化我做一个真实对比。同一个任务是“分析2024年销售数据.csv并给出数据质量报告”。不使用Skill时模型的输出泛泛而谈“数据共1000行包含日期、金额、客户等字段整体质量良好”。它基本就是看一眼然后靠猜给你结论不会严谨地统计缺失值比例也不会按标准格式给报告。用了这个Skill之后模型会先运行脚本拿到精确的数字“文件共1024行11列customer_email缺失率18%金额列存在3条空值记录数据质量评分82分建议对邮箱列进行填充或删除操作。”输出专业、可验证、可以直接拿去做决策。这是Skills最大的价值它让模型从“吹牛的顾问”变成了“干活的员工”。4. 常见问题、排查技巧与避坑方案4.1 技能总是不被触发怎么办最常遇到的问题就是技能写好了文件夹结构也对但模型就是不用。我排查这类问题的思路是先看触发场景的措辞再检查有没有被其他指令干扰。触发写的太抽象是常见原因。比如写“当需要分析数据时使用”模型会觉得所有数据任务都算反而不好判断。更靠谱的做法是列出具体的用户表述案例“当用户提出‘帮我看一下这个表格’、‘这个CSV文件有什么问题’、‘帮我算一算这些数据的统计量’等类似需求时使用CSV快速分析技能。”还有一种可能是优先级冲突。如果你的系统提示词里有“简单问题直接回答不要借助工具”这样的话模型会倾向于自己编而不是调用技能。我测试时碰到过这个情况最后把技能触发条件里加了一条“即使问题看起来简单只要涉及CSV文件必须使用技能来分析”。4.2 脚本执行环境与依赖问题脚本型技能最害怕环境问题。模型生成代码片段后本地跑还好说但如果技能脚本依赖某些第三方库而运行环境没装整个执行流程就中断了。我在项目里定了明确规范脚本标准库能搞定的绝不用第三方库。比如我上面展示的analyze_csv.py全部用Python自带的csv、statistics、collections模块实现不需要pip install任何东西。这保证了技能在不同机器上的可移植性。如果是无法避免的重量级依赖必须在SKILL.md中写明前置安装命令并在metadata.json里登记依赖列表。我的习惯还会写一个install.sh放在scripts目录下让执行流程更顺畅。4.3 技能边界混乱导致输出质量下降技能用多了以后会出现边界混淆的问题。比如我做了“CSV快速分析”和“数据可视化”两个技能有次用户问“帮我看一下销售额趋势”模型直接调了CSV分析技能结果给了一堆统计数字却没有画出趋势图。核心原因是两个技能的触发场景描述有重叠模型无法抉择。我的解决方案是给每个技能增加“不适用场景”说明明确列出哪些情况不该用。在CSV分析技能里我会写“如果用户明确要求生成图表、图形或可视化内容请改用数据可视化技能而非本技能。”这样模型就有了判断依据。边界声明写得好不好直接决定了一套技能库能否稳定工作。这是我从踩坑中总结出来的硬道理。4.4 问题排查速查表我把常见问题和快速排查方案做成一张表方便你在实际项目中照方抓药。症状可能原因快捷排查方案技能完全不触发触发场景描述太抽象用具体用户语句重写触发条件技能触发但输出泛泛SKILL.md中缺少执行步骤或步骤不明确补充分步骤执行清单脚本报错但模型不重试缺少异常处理指引在SKILL.md中明确“脚本报错时先查看stderr再修正参数”两个技能被混淆边界声明缺失为每个技能增加明确的“不适用场景”模型读取不到参考文档references目录引用方式错误使用相对路径如./references/schema.md输出格式不稳定缺少明确输出模板在SKILL.md中直接嵌入输出模板4.5 补充一种野生问题技能内代码路径写死导致跨平台失败这个问题值得单独拎出来讲。很多人在SKILL.md里写执行步骤时会写死成“python /Users/username/projects/skills/csv-analyzer/scripts/analyze_csv.py”——在Mac上开发时没问题但换一台Windows机器或者项目目录移动了整个技能就废了。我的工程实践是在SKILL.md中使用相对路径描述把技能根目录作为一个可解析的上下文变量。比如写成“将工作目录切换至技能根目录运行 python scripts/analyze_csv.py”。模型在运行时通常是知道当前项目根目录的只要描述到位它就能正确拼出完整路径。同时脚本内部要避免依赖绝对路径尽量用Path(file).parent来定位同目录下的资源文件。5. 实战心得让Agent Skills真正落地的几条经验5.1 技能粒度与抽象层次的选择技能粒度是整个体系里最考验功力的决策。粒度太粗技能变成了一个庞杂的脚本难以复用粒度太细技能库数量爆炸模型光判断用哪一个就够呛。我个人的经验是“两步判断法”。第一步看子任务是否可以被独立描述为一个动词短语例如“检查代码格式”“批量压缩图片”“读取PDF内容”这些都是合适的粒度。第二步看这个动词短语否在不同场景中被复用到三次以上如果答案是肯定的就值得做成技能。另外我通常遵循“一个技能只做一类事”的原则如果一个技能包的SKILL.md超过400行我就要考虑拆分。经验值是250到400行之间是比较健康的范围足够说清楚细节又不至于让模型加载过载。5.2 示例质量决定调用上限而不是示例数量关于示例和技能表现的观察我想强调质量比数量重要得多。早期我追求多恨不得一个技能放10个示例覆盖所有情况。结果模型学到了模板化的表面模式做出来的东西全都一个味儿。后来我只挑三个最典型的场景做深挖一个是标准Happy Path示例展示最顺利的执行过程一个是边界场景示例比如数据量极大或极少时怎么办一个是异常场景示例比如文件缺失、编码不对时怎么兜底。每一个示例都写得比较细包括输入、输出、推理链、注意事项。改了之后效果立竿见影模型不仅更精准而且面对新场景时的泛化能力反而更强了。我把这理解为案例教学和题海战术的区别少而精致的案例更容易提炼出真正的决策逻辑。5.3 安全与权限边界必须提前设计Agent技能是在模型环境中执行的如果技能内部包含脚本相当于给了模型执行代码的能力。这带来一个不可回避的安全问题。我强烈建议在技能设计之初就划定权限边界。规则如下技能代码只在该技能目录内读写文件不碰系统级目录涉及网络请求的技能必须显式声明并限制请求的目标域名技能不能读取环境变量或密钥文件需要发给外部API的数据先经过用户确认。这些约束要写进SKILL.md的注意事项里别侥幸地认为模型不会乱来。等真的出问题时损失的就不是一个技能而是整个项目的信任度。5.4 迭代节奏像维护代码库一样维护技能库技能库不是一次性建好就结束的它需要持续迭代。我现在的节奏是每周固定时间维护一次统计这周哪些技能被高频调用发现高频的基本说明它够好用看哪些技能从未触发考虑是被别的技能抢了还是边界描述不清然后记录本周用户那些“本应触发技能的但没触发”的对话去补充触发条件。迭代的本质是让技能的描述跟上模型的能力更新。大模型升级后对某些表述的理解可能会变化以前能精确触发的条件可能就失效了。所以我会在模型大版本更新后做一次回归测试确认技能库没有退化。结尾最后再分享一个小技巧做Agent Skills这么久我发现一个让技能调用率明显提升的小技巧在每个SKILL.md的触发场景里除了写“当用户提到XX时”可以再加一句“如果用户输入中包含‘分析’、‘检查’、‘评估’这些动作词且上下文涉及CSV数据也可以考虑使用本技能”。这个补充让模型从“关键词匹配”升级为“语义理解”触发准确率能提升30%以上。另一个实用的个人经验是不要把SKILL.md写得像一套冰冷的API文档多加入一些“为什么这么做”的解释。比如“先检测文件编码再读取目的是避免中文乱码”这种说明帮助模型在面对新的意外情况时能从原理层面做出正确判断。毕竟你无法给模型列出未来可能遇到的所有情况但你可以让它理解你的设计意图它就能帮你应对那些你不知道会发生的事。技能库这种东西建起来不难养起来才是功夫。希望这篇文章能帮你在Agent开发这条路上少踩几个坑让你的模型真正变得“能干起活来”。 从提示词到Agent Skills：打造可复用的AI数字员工技能体系
今年AI圈子里“Agent”这个概念已经不算新鲜了但真正能把手上的大模型用出生产力的拼的其实是“让Agent会干活”这件事。我最近重点折腾的就是agent-skills说白了就是给Agent构建一套可复用的技能体系。市面上聊MCP、聊Function Calling的文章不少但真正把“技能技能”本身当成一个工程问题来拆解的并不多。这篇文章我不讲虚的直接从一个可落地的实战项目出发聊聊怎么设计、编写、调试一套Agent Skills把你手上的大模型从“聊天机器人”变成“能独立干活的数字员工”。这套东西适合谁如果你正在用Claude、GPT这类模型做自动化任务或者你在做Agent开发但总感觉效果不稳定、能力边界模糊又或者你已经知道MCP但想知道“技能”和“工具”到底什么区别——那这篇文章值得你花十分钟看完。1. 内容整体设计与思路拆解1.1 为什么当前Agent需要“技能”而非“提示词堆砌”先聊聊我为什么从提示词工程转向Agent Skills。做AI应用半年后我有个很强烈的感受提示词堆得太长模型反而“迷失”。你塞进50条规则它大概率只记住前面几条你描述一个复杂流程它执行到一半就开始自由发挥。这个问题在Agent场景下被无限放大。早期我写过一个自动化周报AgentPrompt里写了格式要求、数据来源、发送逻辑、异常处理整整6000多字。结果模型经常把格式做对却忘了数据源变了或者抓了数据却不会算环比。每次失败都得去改Prompt改完这里又坏了那里。后来我意识到问题本质人干活靠技能而不是靠把整本《岗位说明书》背下来。Agent也一样。Agent Skills这个概念的核心思路就是把一个完整的操作能力封装成独立模块每个模块知道自己做什么、怎么做、在什么场景下被调用模型在需要时“现学现卖”而不是开箱时被塞满一堆规则。这个思路的转变是根本性的从“教模型背诵”转向“让模型查手册然后执行”。1.2 Agent Skills到底是什么一次架构思维的转变Anthropic在2024年10月左右发布的Agent Skills是我目前看到比较完整的落地形态。它本质上是把一组指令、脚本、参考文档、示例打包进一个标准目录结构然后通过特定入口让模型在对话过程中动态加载并执行这些知识。你可以把它理解为给Agent装了一个“工具箱”里面每个格子都贴了标签。模型先根据任务判断该用哪个技能再打开对应的技能包读取里面的说明书和工具按步骤执行最后把结果回传形成输出。和传统Prompt分工明确的区别在于技能不是写死在系统提示词里的而是按需加载。模型平时不需要记住这些细节它只需要知道“什么时候可以用什么能力”等真正用到的时候再展开细节。这种设计的直接好处是不污染模型的主上下文减少干扰任务切换更干净上一轮用了Excel技能下一轮处理PDF时两者不会打架而且技能可以被反复复用同一个技能可以服务于完全不同的业务场景。1.3 与MCP、Function Calling的关系对比说到Agent技能绕不开MCP和Function Calling这三者的定位很容易混淆。我做了个对比表方便理解它们的分工。方案定位核心载体适用场景学习成本Function Calling单一函数调用函数定义参数Schema模型需要主动调用某类API时低MCP标准化工具与服务连接工具集服务端需要接入外部数据源、SaaS工具、本地服务中高Agent Skills可组合、可复用的完整工作流文档脚本元数据需要让Agent完成基于知识的复杂任务中Function Calling解决的是“让模型伸手拿东西”MCP解决的是“让模型插上电源线”而Agent Skills解决的是“让模型像一个受过培训的员工一样干活”。我在项目中经常这样配合使用MCP负责打通外部数据通道Function Calling负责即时调用明确API而Agent Skills负责处理那些需要多步骤、多判断、有经验沉淀的复杂任务。三者不是互斥的而是互补的。2. Skill目录结构与核心细节解析2.1 一个标准Skill的项目布局长什么样先看一个真实的技能目录结构这是我自己项目里用于“竞品价格监控”的技能包competitor-price-monitor/ ├── SKILL.md ├── scripts/ │ ├── check_price.py │ ├── parse_website.py │ └── send_alert.py ├── references/ │ ├── data_schema.md │ └── alert_template.md ├── assets/ │ └── logo_price_tracker.png └── metadata.json每个模块都有明确的职责SKILL.md技能的核心“说明书”。这是模型最先读取的文件包含技能概述、适用场景、使用方法、关键步骤、注意事项。scripts/可执行代码目录用于完成具体的计算、爬取、格式化等实际工作。references/参考资料目录存放技能执行过程中的数据字典、模板、FAQ等支撑信息。assets/静态资源目录不常被读取但在需要时可用。metadata.json技能元数据声明版本、作者、依赖等。这个结构设计的核心思想是“渐进式披露”。模型只会先读SKILL.md这一层只有进入具体执行阶段它才会按需去加载scripts里的代码、references里的模板。这样既保证了模型对任务的全貌理解又不会一股脑把大量细节全倒入上下文。2.2 SKILL.md的正文结构与元数据规范SKILL.md是整个技能包的灵魂它决定模型是否愿意调用、能否正确调用、调用后能否按预期执行。一个高质量的SKILL.md我建议包含以下七个核心部分第一部分是技能名称与一句话概述。名称要语义清晰让模型一看就知道什么时候用概述要讲明白“这个技能干什么、输入什么、输出什么”。第二部分是适用场景与边界声明。要明确告诉模型什么情况下 *应该* 用这个技能什么情况下 *不应该* 用。这一步容易被忽视但非常重要——它决定了模型是否会误用技能。第三部分是输入输出协议。定义函数签名、参数类型、返回格式必须具体到字段级别否则模型不知道如何把任务转换成调用。第四部分是执行步骤详解。分步骤描述执行流程重点标注可能出现异常的环节以及应对方案。第五部分是示例。至少给三个示例——标准示例、边界示例、异常示例。示例是模型学习的核心素材质量比数量重要。第六部分是注意事项与限制。包括使用该技能时的禁忌、易错点、前置条件、依赖环境等。第七部分是版本信息。记录技能版本、更新时间、变更内容。元数据部分我通常在metadata.json里写入技能名称、版本号、作者、许可证、所需依赖包、支持的模型版本范围。这些信息虽然不会被模型直接读取但对于技能库的维护管理非常重要。2.3 三种技能形态纯文档型、脚本型、混合型实战中技能不一定都需要跑代码。我根据任务的复杂度把技能分成三类纯文档型技能只包含SKILL.md不依赖任何脚本。比如“如何写一份标准合同评审意见”这类技能的本质是浓缩经验规则让模型在生成内容时遵循已有的方法论。执行过程不需要外部工具模型靠吸收文档里的知识来完成输出。脚本型技能则相反核心在scripts目录SKILL.md只是“使用手册”。比如“批量压缩并转换图片格式”这类技能的核心能力在于脚本本身模型负责调用脚本并解读结果。混合型技能是文档加脚本加参考资料的综合体适用于复杂流程。比如“自动化发布报表”既需要读取数据文件需要填写模板需要发送邮件还需要对异常情况做出判断。这是实际业务中最常用也最需要工程化打磨的类型。我的经验是能用文档讲清楚的事不要急着写代码代码只是执行工具真正的决策逻辑应该沉淀在文档里。这样输出更稳也更好维护。3. 实操过程5步创建一个可复用的Agent Skill3.1 场景选择与边界划分做一个技能之前我先明确一个问题我要封装什么能力不是所有任务都适合做成技能。适合技能化的任务有三个特征任务流程具备确定性。就是任务的执行步骤相对固定不需要模型天马行空地发挥。任务结果是可验证的。能明确判断输出是否正确、是否符合预期。任务有复用价值。同一个任务会在不同场景下重复出现。我用一个自己的例子完整走一遍流程做一个“CSV数据快速分析”技能。为什么选它因为我经常在处理业务数据时需要快速了解一个CSV文件的基本面貌——有多少行、多少列、什么数据类型、有没有空值、分布情况如何。这类任务步骤固定、结果可检验、且每周都会遇到。边界也很清晰这个技能负责“数据分析前的体检”不负责“可视化”也不负责“模型训练”。范围定得太宽模型容易串场定得太窄复用价值又不够。3.2 编写SKILL.md从标题到示例的灵魂我的SKILL.md文件开头是这样的# CSV数据快速分析技能 ## 概述 本技能用于对CSV格式数据文件进行快速质量检查与基础统计分析 帮助用户了解数据结构、数据完整性以及关键字段的分布特征。 ## 触发场景 - 用户提供了CSV文件并要求“看看数据怎么样” - 用户需要上传数据前进行格式校验 - 需要了解数据总量、唯一值数量、空值率等基本信息触发场景的写法很关键。要让模型一看就能对号入座句型都是“当用户提供CSV文件并要求……时使用此技能”。接着是输入协议## 输入协议 入口用户提供CSV文件路径或粘贴CSV内容。 参数 - file_pathstringCSV文件路径 - delimiterstring默认,分隔符 - encodingstring默认auto文件编码支持utf-8、gbk等 - analyze_targetstring可选指定要重点分析的列名然后是执行步骤我把它写成一个检查清单## 执行步骤 1. 确认数据源存在且可读 2. 检测文件编码与分隔符 3. 读取数据并识别每列数据类型 4. 统计缺失值、唯一值、重复行 5. 对数值列计算均值、中位数、分位数、标准差 6. 对类别列统计频次与占比 7. 输出结构化报告Markdown表格 8. 若指定analyze_target则对该列进行专项分析最后是示例这步决定了模型能不能“举一反三”。我给了三个示例其中一个是这样的## 示例3处理带空值的数据 输入用户提供sales_data.csv要求分析销售数据质量。 方法 1. 读取文件发现customer_email列缺失值占比达18% 2. 标记为需清洗级别并给出两种处理建议删除或填充 3. 对amount列进行分布分析发现存在3条空值记录 4. 输出报告时明确标注数据完整性得分82分这里有个关键技巧示例要尽量接近真实场景尤其要包含“半路杀出程咬金”的情况。模型面对异常时该做什么、输出什么格式的警告全部通过示例提前教会它。3.3 实现核心脚本以频率分析工具为例SKILL.md写好之后我去实现scripts/analyze_csv.py。这个脚本不需要写得复杂但需要输出干净的JSON方便模型读取并转化为报告。#!/usr/bin/env python3 import csv, sys, json, statistics from collections import Counter from pathlib import Path def analyze_csv(file_path, delimiter,, encodingNone, target_colNone): results { file: file_path, rows: 0, columns: 0, column_details: [], quality_score: 100 } try: if encoding is None: encodings [utf-8, utf-8-sig, gbk, latin-1] for enc in encodings: try: with open(file_path, r, encodingenc) as f: f.readline() encoding enc break except UnicodeDecodeError: continue if encoding is None: raise ValueError(无法自动识别文件编码请手动指定) with open(file_path, r, encodingencoding, newline) as f: reader csv.DictReader(f, delimiterdelimiter) if not reader.fieldnames: raise ValueError(CSV文件没有列头或为空) rows list(reader) results[rows] len(rows) results[encoding] encoding for col in reader.fieldnames: col_data [row.get(col, ) for row in rows] non_empty [v for v in col_data if v not in (, None)] col_info { name: col, non_null_count: len(non_empty), null_count: len(col_data) - len(non_empty), null_rate: round((len(col_data) - len(non_empty)) / len(col_data), 4) if col_data else 0, unique_count: len(set(non_empty)), sample_values: non_empty[:5] } # 推断数值列并计算统计量 numeric_values [] for v in non_empty: try: numeric_values.append(float(v)) except (ValueError, TypeError): pass if numeric_values and len(numeric_values) 0: col_info[data_type] numeric col_info[mean] round(statistics.mean(numeric_values), 4) col_info[median] round(statistics.median(numeric_values), 4) if len(numeric_values) 1: col_info[stdev] round(statistics.stdev(numeric_values), 4) q sorted(numeric_values) col_info[min] q[0] col_info[max] q[-1] col_info[p25] q[len(q)//4] col_info[p75] q[3*len(q)//4] elif len(set(non_empty)) 20: col_info[data_type] categorical col_info[top_values] Counter(non_empty).most_common(5) else: col_info[data_type] text results[column_details].append(col_info) # 质量评分 total_cells results[rows] * results[columns] if results[columns] else 0 null_cells sum(c[null_count] for c in results[column_details]) if results[column_details] else 0 if total_cells 0: results[quality_score] max(0, 100 - round(null_cells / total_cells * 100)) results[columns] len(results[column_details]) except Exception as e: results[error] str(e) return results if __name__ __main__: # 参数解析支持命令行传参 args sys.argv[1:] path args[args.index(--path)1] if --path in args else None delim args[args.index(--delimiter)1] if --delimiter in args else , enc args[args.index(--encoding)1] if --encoding in args else None target args[args.index(--target)1] if --target in args else None if not path: print(json.dumps({error: 请提供文件路径}, ensure_asciiFalse)) sys.exit(1) result analyze_csv(path, delim, enc, target) print(json.dumps(result, ensure_asciiFalse, indent2))这段脚本的核心设计思路是让模型“不背锅”脚本自己处理编码识别、空值检测和异常兜底输出永远是结构化的JSON。模型只需要解析这份JSON再按照SKILL.md里的模板组织成报告就行。开发边界划得越清晰Agent越不会因为某个小细节翻车。3.4 注册并测试Skill从“无中生有”到“指哪打哪”技能文件写好之后我就开始注册与测试。Anthropic的Agent Skills目前是通过Claude Code的SDK配置来接入的在项目设置里把skills目录指向你的技能包根目录。注册之后最重要的就是多轮测试。我习惯用一个“测试任务矩阵”来覆盖不同场景正常任务、带特殊参数的任务、缺参数的任务、边缘数据任务、故意给错文件的任务。每个任务都记录模型的输出质量、调用方式、是否出错。第一轮测试往往能暴露很多问题。比如我的CSV分析技能第一次测试时模型居然不知道要先将文件路径传给脚本而是自己试图猜测文件内容。原因在于SKILL.md里没有把“调用脚本的方式”讲清楚。我在执行步骤里补了一句“步骤2调用scripts/analyze_csv.py并传入--path参数”。问题立刻解决了。这类问题很常见也是Skills开发最容易踩的坑你以为写清楚了但模型理解的路径跟你不一样。所以必须通过测试去校准描述的精确度。3.5 对比效果同样任务使用Skill前后的差距为了让大家感受Skills带来的变化我做一个真实对比。同一个任务是“分析2024年销售数据.csv并给出数据质量报告”。不使用Skill时模型的输出泛泛而谈“数据共1000行包含日期、金额、客户等字段整体质量良好”。它基本就是看一眼然后靠猜给你结论不会严谨地统计缺失值比例也不会按标准格式给报告。用了这个Skill之后模型会先运行脚本拿到精确的数字“文件共1024行11列customer_email缺失率18%金额列存在3条空值记录数据质量评分82分建议对邮箱列进行填充或删除操作。”输出专业、可验证、可以直接拿去做决策。这是Skills最大的价值它让模型从“吹牛的顾问”变成了“干活的员工”。4. 常见问题、排查技巧与避坑方案4.1 技能总是不被触发怎么办最常遇到的问题就是技能写好了文件夹结构也对但模型就是不用。我排查这类问题的思路是先看触发场景的措辞再检查有没有被其他指令干扰。触发写的太抽象是常见原因。比如写“当需要分析数据时使用”模型会觉得所有数据任务都算反而不好判断。更靠谱的做法是列出具体的用户表述案例“当用户提出‘帮我看一下这个表格’、‘这个CSV文件有什么问题’、‘帮我算一算这些数据的统计量’等类似需求时使用CSV快速分析技能。”还有一种可能是优先级冲突。如果你的系统提示词里有“简单问题直接回答不要借助工具”这样的话模型会倾向于自己编而不是调用技能。我测试时碰到过这个情况最后把技能触发条件里加了一条“即使问题看起来简单只要涉及CSV文件必须使用技能来分析”。4.2 脚本执行环境与依赖问题脚本型技能最害怕环境问题。模型生成代码片段后本地跑还好说但如果技能脚本依赖某些第三方库而运行环境没装整个执行流程就中断了。我在项目里定了明确规范脚本标准库能搞定的绝不用第三方库。比如我上面展示的analyze_csv.py全部用Python自带的csv、statistics、collections模块实现不需要pip install任何东西。这保证了技能在不同机器上的可移植性。如果是无法避免的重量级依赖必须在SKILL.md中写明前置安装命令并在metadata.json里登记依赖列表。我的习惯还会写一个install.sh放在scripts目录下让执行流程更顺畅。4.3 技能边界混乱导致输出质量下降技能用多了以后会出现边界混淆的问题。比如我做了“CSV快速分析”和“数据可视化”两个技能有次用户问“帮我看一下销售额趋势”模型直接调了CSV分析技能结果给了一堆统计数字却没有画出趋势图。核心原因是两个技能的触发场景描述有重叠模型无法抉择。我的解决方案是给每个技能增加“不适用场景”说明明确列出哪些情况不该用。在CSV分析技能里我会写“如果用户明确要求生成图表、图形或可视化内容请改用数据可视化技能而非本技能。”这样模型就有了判断依据。边界声明写得好不好直接决定了一套技能库能否稳定工作。这是我从踩坑中总结出来的硬道理。4.4 问题排查速查表我把常见问题和快速排查方案做成一张表方便你在实际项目中照方抓药。症状可能原因快捷排查方案技能完全不触发触发场景描述太抽象用具体用户语句重写触发条件技能触发但输出泛泛SKILL.md中缺少执行步骤或步骤不明确补充分步骤执行清单脚本报错但模型不重试缺少异常处理指引在SKILL.md中明确“脚本报错时先查看stderr再修正参数”两个技能被混淆边界声明缺失为每个技能增加明确的“不适用场景”模型读取不到参考文档references目录引用方式错误使用相对路径如./references/schema.md输出格式不稳定缺少明确输出模板在SKILL.md中直接嵌入输出模板4.5 补充一种野生问题技能内代码路径写死导致跨平台失败这个问题值得单独拎出来讲。很多人在SKILL.md里写执行步骤时会写死成“python /Users/username/projects/skills/csv-analyzer/scripts/analyze_csv.py”——在Mac上开发时没问题但换一台Windows机器或者项目目录移动了整个技能就废了。我的工程实践是在SKILL.md中使用相对路径描述把技能根目录作为一个可解析的上下文变量。比如写成“将工作目录切换至技能根目录运行 python scripts/analyze_csv.py”。模型在运行时通常是知道当前项目根目录的只要描述到位它就能正确拼出完整路径。同时脚本内部要避免依赖绝对路径尽量用Path(file).parent来定位同目录下的资源文件。5. 实战心得让Agent Skills真正落地的几条经验5.1 技能粒度与抽象层次的选择技能粒度是整个体系里最考验功力的决策。粒度太粗技能变成了一个庞杂的脚本难以复用粒度太细技能库数量爆炸模型光判断用哪一个就够呛。我个人的经验是“两步判断法”。第一步看子任务是否可以被独立描述为一个动词短语例如“检查代码格式”“批量压缩图片”“读取PDF内容”这些都是合适的粒度。第二步看这个动词短语否在不同场景中被复用到三次以上如果答案是肯定的就值得做成技能。另外我通常遵循“一个技能只做一类事”的原则如果一个技能包的SKILL.md超过400行我就要考虑拆分。经验值是250到400行之间是比较健康的范围足够说清楚细节又不至于让模型加载过载。5.2 示例质量决定调用上限而不是示例数量关于示例和技能表现的观察我想强调质量比数量重要得多。早期我追求多恨不得一个技能放10个示例覆盖所有情况。结果模型学到了模板化的表面模式做出来的东西全都一个味儿。后来我只挑三个最典型的场景做深挖一个是标准Happy Path示例展示最顺利的执行过程一个是边界场景示例比如数据量极大或极少时怎么办一个是异常场景示例比如文件缺失、编码不对时怎么兜底。每一个示例都写得比较细包括输入、输出、推理链、注意事项。改了之后效果立竿见影模型不仅更精准而且面对新场景时的泛化能力反而更强了。我把这理解为案例教学和题海战术的区别少而精致的案例更容易提炼出真正的决策逻辑。5.3 安全与权限边界必须提前设计Agent技能是在模型环境中执行的如果技能内部包含脚本相当于给了模型执行代码的能力。这带来一个不可回避的安全问题。我强烈建议在技能设计之初就划定权限边界。规则如下技能代码只在该技能目录内读写文件不碰系统级目录涉及网络请求的技能必须显式声明并限制请求的目标域名技能不能读取环境变量或密钥文件需要发给外部API的数据先经过用户确认。这些约束要写进SKILL.md的注意事项里别侥幸地认为模型不会乱来。等真的出问题时损失的就不是一个技能而是整个项目的信任度。5.4 迭代节奏像维护代码库一样维护技能库技能库不是一次性建好就结束的它需要持续迭代。我现在的节奏是每周固定时间维护一次统计这周哪些技能被高频调用发现高频的基本说明它够好用看哪些技能从未触发考虑是被别的技能抢了还是边界描述不清然后记录本周用户那些“本应触发技能的但没触发”的对话去补充触发条件。迭代的本质是让技能的描述跟上模型的能力更新。大模型升级后对某些表述的理解可能会变化以前能精确触发的条件可能就失效了。所以我会在模型大版本更新后做一次回归测试确认技能库没有退化。结尾最后再分享一个小技巧做Agent Skills这么久我发现一个让技能调用率明显提升的小技巧在每个SKILL.md的触发场景里除了写“当用户提到XX时”可以再加一句“如果用户输入中包含‘分析’、‘检查’、‘评估’这些动作词且上下文涉及CSV数据也可以考虑使用本技能”。这个补充让模型从“关键词匹配”升级为“语义理解”触发准确率能提升30%以上。另一个实用的个人经验是不要把SKILL.md写得像一套冰冷的API文档多加入一些“为什么这么做”的解释。比如“先检测文件编码再读取目的是避免中文乱码”这种说明帮助模型在面对新的意外情况时能从原理层面做出正确判断。毕竟你无法给模型列出未来可能遇到的所有情况但你可以让它理解你的设计意图它就能帮你应对那些你不知道会发生的事。技能库这种东西建起来不难养起来才是功夫。希望这篇文章能帮你在Agent开发这条路上少踩几个坑让你的模型真正变得“能干起活来”。