Agent Skills开发实战：从零构建可复用的AI技能包

我最近在重新整理手上的AI编程工作流发现一个绕不开的名字agent-skills。这东西在Claude Code、Codex、OpenCode这些工具里越来越常见而且你要是关注AI Agent开发这几天大概率也被“Skills”“superpower skills”“pi agent”这些词刷屏了。简单说Skills就是给Agent准备的“岗位说明书操作手册工具包”解决的问题很明确让AI助手在特定场景下不再靠临场发挥而是按一套固定但可定制的高质量流程干活。这篇文章不打算写什么宏大叙事就是把我自己从零到一开发、安装、测评、改造Skills的全过程摊开讲。适合哪类人看一类是正在用Cursor、Claude Code、Codex写代码但总觉得模型“时灵时不灵”的开发者另一类是想系统入局AI Agent开发、但不知道从哪下手的同学。你不需要有很深的机器学习背景只要写过一点脚本、用过命令行就能跟着做出自己的第一个技能包。1. 从Agent到Skills为什么“技能包”成了刚需1.1 我为什么开始折腾Skills先说说我自己的痛点。之前用Claude Code做项目重构每次让它“检查一下代码质量”或者“帮我按项目规范生成提交信息”它都能做但每次做的风格都不一样。今天给我输出英文注释明天给我改成中文注释今天建议加日志明天把日志全删了。后来我意识到问题不在模型能力在于我没有给模型一套“稳定操作规范”。Skills的学名在很多文档里叫“Agent Skills”本质上是把一段提示词、若干脚本、参考资料、约定流程打包成一个文件夹挂在Agent的工作目录下。当模型遇到匹配的任务时会自动读取这个技能包里的指令和工具照着里面的流程走。这样一来模型的行为从“自由发挥”变成了“按规范执行”稳定性和质量都上来了。我入坑之后发现不止我一个人在折腾这玩意儿。社区里已经冒出了大量第三方的Skill库比如按热度搜索“superpower skills”能找到打包了上百个场景技能的合集还有“pi agent”“hermes agent”这类开源智能体项目干脆把Skills作为内置功能设计进去。这说明Skill大概率不是某个工具的临时功能而是Agent落地时的一个基础单元。1.2 Skills不是Function Call也不是MCP很多初学者会把Skills、Function Calling、MCP混在一起。我当初也绕了好一阵后来用一句话打通了Function Call是模型请求调用某个函数MCP是给模型提供外部工具和数据的标准化管道而Skill是“工具指令参考文档”的完整工作流。打个比方Function Call是给了模型一个电话它能拨号MCP是给了模型通信录和电话线能接入外部世界而Skill是给模型配了一个“职业培训手册”告诉它你遇到什么样的情况、用什么话术、走什么流程、出什么结果。实际用下来三者是互补关系Skill里可以写提示词也可以在scripts目录里写脚本还可以通过MCP调用外部数据服务。这个区别直接决定了设计思路如果你只是让Agent做一次简单的函数查询用Function Call就够了如果要做复杂业务对接选MCP更合适但你希望Agent稳定完成一类重复性工作比如“代码审查”“latex排版”“周报生成”最合适的就是做成Skill。1.3 Skill和Agent到底有什么区别“skill和agent的区别”是我看到的高频搜索词必须单独说清楚。Agent是一个完整的、目标驱动的自主系统它对一个目标负责能自己拆解任务、规划步骤、调用多个工具、甚至跨多轮对话执行。Skill则是Agent手里的一个“能力卡片”它只负责一类具体事情怎么做不关心总体目标怎么拆。这就好比Agent是一家公司的项目经理Skill是项目组里的专业工程师。项目经理决定项目怎么推进但具体“代码怎么审查”“论文格式怎么排版”得靠专业工程师来干。所以你会看到像pi agent、hermes agent这类项目会把Skills作为插件化的能力层用Agent做决策和协调用Skills做专业执行。理解了这一层再看那些Agent框架文档就不会晕。2. Skills设计先搞清楚一个技能包里该放什么2.1 一份Skill的标准结构如果你看过Claude Code的官方文档会发现一个Skill的标准结构大概是这样的my-skill/ ├── SKILL.md # 技能的核心指令必填 ├── scripts/ # 可执行脚本模型会调用 ├── references/ # 参考资料、规范文档、示例 │ ├── best-practices.md │ └── examples/ └── assets/ # 图片、模板文件等资源看到这个结构先不用急着背它的设计逻辑很直白SKILL.md负责“告诉模型怎么思考”scripts负责“告诉模型怎么动手”references负责“给模型提供知识背景”。三者都有技能才完整。我见过不少人只写一个SKILL.md把所有操作步骤和话术全堆在提示词里。这种做法不是不行但很快会遇到一个痛点提示词越长模型越容易抓不住重点而且无法执行真正的“操作”只能凭空推理。把计算、文件读取、代码扫描这类任务交给脚本去做再把结果交给模型判断既准确又省Token。2.2 SKILL.md怎么写才不会被模型忽略SKILL.md是这个技能包的灵魂但它不是普通的Markdown文档。我踩过的坑是一开始把它写成了一篇“技术方案”堆了一堆背景介绍结果模型经常读不完就执行或者压根不触发。后来我调整了写法核心就靠两个东西一个是YAML格式的frontmatter一个是开头几百字的“操作说明”。--- name: code-review description: 用于代码审查。当用户要求检查代码质量、查找潜在Bug、评估提交内容时使用本技能。 --- # 代码审查技能 ## 你的任务 对本地的代码变更进行系统性审查输出结构化的审查报告。 ## 操作步骤 1. 先运行 python3 scripts/extract_diff.py 获取变更内容 2. 结合 references/ 下的审查规范逐条检查 3. 按模板输出报告 ## 红线 - 不修改任何源码文件只输出报告 - 报告必须包含“严重问题”“改进建议”“可读性反馈”三个板块这里最关键的是description字段。模型并不会在每次对话时都加载你的完整SKILL.md它通常只加载技能名称和描述等判断出“当前任务和描述匹配”时才把完整内容拉进来。你可以把description理解成“技能的关键字索引”写得越具体、越贴近用户真实需求命中率越高。2.3 命名与触发设计降低模型的调用成本命名这件事看起来不起眼其实直接影响触发率。技能目录名要清晰不要用“utils”“toolbox”这种云里雾里的名字。我自己的习惯是用“动作-对象”的格式比如code-review、latex-format、weekly-report这样模型一看名字就能猜到用途。触发条件设计也有讲究。太窄了模型遇到边缘情况时不会调用比如description里只写“当用户要求代码审查时”结果用户说“帮我看看这段代码有没有问题”模型可能就当成普通问答而不会触发技能。太宽了也不行啥任务都往这个技能上靠反而输出一堆不相关内容。我建议在description里列出至少三到五种用户常见的表达方式比如“审查代码”“检查Bug”“评估代码质量”“帮我过一遍commit的改动”这样触发率会高很多。2.4 参数定义把选择权交给模型把约束留给自己Skills里也可以定义参数但用法和普通函数参数不太一样。普通函数要求调用方必须传指定参数而Skill的参数更像是“给模型的可选建议”让模型根据实际情况灵活调整。我用过一个失败的技能里面设计了十几个参数又要求模型每次都必须填全。结果模型经常为了填参数而编内容反而忽略了核心任务。后来我改成只保留两三个影响输出的关键参数比如输出语言、审查深度、是否包含性能分析其它全部写成“不指定时由模型自行判断”。这样模型有了自由度输出质量反而更高。这背后的道理是模型不是死板执行参数的机器它具备一定的上下文理解能力。你给它的参数越多它需要做的“决策”也越多出现幻觉和错误的概率就越大。所以在Skill里参数要少而精流程要清晰而直接。3. 实操从零开发一个可复用的代码审查Skills3.1 项目结构搭建直接上个完整的实战案例。我平时最常用、也最推荐新手练手的技能是“代码审查”。一方面它贴近日常开发另一方面它涉及“脚本指令参考资料”三个部分正好把Skill的关键点全覆盖了。先建目录mkdir -p code-review-skill/{scripts,references} cd code-review-skill建完后我们需要三个文件SKILL.md用来定义行为scripts/extract_diff.py用来提取代码变更信息references/best-practices.md用来存放审查规范。3.2 SKILL.md内容详解下面是这个技能的核心指令文件我加了注释方便理解。--- name: code-review description: 对本地代码变更进行系统性审查。当用户要求代码审查、检查Bug、评估提交内容时使用本技能。 --- # 代码审查技能 ## 身份 你是一名资深代码审查工程师关注代码正确性、安全性和可维护性。 ## 操作流程 1. 运行 python3 scripts/extract_diff.py获取当前工作区相对于最近一次提交的变更内容。 2. 如果变更内容为空直接输出“没有检测到代码变更”然后停止。 3. 对照 references/best-practices.md 里的审查规范逐项检查变更内容。 4. 输出审查报告格式见“报告模板”。 ## 报告模板 ### 概览 - 审查范围涉及的文件与行数 - 整体评价一句总结性判断 ### 严重问题 列出可能导致Bug、安全漏洞、性能问题的点每条注明文件和行号。 ### 改进建议 列出结构、命名、可维护性相关的建议每条注明理由。 ### 可读性反馈 对注释、命名、函数长度给出简短反馈。 ## 红线 - 不修改任何源码文件。 - 只审查变更内容不要跑到无关文件里去“挑刺”。这里我刻意把“身份”这个字段写在靠前的位置。实际测试下来给模型一个明确的角色定位比直接扔流程更管用。它会影响模型整个输出的语气和关注点审查结果更接近“资深工程师”而非“普通问答助手”。3.3 脚本开发的几个关键细节下面是脚本部分。我选择Python来写是因为跨平台性最好Claude Code和Codex的沙箱环境里基本都能直接跑。#!/usr/bin/env python3 import subprocess import sys def get_diff(): 获取工作区相对HEAD的变更内容 result subprocess.run( [git, diff, HEAD, --, *.py, *.js, *.ts, *.tsx], capture_outputTrue, textTrue, encodingutf-8, errorsreplace ) if result.returncode ! 0: print(无法读取Git变更请确认当前目录是一个Git仓库。) sys.exit(1) if not result.stdout.strip(): print(没有检测到代码变更。) return print(result.stdout) if __name__ __main__: get_diff()这个脚本做了一件很简单的事情提取Git工作区中代码文件的变更内容。真正复杂的内容都交给了模型分析脚本只承担“数据采集”的职责。这个分工我强烈建议你记住——SKILL.md里的脚本不要想着做成“全能分析器”它只需要帮你拿到模型需要的原始数据就够了。3.4 多语言模板与依赖管理上面脚本只过滤了py、js、ts三类文件这在真实项目里不太够用。我后来改成可配置的方案在SKILL.md里让模型根据项目特点自动调整过滤范围。更通用一点的做法是在脚本里增加一个可选参数import argparse parser argparse.ArgumentParser() parser.add_argument(--ext, default*.py,*.js,*.ts,*.tsx, help用逗号分隔的扩展名模式) args parser.parse_args() ext_list [e.strip() for e in args.ext.split(,)]这个改动虽然小但效果很明显。模型可以结合项目具体情况灵活选择要审查哪些类型的文件而不是被写死的扩展名捆住手脚。依赖管理方面我的原则是能用标准库就用标准库尽量不要引入第三方依赖。有些技能的scripts需要安装一堆Python包模型跑在沙箱环境里很可能因为依赖装不上直接报错反而把整个流程卡死。如果确实需要复杂依赖有两个替代思路一是把逻辑放到需求方本地环境执行二是用模型自带的代码能力现场生成临时脚本。3.5 在Claude Code里安装并使用技能写好了接下来就是安装和调用。不同框架的安装位置不一样我在Claude Code里最常用的做法是把技能放在项目的.claude/skills/目录下或者放在全局的~/.claude/skills/目录下。# 在当前项目启用该技能 mkdir -p .claude/skills cp -r code-review-skill .claude/skills/ # 检查技能是否被识别 claude进入交互界面后直接输入“帮我审查一下当前代码变更”。如果技能被正确触发你会看到模型先执行脚本提取变更然后参考规范输出报告。这里有个小技巧在Claude Code里输入/skills命令可以查看所有已加载的技能列表方便排查技能有没有被识别。3.6 在Codex和OpenCode里复用同一份SkillsClaude Code能用Skills不代表其它工具也可以用。我实际测试过Codex对Skills的支持也在快速跟进但目录约定略有不同。把同样的技能复制到Codex的配置目录下即可mkdir -p ~/.codex/skills cp -r code-review-skill ~/.codex/skills/OpenCode的加载机制类似一般是读取项目根目录下的.opencode/skills。我建议你在写完技能后先在本地建一个“技能分发目录”把技能包复制给不同工具时只改目录路径就行技能内部结构保持完全一致。这样同一份技能可以在多个Agent里复用不用重复开发。4. Skill的获取、安装与二次改造4.1 常见的Skills来源刚上手时完全从零开发效率太低我建议先去社区找现成的技能包跑通了再动手改。常用的来源有这么几个来源说明适合场景anthropics/skills官方维护的示例技能库质量高风格规范学习SKILL.md的标准写法awesome-claude-skills社区聚合仓库收录大量第三方技能按关键词搜索现成技能superpower skills打包了上百种技能的合集类项目一次性体验各类技能效果各大AI编程工具的插件市场Claude Code、Codex、OpenCode都支持插件与其主框架集成最紧密渠道不在多关键是会挑。我的经验是先看SKILL.md里的description写得好不好再看scripts里依赖重不重。如果description写得很模糊、scripts又依赖一大堆环境这种技能包大概率不好用。4.2 superpower skills这类大包值不值的装“superpower skills”的热度确实很高它是社区里一个大型技能合集主打“渐进式提示”理念把技能分类组织好按需加载。我自己也下载试用过感受是安装很爽用起来需要门槛。大合集的优点是覆盖面广几乎你能想到的场景都有对应技能缺点是启动和检索成本变高模型在每次会话里要扫描的技能列表更长反而可能出现“技能覆盖偏差”即真正需要的技能没触发不相关的技能挤占了上下文。所以我现在的习惯是把大合集下载下来当作“技能素材库”用到哪个功能就把对应技能包单独抽出来放进当前项目而不是一股脑全挂上。4.3 改别人的技能包三条经验改造别人技能包比自己写还容易踩坑我总结三条经验。第一先跑通再改逻辑。不管原技能描述得多牛先放到测试目录里实际跑一遍确认它能出结果再动刀。不要一上来就改提示词结果问题出在脚本上排查起来特别费劲。第二改description时要同步改目录名。很多人的技能包名字和description不一致比如目录叫code-reviewdescription里却写着“检查代码风格”模型触发时容易困惑。保持两者一致能显著提高触发准确率。第三警惕“幽灵依赖”。有些技能包在SKILL.md里写着运行某个脚本但脚本引用的工具或库并没有写清楚。遇到这种情况要么补齐依赖说明要么把相关逻辑重写为纯Python标准库。否则换个机器就崩根本没法用。5. 怎么评价一个Skill好不好用5.1 功能性测试跑通主路径技能做出来不是给自己看的是要给模型实际调用的。所以第一步测试要看“主路径”能不能走通用户提出一个典型请求模型能否正确触发技能技能能否给出合格结果。我测试代码审查技能时会在一个故意写了几处Bug的测试仓库里运行查看模型是否发现这些问题。如果技能连主路径都跑不通后面的优化都无从谈起。这里有个简单的做法设计3到5个“标准测试任务”每次改完技能都跑一遍保证基本功能不退化。5.2 稳定性测试同一任务跑三次大模型的随机性决定了同一个任务跑多次可能给出不同结果。稳定性评估就是看技能能不能“保持一致地输出质量”。我的方法是同一任务连跑三次比较结果差异。如果三次结果差异非常大问题多半出在SKILL.md——指令描述不够具体给模型的自由度过大。对应的解法是细化流程增加“必须包含的板块”或“必须输出的关键字段”。如果三次结果都稳定但质量都很差那问题可能出在脚本或参考文档上需要换一种思路重新整理数据或规范。5.3 可迁移性测试换个仓库试试一个技能只在自己熟悉的项目里能用不算好技能。我建议在不同语言、不同规模的项目上分别测试同一个技能。拿代码审查技能举例在Python项目上能用那Java或Go项目行不行在小仓库里能用面对几千个文件的大仓库会不会超时可迁移性测试往往能暴露脚本中的硬编码问题。比如我之前写的脚本只处理了*.py文件换到JS项目就完全失效。后来我改成可传参的扩展名匹配这个问题才解决。5.4 副作用测试会不会把项目搞乱最容易被忽视的是副作用测试。Agent技能在运行时可能会创建临时文件、修改配置、安装依赖这些行为一旦失控就是在用户的项目里“埋雷”。我的习惯是测试前记录一下git状态技能跑完后再用git status检查工作区有没有意外的改动。一个规范的技能应该做到要么不修改任何项目文件要么明确声明“本技能会修改哪些文件”。这与“不轻易让Agent改动用户数据”的原则是一致的安全意识。6. 开发过程中踩过的坑6.1 提示词“太长不看”第一次写SKILL.md我恨不得把毕生所学都写进去结果钻了一个大坑模型读不进去。后来我发现SKILL.md超过一定长度后模型会选择性忽略后半部分尤其是那些藏在末尾的操作步骤。解决办法有两个一是把核心流程压缩到文件开头两三百字内确保模型一眼就能看到操作步骤二是把大段参考资料移到references目录里让模型用时再查而不是堆在主指令里。一句话总结SKILL.md要薄references可以厚。6.2 工具脚本与模型脱节我一开始把很多判断逻辑写进了脚本比如让脚本自动计算代码复杂度、自动分类问题类型。结果模型拿到的是一大堆散乱数据反而不知道该从哪里入手分析。后来我把脚本简化成“提取变更内容”把判断和分类全部交给模型。这里面的原则是机械的事情交给脚本聪明的事情交给模型各干各的擅长。6.3 “幽灵调用”问题很多技能看起来写得不错但实际触发率很低我管这叫“幽灵调用”模型表面上加载了技能实际操作时却完全没按技能里的流程走。排查后发现问题多半出在description的“命中词”太少或者任务描述与技能描述之间的表达差异太大。解决方法是收集用户在真实场景下的说法把高频表达直接写进description。比如用户常说的“帮我看看这次提交改动大不大”也要体现在触发条件里。这本质上和SEO关键词优化是同一个思路让技能在正确的时刻被正确地找到。6.4 多框架兼容的坑同一份Skills在不同框架里的表现可能差异很大。同一个代码审查技能在Claude Code里跑得丝滑换到Codex里可能就出现格式混乱、脚本报错。原因之一是不同框架对SKILL.md结构的解析规则略有差异另一个是沙箱环境里预装软件不同。我的建议是如果你的技能要在多个框架里用一定要先在各框架的官方文档里确认目录规则和编写规范并分别在各自环境里做一遍主路径测试。不要想当然认为“一个技术文件夹到处能跑”。6.5 钩子与定时清理稍微进阶一点的用法是给Skill配置钩子hooks让它在特定时机自动执行。比如代码审查技能可以在用户执行提交操作前自动运行。但钩子用不好同样出问题我试过给技能配置一个文件清理钩子结果把测试环境里重要的临时文件误删了。所以钩子逻辑必须加白名单或备份机制宁可不清理也不能误伤。7. Agent开发学习路线与延伸思考7.1 从Skills到Agent还有多远如果你看完前面的内容已经能独立开发一个Skill了那么恭喜你Agent开发的路你已经走完了三分之一。因为Agent开发最核心的不是框架选型而是能力拆解把一个目标分解成若干技能再把技能实现成可调用的模块。这个过程和写大型软件的“模块化”思路一脉相承。下一步建议系统学习Agent编排框架。目前主流的框架都有良好的Skill集成能力理解它们的事件循环、状态管理和工具调用机制可以把多个Skill编排成更复杂的Agent工作流。常见的入门路径是掌握Prompt基础理解Function Calling学会独立开发Skills最后学习Agent编排框架并搭建完整项目。7.2 评估驱动开发建立自己的测试集我在测评部分反复强调“设计标准测试任务”这个习惯放到整个Agent开发学习路线里同样适用。你可以给自己建一个简单的“评估集”里面放几十条典型任务每次改完代码都跑一遍看效果。这个做法在Agent开发里叫“evals”看起来高大上本质就是给AI行为建立回归测试。我见过不少开发者花了大量时间在框架调参上但对效果的判断全靠“感觉”。这样做开发节奏会越走越偏。有了自己的评估集你会清楚地知道每次改动是变好了还是变差了也会慢慢积累出哪些策略有效、哪些无效。7.3 后续还可以往哪些方向扩展Skills这个方向后续还有很多可以玩的空间。比如加一层记忆机制让技能能记住用户偏好再比如引入外部知识库让技能在专业领域里回答得更精准还可以把多个技能组织成“阶梯式技能”让一个技能调用另一个技能实现更复杂的工作流程。我现在正在做的是把常用的十几个技能统一到一个私有仓库里配上版本管理和自动同步脚本换机器时一条命令就能全部安装到位。这个方案后期也可以把团队共同的规范沉淀成技能模板做到新项目开箱即用。再分享一个小技巧收尾每次写完一个Skill记得留一份运行截图或输出样例放进references的examples目录里。这不仅是给模型提供参考输出格式更是你日后回看和复盘时最直观的资料。开发Skill最忌讳闭门造车多拿实际项目磨多给自己的技能做“回归测试”比看任何教程都管用。