不知道各位有没有这样的体会同一个模型在别人手里是高效的开发助手在自己手里却像个只会应答的工具人。差别在哪最近我在复盘自己的Agent工作流时答案越来越清晰——真正决定上限的不是你用什么模型、什么框架而是你给Agent配了哪些Skills。这个词最近在Claude Code、Codex、OpenCode这些圈子里的讨论度非常高。简单说Skills就是把一个领域的操作方法、模板、脚本打包成Agent能直接调用的能力模块。今天这篇我就想聊聊agent-skills它到底是什么、跟Agent本身有什么区别、怎么安装使用、怎么自己写一个以及我在实际使用中踩过的坑。1. Skills是什么为什么Agent越来越离不开它1.1 从Prompt到SkillsAgent能力封装方式的进化早期我们用AI编程方式是写一段很长的Prompt把规则、示例、约束全塞进去。这种方式有一个天然的问题Prompt越长模型越容易丢失重点而且改一次Prompt就要全部重来想跟别人共享能力更是麻烦。你复制一段锦囊给朋友对方还得手动改人名、改路径、改上下文。Skills的出现本质上把“一次性指令”升级成了“可复用、可分发、可自动触发的能力包”。一个Skill通常是一个目录里面有一个SKILL.md文件作为入口YAML frontmatter里写明技能名称、描述、适用场景正文部分写执行步骤、注意事项还可以附带Python/Shell脚本、模板文件、参考文档。Agent在运行时读取这个文件判断当前任务是否需要调用这个技能。这个设计很聪明。它把“教模型怎么做”和“给模型工具用”两件事合到了一起。以前你想让AI画一张架构图要么在对话里反复描述格式要求要么写好一段提示词每次粘贴现在你只需要装一个“结构图Skills”直接说“把系统架构画出来”Agent就会自己读取技能里的规范、调用脚本生成图表。对用户来说体验从“教它干活”变成了“它本来就会”。从生态角度看Skills还解决了知识分发的问题。以前一个人的提示词写得再好传播和复用都很麻烦现在一个Skills文件夹可以直接扔到GitHub上别人拉下来放到指定目录就能用。这也是为什么最近各种Skills合集、Skills推荐帖子特别火——因为它的分发成本实在太低了。1.2 Skill、Agent、Harness和Prompt到底有什么区别热词搜索里“skill和agent的区别”“harness和agent区别”是问得最多的两个问题。很多人被这一堆概念绕晕很正常。我自己刚接触的时候也花了很久才理清楚。用大白话讲Agent是那个干活的人它能感知输入、规划步骤、调用工具、给出结果。Harness是Agent跑起来的“运行环境加调度外壳”负责管理上下文、执行工具调用循环、控制权限。Skill是Agent的“技能包”给Agent注入某个具体领域的能力本质是结构化的指令加素材加脚本。Prompt是临时说的一句话每次都在上下文中占位置Skill则可以被索引、按需加载平时不占用对话上下文。打个比方Harness是厨房Agent是厨师Skill是菜谱和刀具工具箱Prompt是客人临时说的一句“少放辣”。厨师还是那个厨师但菜谱工具箱越全能做出来的菜就越丰富临时交代的事下次还得重新交代。实际开发中有个容易踩的坑很多人把Skill当Prompt写以为只要在SKILL.md里多写点规则就行。其实Skill真正的价值在于“结构化加可执行”。它不只是告诉Agent“你应该怎么做”还能给它配套脚本、模板、校验逻辑让它在执行时有东西可调用、有标准可对照。只有Prompt没有工具的Skill本质上还是在靠模型临场发挥。1.3 拆解一个完整的Skill内部结构与其空讲概念不如直接看一个完整的Skill长什么样。以热词里出现频率很高的“结构图Skills”为例这种技能专门用来生成架构图、流程图、拓扑图在写技术文档、做方案汇报时非常实用。一个典型的结构图Skills目录如下structure-chart-skill/ ├── SKILL.md ├── scripts/ │ ├── generate_mermaid.py │ └── validate_graph.py └── templates/ ├── architecture_template.mmd └── flow_template.drawioSKILL.md是入口里面用YAML frontmatter定义元信息正文定义执行流程。我一般会写成这样--- name: structure-chart description: 当用户需要架构图、流程图、拓扑图、时序图时使用。 该技能支持mermaid和drawio两种输出格式。 --- 1. 分析用户描述中的系统组件与调用关系。 2. 选择最合适的图类型架构图用flowchart时序图用sequenceDiagram。 3. 生成mermaid代码并用scripts/validate_graph.py做语法校验。 4. 输出mermaid源码与渲染预览必要时同时提供drawio XML。 5. 所有节点命名必须语义化不允许出现node1、node2这类无意义名称。注意看description这一行它是Agent判断“什么时候该用这个技能”的关键依据。这里有个很多人不知道的细节Agent不是把所有Skill都读进上下文而是先根据当前任务和每个Skill的description做语义匹配匹配上了才加载正文。所以description写得太泛Agent会犹豫要不要用写得太窄该用的时候又想不起来。最好把“什么场景触发”“支持什么输出格式”都写进去。scripts目录放的是可执行脚本generate_mermaid.py负责把结构化描述转成图表代码validate_graph.py负责做语法检查。templates目录则是常用模板Agent可以基于模板改参数不用每次从零生成。整套结构下来Agent拿到手的是一套完整的生产工具链而不是一句空泛的“你可以画图”。2. 主流Agent框架的Skills生态与选型思路2.1 Claude Code、Codex、OpenCode的Skills实现有什么不同现在几乎每个主流Agent框架都在做自己的Skills机制但实现方式各有差异。我先说Claude Code官方支持把Skills放在两个位置用户级目录~/.claude/skills/适用于所有项目项目级目录.claude/skills/只对当前仓库生效。这种“全局加局部”的设计很实用你把通用技能放在用户级把项目特定技能放在仓库里跟着代码库一起提交团队成员拉下来就能用。OpenAI Codex也支持类似的自定义能力不过它的配置方式更偏向通过配置文件定义Agent的行为和工具集Skills在其中更像“预设工作流”的组成部分。OpenCode作为开源社区里很活跃的终端AI编码助手Skills生态也发展得很快GitHub上已经有不少人分享自己的OpenCode Skills仓库。还有一些像Pi Agent、Hermes Agent这类开源Agent项目也在往Skills方向靠不过迭代比较快具体支持情况建议直接看官方文档。我用一张表把几个常见框架的特点列出来方便按需选型框架Skills机制主要特点适合场景Claude Code目录式SKILL.md支持全局/项目级生态成熟触发方式丰富日常编码、文档、运维脚本OpenAI Codex配置文件加自定义工作流与OpenAI模型集成紧密偏代码生成与重构OpenCode开源生态Skills仓库活跃社区化配置灵活喜欢自己折腾的开发者Hermes Agent开源Agent支持模块化扩展可定制程度高研究型项目、AI Agent开发我的建议是别贪多先选一个主力框架用熟把Skills的编写和调试流程跑通再横向对比其他的。工具换来换去最容易让人学不会。2.2 superpower skills这类合集包的正确打开方式热词里“superpower skills安装”热度很高。superpower skills是目前社区里很出名的Skills合集里面打包了几十个常用技能从代码审查到文档写作都有。很多人以为装了它就能一步到位结果装上之后发现Agent反而变“笨”了该调用的没调用不该调用的乱调用。问题往往出在“全量安装”。你想想一个对话里塞进几十个技能的元信息Agent每次做语义匹配都要跟几十个description比对决策成本上去了准确率自然下降。正确做法是把合集当成一个“技能超市”从里面按需挑选真正用得上的几个复制到自己的skills目录。安装方式也很简单核心就是拉取项目文件按需复制# 拉取合集仓库 git clone https://github.com/xxx/superpower-skills.git # 把需要的技能目录复制到Claude Code全局skills目录 cp -r superpower-skills/skills/code-review ~/.claude/skills/这套合集还附带自己的CLI工具可以通过npx启动用来管理技能的安装和更新。但说实话我更推荐手动复制。原因很简单手动复制让你清楚自己到底装了哪些东西出了问题也好排查全自动安装看着省事装完了你可能都不知道系统里多了什么。2.3 高频实战Skills推荐结构图、图片生成、LaTeX排版从热搜词来看大家最关心的实用型Skills集中在结构图、图片生成、LaTeX排版、前端开发这几个方向。这些确实是我日常使用频率最高的类型。结构图Skills前面已经说过适合所有需要输出图表的技术文档场景实测能大幅减少画图时间。图片生成Skills的本质是封装一个图像生成接口让Agent能根据文字描述直接调用模型生成图片并保存到本地这种Skills在配图、素材制作场景很管用安装时要注意确认脚本依赖的图像模型API Key是否已配置。LaTeX排版Skills则是学术党利器把Markdown或Word内容规范转换成LaTeX文档处理中文编译、图表交叉引用、参考文献格式用好了能让排版效率翻倍。前端开发Skills也是高频需求。一套好的前端Skills会包含组件规范、代码风格约束、项目结构说明Agent生成代码时会自动遵循团队约定而不是每次都要临时说“用TypeScript写、组件放src/components下”。这种“把团队规范做成Skill”的做法我特别推荐有前端团队的人尝试。除了这几个我还建议自己组装一个“文档整理Skills”包含日期格式、标题规范、图片存放路径等约束。这个技能不复杂但能明显减少文档返工率。2.4 用一个可复用的评测流程判断Skills好坏热词里有“skills怎么测评”说明大家已经不满足于“装了就完事”还想知道哪个更靠谱。这确实是个好问题。我现在的做法是建一套简单的评测流程每次拿到新Skills都先过一遍再决定要不要放到主力环境。我的评测方法分四步固定输入样本准备3到5个该技能最典型的任务描述最好覆盖简单、中等、复杂三种难度。跑通过率每个任务执行3次看能不能正常跑到流程结束记录报错情况。检查稳定性同一任务多次执行看输出质量是否稳定有没有时好时坏的情况。观察上下文占用通过日志看Skill加载时消耗了多少token占用过高的技能要谨慎使用。举一个实际例子我之前测试过两个LaTeX排版Skills一个声称支持中文一个没写。用同一篇中文文档做输入声称支持中文的那个第一次跑就成功编译通过另一个生成的内容里中文全部乱码。光看README根本发现不了这种差异必须实测。所以我强烈建议把“先评测再上生产”变成自己的固定流程。3. 手把手开发一个自己的Skills3.1 先定义能力边界别一上来就写代码很多人第一次开发Skills上来就打开编辑器写SKILL.md写着写着发现内容乱成一团。我踩过这个坑之后养成了一个习惯先回答三个问题再动笔。第一这个技能解决什么具体问题要用一句话说清楚比如“把Git提交记录整理成周报草稿”。第二输入是什么、输出是什么比如输入是项目路径和日期范围输出是Markdown格式的周报。第三哪些情况明确不处理这个特别关键没写清楚边界Agent就会过度发挥。比如会议纪要Skills可以处理转写文本整理但不处理音频文件本身这个边界必须写明白。定义好这三个问题之后建议再写一个简短的“用户场景示例”。比如用户说“帮我生成本周周报”Agent应该能根据这个描述联想到应该调用哪个Skill。这个示例会成为你写description的重要参考。我在开发第一个Skills的时候就是因为没定义边界导致每次任务都很容易被带偏。后来补上了“不处理事项”和“典型触发示例”两段准确率立刻上来了。这个经验我觉得值得大家都在项目里落地。3.2 编写SKILL.md与配套脚本下面用一个“周报生成Skills”作为完整示例带大家走一遍编写流程。先建目录结构weekly-report-skill/ ├── SKILL.md ├── scripts/ │ └── collect_git_log.py └── templates/ └── weekly_report_template.mdSKILL.md这样写--- name: weekly-report description: 根据Git提交记录生成周报草稿。 当用户提到“周报”、“本周工作”、“提交记录”时使用。 输入是项目路径和日期范围输出是Markdown格式周报。 --- 1. 解析用户提供的项目路径和日期范围默认最近7天。 2. 调用scripts/collect_git_log.py获取该时间段的Git提交记录。 3. 按提交类型分类整理功能开发、Bug修复、重构、文档、其他。 4. 填充到templates/weekly_report_template.md中。 5. 输出周报草稿并提示用户补充遗漏项。 不处理跨仓库合并统计一用户只统计指定路径下的仓库。配套的collect_git_log.py核心逻辑如下import subprocess import sys from datetime import datetime, timedelta def collect_git_log(repo_path: str, days: int 7) - str: since (datetime.now() - timedelta(daysdays)).strftime(%Y-%m-%d) cmd [ git, -C, repo_path, log, f--since{since}, --prettyformat:%s|%ad, --dateformat:%m-%d ] result subprocess.run(cmd, capture_outputTrue, textTrue, encodingutf-8) return result.stdout if __name__ __main__: repo_path sys.argv[1] days int(sys.argv[2]) if len(sys.argv) 2 else 7 print(collect_git_log(repo_path, days))模板文件就是周报的Markdown骨架预留了“本周完成”“下周计划”“风险与问题”几个小节。这一步最核心的思路是把重复劳动交给脚本把质量判断交给模型。脚本负责准确获取数据模型负责语义分析和结构化输出。这样分工明确技能才稳定。3.3 安装、触发与实测迭代写完之后把它放到Claude Code的项目级skills目录mkdir -p .claude/skills cp -r weekly-report-skill .claude/skills/重启会话后在对话里输入“帮我把xxx项目的本周提交整理成周报”正常情况下Agent会识别出这个任务属于weekly-report技能自动加载SKILL.md并执行流程。如果它没触发可以试试显式触发在Claude Code里用#weekly-report加上任务描述。不同框架的显式触发方式可能不同建议先查官方文档确认。第一次跑通只是起步真正的功夫在迭代。我建议拿到结果后反问三个问题输出结构是不是我想要的哪些步骤可以进一步自动化有没有出现脚本报错或理解偏差每调整一次就记录一下改动内容。以我自己做的周报Skill为例第一版只支持单仓库后来发现实际场景经常要汇总多个子仓库的提交就改成了接收多个路径参数。又跑了几周发现“风险与问题”这个模块永远为空因为提交信息根本看不出来风险索性改成默认不填让用户手动补充。这些细节都是只有长时间用下来才能发现的一次成型不现实。4. Agent Skills常见问题与排错实录4.1 遇到“Agent execution terminated due to error”怎么办热词里有一条“agent execution terminated due to error”这是很多人在使用Agent过程中遇到的最让人头大的报错——任务跑得好好的突然就终止了也没说明白是哪里出错。被这个问题坑多了之后我总结了一套排查方法。先看错误日志的尾部信息找到terminated之前的最后一条工具调用记录。90%的情况下问题都出在那个工具调用上。然后单独在终端里手动执行这一步的脚本看它能不能独立完成。比如周报Skill里collect_git_log.py报错你就手动跑一遍python scripts/collect_git_log.py /path/to/repo 7如果脚本本身跑不过说明问题在脚本环境依赖没装、Python版本不对、路径写死不存在。这几类问题跟Skill本身没多大关系更多是环境配置问题。如果脚本能跑通那多半是模型生成的调用参数有问题比如传了不存在的路径、参数格式不对这时候要回头检查SKILL.md里的参数说明是否清晰有没有给出示例值。另外一个常见原因是执行超时。有些Skill流程里包含耗时较长的操作比如大型项目代码扫描、图片批量处理Agent内置的执行超时时间到了就会强制终止。解决办法是把耗时步骤拆细或是在Skill脚本里加上阶段性日志输出让Agent知道任务还在推进。4.2 Skills装了却不生效多半是这几个原因“为什么我装了SkillsAgent根本没反应”这个问题我收到过很多次。根据我的经验绝大多数情况跑不出下面四个原因。第一目录位置放错了。Claude Code只认两个skills目录要么用户级~/.claude/skills/要么项目级.claude/skills/。你放到其他目录框架根本扫描不到。第二SKILL.md格式不对。YAML frontmatter必须放在文件最顶部且name和description字段不能省。漏了frontmatter这个Skill不会被索引。第三description描述语义匹配不上。你要是写一个LaTeX排版技能但description里全是“文档撰写”那Agent遇到排版需求时压根不会考虑它。第四框架版本太老。Skills是较新的特性如果长时间没更新版本可能根本不支持。判断是不是第一个原因最简单直接在终端里查看框架是否扫描到了该技能ll ~/.claude/skills/ ll .claude/skills/看看你的技能目录在不在里面没有就是位置不对。格式和描述问题打开SKILL.md逐行检查就可以。4.3 多个Skills产生冲突时如何收敛当你的Skills数量多到一定程度会碰到一个新问题两个Skills看起来都能处理同一个任务Agent不知道该选哪个。比如我同时装了“通用文档Skill”和“LaTeX排版Skill”当用户说“把这篇报告排版一下”Agent就需要在两者之间做选择。冲突的核心原因是description覆盖范围重叠。解决思路不是把其中一个删掉而是明确各自的职责边界。我的做法是给每个Skill的description加上“触发器关键词”和“排除条件”。比如排版Skill里写“当用户需要生成LaTeX或PDF文档时使用”通用文档Skill里写“当用户需要撰写Markdown笔记不涉及LaTeX排版时使用”。这样描述清晰了Agent的决策就容易了。还需要注意Skills的加载顺序。有些框架会优先加载用户级目录里的技能有些则优先项目级目录。我的一般原则是项目级Skills应该覆盖项目特有流程用户级Skills负责通用能力。如果两者出现规则冲突项目级的优先级应该更高。具体怎么配置要看框架文档不同工具策略不一样。5. 从Skills到完整Agent开发进阶学习路线5.1 我给新人的Agent开发学习路线很多人在热词里搜“agent开发学习路线”。我的建议很直接不要一上来就看那些复杂的Agent框架源码而是从Skills切入这是一个最低门槛的学习路径。第一步熟练使用。先选一个主流框架日常高频使用重点体验它是怎么调度模型、怎么调用工具、怎么处理多轮任务的。第二步拆解Skill。GitHub上那些成熟的Skills仓库是最好的学习材料自己动手装几个拆开看里面SKILL.md的写法、脚本的组织方式。第三步自己写Skill。从最简单的技能开始练到能独立设计一个多脚本协作的完整技能。第四步上升到框架层面。这时候再去接触LangGraph、OpenAI Agents这些框架你会发现之前用Skills积累的经验全都能用上——工具封装、上下文管理、语义匹配这些概念在框架层面大同小异。这条路线的好处是每个阶段都有产出。第一步提升效率第二步积累经验第三步形成自己的技能库第四步才真正进入Agent开发的核心。相比一开始就啃框架文档这条路友好得多。5.2 记忆、工具调用与安全做Agent绕不开的三件事热词里有“agent记忆”“agent安全”说明大家关注的点在从“能用”往“好用、可靠”迁移。这确实是Agent开发里三个绕不开的课题。记忆方面Skills本身可以承载一部分记忆功能。短期记忆在上下文里长期记忆得靠外部存储比如把执行过的任务记录写入文件下次执行时让Agent先读取这些记录。我在周报Skill里的做法就是让脚本把每次生成的周报追加到一个history.md里后续生成时可以参考之前的结构和风格。工具调用是Agent的核心能力。Skills要稳定工作依赖清晰的参数定义和可靠的错误处理。脚本里必须做好异常捕获不能让一个文件不存在就导致整个任务终止。每条外部命令执行完都要检查退出码有问题及时报错并给出可理解的提示。安全这块更要重视。Skills本质上给了Agent执行本地脚本的权限这就等于打开了系统的一扇门。我的原则是不装来历不明的Skill对包含脚本的Skill装之前先通读一遍代码Skill内脚本遵循最小权限涉及删除、覆盖文件的操作先确认再执行。特别是搜索热词里那些“skills安装包”里面可能有收集信息、执行网络请求的脚本一定要先审后装。5.3 想面Agent方向这些话题值得提前准备热词里有“agent开发面试题”说明很多人在准备Agent方向的岗位面试。结合我自己的经验面试官问来问去其实就集中在几个话题上。现代Agent架构是必问的要能讲清模型、工具、记忆、执行循环这些组件怎么协作Skills在其中起什么作用。Agent和RAG的区别也经常出现前者偏向多步骤任务执行后者偏向知识检索问答。工具调用一致性、eval设计也是高频题可以参考“agent evals”这个概念来准备。harness和agent的区别在面试里出现的频率也在上升尤其是问你对Claude Code这类工具的理解时。准备这些话题不建议死记硬背。最好的方法还是自己动手做一两个Agent小项目把Skills、记忆、工具调用全走一遍。面试官问到一个点你能随口说出实际踩过的坑和解决方案这种真实经验远比背概念有说服力。最后分享一个我个人的工作习惯。我现在接到一个新需求第一反应永远是问自己这个活儿我是不是每周都要干如果是我就花半小时把整个流程封装成一个Skill以后就不重复劳动。反过来如果只是偶尔一次的需求那就直接用临时Prompt解决不急着封装。封装是有成本和维护负担的装得太多、写得太泛反而会让Agent变“笨”。控制好Skills的数量和质量让每个技能都真正解决一类高频问题这才是Agent工作流能持续提效的核心。