Agent Skills 这个概念最近讨论热度很高但很多人还是把它当成普通 Prompt 的升级版或者跟 AI Agent 混在一起谈。我先把结论放在前面Agent Skills 本质上是给 AI Agent 准备的一套“标准作业流程 工具脚本”让 AI 不再只凭一句提示词自由发挥而是按你规定的步骤、格式和工具去完成一类明确任务。这篇内容会从入门到精通拆开讲先说明 Agent Skills 和 Prompt、AI Agent、AI Skills 的区别再讲怎么安装现成技能、怎么自己写一个技能最后落到真实工作流里的批量处理和论文写作场景。适合刚开始接触 Claude Skills又不想只停留在聊天窗口里的人。最值得关注的一点是Skills 不是魔法而是一套可维护、可复用、可排错的工作流封装。理解这一点比记住任何一条安装命令都重要。1. Agent Skills 到底是什么和普通 Prompt 有什么区别很多人第一次看到 Skills 这个词会以为它只是“写得更详细的提示词”。其实差别很大。普通 Prompt 是即时生效的一段指令AI 读完按自己的理解执行结果好不好不稳定。Skills 则是一套预先封装好的能力它有使用说明有步骤有脚本有输入输出格式甚至还有失败处理逻辑。AI 调用它不是重新思考怎么做而是按你已经定义好的流程走。1.1 从“告诉 AI 做什么”到“给 AI 一套完整操作流程”打个比方。普通 Prompt 就像你临时跟新员工说“帮我把资料整理一下。”新员工听完可能按自己想法做格式对不对、字段全不全完全看运气。Skills 则是你给新员工一本操作手册里面写着资料从哪里拿、分包成几步、每步用什么工具、输出文件必须包含哪些字段、遇到错误先记录再重试。员工只需要执行不需要每次重新设计流程。落到工具上Agent Skills 通常由一个技能描述文件、若干脚本、模板和参数定义组成。AI Agent 在收到任务时会先读取能力目录判断哪个技能适合当前任务然后按照技能描述加载相关脚本一步步执行。这个过程的优势在于同一套流程可以被反复调用输出格式更稳定出现问题时也更容易定位是哪一步出的错。1.2 AI Skills 和 Agent 的区别为什么不能混为一谈现在有很多说法比如“AI Skills”和“Agent”。看着像实际上是两个层次的东西。Agent 是执行主体它负责理解任务、拆解步骤、决定先调哪个工具、后调哪个工具是一个决策器和调度器。Skills 则是 Agent 手里可以拿出来的能力包是一格格已经封装好的功能单元。可以这样理解Agent 像项目经理Skills 像工具箱里的专用工具。项目经理负责判断当前项目该用哪个工具、用什么顺序组合工具工具本身不会自己决定项目目标也不会主动更换施工顺序。一个 Agent 可以同时挂多个 Skills一个 Skills 也可以被不同 Agent 复用。所以在学习时不要先纠结“我要不要用 Skills 替代 Agent”。它们不是替代关系而是配合关系。真正值得关心的是你的 Agent 当前缺少哪些固定能力这些能力是否适合封装成 Skills以及封装之后能否稳定复用。1.3 一套 Skills 通常由哪些部分构成虽然不同工具的细节不一样但成熟的 Skills 一般包含这几个部分组件作用说明技能主文件告诉模型何时调用、怎么调用、输出格式通常是 SKILL.md是技能的核心说明脚本或命令执行真正的机械操作Python、Shell、Node 等完成数据清洗、文件处理等模板或资源固定输出的底稿文档模板、表格模板、术语表、参考示例参数定义约定输入输出结构输入文件路径、输出目录、语言、格式、必填项日志与测试用例验证技能是否可靠记录每次运行情况用于问题排查一个技能如果只有说明文件没有实际可执行的脚本那它其实更像“知识包”。知识包有价值但它不是真正的技能。反过来只有脚本没有说明文件Agent 就不知道什么时候该用这个脚本也没法判断输入参数怎么传。真正好用的 Skills必须让“模型能读懂说明”和“脚本能执行动作”连成一条完整链路。2. 先用起来如何安装和调用别人写好的 Skills自己写技能之前建议先在现有环境里装几个成熟技能跑一遍。这样能直观体会到“技能生效”和“技能没生效”之间的差别。很多人搜“好用的 claude code skills 安装”或者“claude code skills 推荐”其实并不是缺一份清单而是不知道装完怎么验证。这一节把安装路径和验证方法讲清楚。2.1 运行环境与前置条件Agent Skills 的运行环境不算苛刻但也不是直接打开一个聊天窗口就能跑。它依赖的是 Agent 工具本身而不是依赖 GPU 算力。技能里的脚本负责处理本地文件、清理数据、拼接内容这些操作主要消耗 CPU、内存和磁盘读写。真正的大模型推理还是在远端或本地的模型服务里完成。第一次使用前建议先确认这几个条件当前使用的 Claude 相关工具版本是否支持 Skills 机制。当前账号是否有权限读写技能目录。技能里用到的 Python、Node、Shell 命令是否存在。工作目录是否有写权限尤其是输出文件目录。如果是公司电脑还要看安全策略是否允许执行本地脚本。低配置环境也能跑但要做好心理准备单条任务可以批量并行不一定稳定。不要因为单个技能跑通了就想当然地认为大并发也没问题。2.2 常见安装方式和目录规范从主流工具的使用习惯来看Skills 一般是以文件夹形式放进指定目录。以常见约定为例目录结构可能是这样skills/ ├── my-first-skill/ │ ├── SKILL.md │ └── scripts/ │ └── run.py └── another-skill/ ├── SKILL.md └── assets/不同工具对目录命名和存放位置的叫法不一样。有的放在用户配置目录下有的放在项目目录下还有的需要在配置文件中手动声明。安装前最好先看工具本身的说明或者用一条最小测试技能验证目录是否被正确加载。这一步最容易踩的坑是路径问题。Windows、macOS、Linux 的隐藏目录和权限规则不一样中文用户名和特殊字符也可能导致路径解析异常。如果你发现技能已经放好但模型就是调不起来先检查路径再检查权限。2.3 怎么判断它真的生效了安装完不能只看文件在不在要以“Agent 能不能主动调用”为准。验证顺序建议这样来在对话里输入一句明确需要技能处理的话比如“请用 doc-formatter 技能整理下面这段笔记”。看模型是否回复“我会调用 xx 技能”或者出现技能加载的日志。看脚本是否有实际执行记录比如终端输出、文件生成、日志变化。检查输出结果是否符合技能描述里约定的格式。如果模型只是把技能描述复述了一遍但没有任何脚本执行痕迹那通常意味着技能没有被正确加载或者调用方式不对。此时不要急着调提示词先确认技能目录和技能名是否匹配。2.4 现成 Skills 推荐看什么搜索“claude code skills 推荐”时不要只看谁列表长、谁 star 多。重点看三个信息输入格式是否清晰、输出是否固定、是否依赖外部网络和密钥。一个适合新手的技能应该具备这些特征输入明确、不依赖敏感信息、单次运行成本低、输出结果容易检查。比较适合先尝试的方向包括笔记和文档结构化整理。代码批量格式化和静态检查。Markdown 表格转换。文件批量重命名。日志切片和错误信息提取。论文参考文献格式辅助整理。这些场景的共同点是规则稳定、可重复、容易验证。等你在这些场景里跑顺了一个技能再去看更复杂的实战技能会比较淡定。3. 自己造第一个 Skills从需求定义到跑通从“会用”到“会造”最关键的变化不是会写代码而是会定义流程。很多人第一次写技能时上来就写脚本结果脚本很复杂但模型根本不知道什么时候该调用。正确顺序应该是先想清楚任务边界再写技能说明最后才写脚本。3.1 技能边界与输入输出定义写任何技能之前先回答这六个问题技能名称是什么用一个动词短语让模型一眼看明白。输入是什么是用户粘贴的文本还是文件路径还是结构化数据。输出是什么是返回给用户的文本还是生成文件还是调用外部 API。适用条件是什么什么情况下模型应该调用这个技能。不适用条件是什么什么情况下不要调用避免误用。失败时需要做什么是报错停止还是记录日志继续。一个技能只做一件事。如果一件事里有多个环节可以把环节拆成多个技能再让 Agent 通过编排把它们组合起来。比如“把会议纪要转成周报”至少可以拆成“会议纪要素提取”和“周报模板填充”两个技能。拆开之后每个技能都更容易维护和测试。3.2 技能目录与主文件结构以一个简单的“文档格式化”技能为例目录可以这样设计doc-formatter/ ├── SKILL.md ├── scripts/ │ └── format_to_markdown.py └── assets/ └── output_template.mdSKILL.md 是技能主文件负责让模型看懂。不要把它写成代码注释要写成使用说明书。一个通用示例--- name: doc-formatter description: 将杂乱纯文本整理成规范 Markdown 列表结构。 when_to_use: 用户需要对笔记、会议记录、日志片段做结构化整理时。 --- # 使用步骤 1. 读取输入文本先按空行拆成段落。 2. 将每段关键信息转成二级标题或有序列表。 3. 调用 scripts/format_to_markdown.py 处理文本。 4. 输出结果给用户并用一句话说明整理规则。这个示例不是官方 API只是说明技能说明文档应该包含哪些信息。真正落地时你需要根据自己使用的工具调整字段和执行方式。3.3 脚本要小、要稳、要能独立运行技能里的脚本不要追求花哨优先使用标准库减少第三方依赖。因为每次调用技能时环境未必有你安装的依赖。下面这个脚本只是为了展示思路不一定是某个工具的标准接口import sys def main(): raw sys.stdin.read() lines [line.strip() for line in raw.splitlines() if line.strip()] print(# 整理结果\n) for i, line in enumerate(lines, 1): print(f{i}. {line}) if __name__ __main__: main()脚本本身不是重点重点是数据流模型读取用户输入把文本传给脚本脚本处理完把结果返回给模型。如果这个链路里有任何一环断了要么是参数没传对要么是脚本没有按约定读取数据。写脚本时还要考虑空输入。脚本遇到空文本不能直接崩溃至少要输出一句“未检测到有效内容”。否则模型拿到一堆异常日志也不知道该怎么处理。3.4 造技能时最容易踩的坑第一次造技能有几类问题几乎是必踩的路径写死。技能在别人电脑或服务器上跑时绝对路径可能不存在。脚本处理不了空输入。输入只有一行、输入为空、输入带 BOM 编码都可能让脚本崩溃。技能描述太泛。比如只写“可以辅助处理文本”模型就会犹豫到底该不该调用。没有给出输出示例。模型不知道结果长什么样才是对的。依赖没有记录。换台机器跑脚本 import 报错。建议第一个技能不要做太复杂。选一个你每天都要做的重复动作比如“把剪贴板里的文本转成 Markdown 列表”“把 CSV 文件按字段拆分”。跑通之后再慢慢往里面加规则和异常处理。4. 把 Skills 真正嵌进工作流而不是当玩具很多人装了一堆技能最后只在测试时用一下。真正让技能发挥价值的关键是把它放在一个会反复出现的工作流里。任务类型不同使用方法也不同。4.1 单任务场景先跑稳再说单任务场景最简单但也是最重要的验证环节。选定一个技能后拿最小样例测一遍一个输入文件、一段文本、一次输出。看三件事模型是否知道调用技能。技能脚本是否顺利执行。输出结果是否是你想要的结构。这一步不要追求速度。如果单条任务都没跑顺后面所有批量或者接口化都是浪费。4.2 批量任务要考虑队列、命名和失败重试技能能跑通单条任务不代表可以直接处理批量任务。批量场景需要额外设计输入列表从哪里来是读取目录下所有文件还是读取一个清单文件。输出命名规则避免覆盖原文件最好带上时间戳或序号。失败怎么办是跳过继续还是全部停止。日志怎么记录每次处理必须留下可追溯记录。批量任务的正确打开方式是先跑 3 到 5 条样本检查输出一致性和错误率确认没问题后再扩大范围。不要一上来就把并发开满。很多工具看着支持并行处理但低配机器一开并发就出现资源争抢结果反而是大面积失败。检查项单任务批量任务输入数量1几十到几百输出命名手动确认需要统一规则失败处理手动重试需要失败跳过和重试日志可有可无必须完整并发不必要需要控制峰值4.3 论文写作与混合研究方法场景最近讨论很多的一个场景是“Agent Skills 辅助人文社科混合研究方法论文写作”。我自己理解这个方向是成立的但要用对地方。混合研究方法通常包含定量和定性两条线流程复杂重复性步骤多恰恰适合用技能来做过程管理。可以交给技能处理的环节包括文献条目分类和去重。访谈文本的初步编码和主题聚类。问卷开放题回答的文本清洗。术语一致性检查。参考文献格式统一。图表和附录编号核对。这里要特别说一下技能可以做初步编码但不能替研究者做分析和判断。质性研究里的编码往往需要结合理论框架和语境AI 只能帮助你提高扫描效率不能代替你的学术判断。结论性内容必须由研究者自己完成否则方法论上会有很大风险。另外一个容易被忽略的点是人工介入点怎么设计。建议把技能设计成“分段输出人工确认”的流程技能先把文本分成若干段给出初步编码再让研究者逐段确认。这样既保留效率也保留研究的可追溯性。4.4 多文件、长文档、跨格式处理处理长文档时最容易出现上下文超出限制的问题。技能描述和输入文本都需要占用上下文空间。如果文档太长建议先拆分再处理最后合并。跨格式处理也有类似问题。比如一个技能要处理 CSV 文件和 Word 文档就不能假定所有文件结构都一样。先统一编码再统一字段名再处理数据。遇到异常行不要直接删除先收集到一个异常文件里便于事后检查。5. 评估一个 Skills 好不好用看哪些判断标准自己造技能或者选别人技能时不能只看“能不能跑通”。能跑通只是最基础的条件。真正决定技能长期价值的是输出稳定性和可维护性。5.1 从能用变好用一个能用的技能能处理理想输入一个好用的技能能处理不理想输入并且输出仍然稳定。具体可以看这几个标准输出完整性内容没有无故丢失。格式一致性连续调用多次输出结构和风格保持一致。重复性同样输入得到的结果差异不大而不是每次随机发挥。失败可恢复遇到异常时能给出明确提示而不是直接中断。如果技能输出经常出现缺字段、顺序错乱、格式跳跃那说明技能描述里的步骤还不够清晰或者脚本对输入兼容性不够。不要通过反复修改提示词来碰运气要回到 SKILL.md 和脚本本身去找问题。5.2 性能和资源消耗技能脚本也会占用资源。判断一个技能是否适合日常工作流可以记录这些数据单次任务耗时。输入文件大小和耗时关系。内存和 CPU 占用情况。批量任务失败率。日志是否足够定位问题。低配置机器可以跑通单任务但需要把批量数量和并发降下来。一个合理的策略是先以 5 条数据为批次跑完看日志和耗时再决定要不要扩大批次。临时文件也要及时清理否则连续跑几十个任务磁盘写满之后会出现奇怪报错。5.3 什么时候不适合用 SkillsSkills 不是所有场景的最优解。遇到下面这些情况不要硬造技能一次性的简单问答不需要固定流程。高度个人化的判断比如帮用户决定职业方向。需要长期多轮交流背景才能完成的任务。输入格式极端不稳定、每次都不一样。另外高敏感数据场景要特别谨慎。技能脚本会读取本地文件、执行命令如果脚本来源不可信或者第三方依赖存在风险不能直接放进生产环境。技能文件应该做代码审查特别是包含网络请求和系统命令的技能要确认它没有多余的行为。6. 常见坑和排查顺序最后讲几个高频问题。遇到技能相关故障第一反应不应该是改提示词而是按顺序排查先看现象再看输入再看环境再看脚本最后才回头看提示词。6.1 模型不按技能走怎么办表现是你明确提到技能名模型却还是用普通对话回答或者根本没加载技能日志。常见原因是技能描述里没有写清触发条件或者技能名称与目录名不一致。解决办法是在 SKILL.md 里加一句明确的调用条件比如“当输入包含会议纪要或原始笔记时应调用 doc-formatter 技能”。如果还不行就在用户指令里更明确地声明“请调用 doc-formatter 技能处理。”6.2 脚本报错但界面没提示脚本执行失败时很多工具不会把完整报错直接展示给用户。排查顺序应该是看运行日志有没有脚本调用记录。看输入文件是不是空文件、编码不对、路径不存在。看脚本权限是不是没有可执行权限。看依赖是不是缺少某个库。看脚本自身是不是对特殊字符或空输入没有处理。我见过很多“技能报错”最后定位下来不是技能写得有问题而是文件路径里带了一个空格脚本没有做转义。这种问题看日志比猜原因快得多。6.3 输出格式不对如果脚本执行成功但输出格式不对优先检查输入参数传递。模型的描述和脚本实际接收到的数据可能是两回事。比如模型以为自己在传文件内容脚本实际拿到的是文件路径。这种错位要靠日志里的参数信息来对齐。另外模板文件也可能有问题。如果输出模板放在 assets 目录要确认模板编码和脚本读取方式一致。Windows 下常见的 UTF-8 和 GBK 混用问题在打开旧文本时容易遇到。6.4 版本与平台差异技能目录和脚本命令在不同版本、不同操作系统之间可能不一样。写脚本时尽量遵守几个原则不使用绝对路径不在脚本里硬编码路径分隔符用跨平台的命令依赖环境变量时先检查再使用。不要因为你当前环境能跑就认为所有环境都能跑。我自己现在的习惯是每装一个新技能或写完一个新技能都会用一条固定的小样本做回归测试。技能一旦改动立刻重复跑一遍样本确认输出没有漂移。这种方法不需要复杂工具但对保持技能稳定性很有帮助。真正落地时我最先看的不是功能列表而是输入输出是否明确、日志是否清晰、单任务是否稳定。先把一个技能用在你每天都会遇到的重复任务上跑顺了再考虑扩展。Skills 的价值不在数量而在可维护和可复用。