Agent Skills实战指南：从概念到安装调试的完整梳理

接到这个标题“agent-skills”的时候我第一反应是这不就是当前 AI Agent 开发圈里被讨论最多、却也最容易被误解的一个概念吗如果你最近刷过 GitHub、看过 Codex 或 Claude Code 的更新日志大概率已经见过 skills、superpower skills、pi agent、codex skills 这些词。它们围绕同一个核心让 AI Agent 不再只是“会聊天”而是真的“会干活”——按固定流程、带专业方法、能稳定复现地干活。这篇内容我想用做 agent 项目的实操视角把 skill 到底是个什么东西、和 agent / harness 有什么区别、怎么安装、怎么写、怎么避坑从头到尾捋一遍。无论你是刚接触 agent 开发的新手还是已经在调 Codex、Claude Code 但被“execution terminated due to error”折腾到头秃的老手这篇文章都能给你一些可以直接上手的参考。1. Skills到底是什么一句话能说清但很多人理解偏了我见过不少人在群里问“skill 和 agent 有什么区别”。如果只能回答一句话我会说agent 是“执行者”skill 是“执行者脑子里的操作手册”。一个 agent 可以没有 skill跑步起来但想让 agent 在某个领域稳定干活几乎必须有 skill。1.1 从 Prompt 到 SkillsAI Agent 的“肌肉记忆”最早大家用 LLM 的时候靠的是 Prompt。你把需求写清楚模型自由发挥。自由发挥的问题在于同一个任务今天的结果和明天的结果可以差很多。尤其在代码生成、图片生成、文档排版这类有固定流程的任务里模型常常会跳步、漏细节或者“自以为做完了但根本没保存文件”。Skills 的出现就是为了解决这个“自由发挥”的问题。它本质上是一个预定义好的、可复用的能力包里面装的是对任务目标的明确描述完成任务的步骤或流程每一步需要调用的工具或命令判断结果是否合格的检查项常见坑和禁忌用生活类比来说Prompt 像你给一个实习生口头交代“把这个报表做一下”而 Skill 像你给他一本《报表制作标准作业流程手册》里面写了用哪个模板、数据从哪取、公式怎么填、做完怎么自检。显然后者的结果稳定得多。我在实际项目中有一个体会不带 skill 的 agent 更像一个“聪明但不太靠谱的新人”而带着 skill 的 agent 可以做到“稳定产出合格结果”。这背后的原因是skill 把隐性的专家经验显性化了。你不需要每次对话都重新解释需求和流程agent 会在匹配到对应场景时自动套用技能。1.2 Skill、Prompt、Tool、Agent 到底有什么区别这个表我建议你存下来因为几乎每个做 agent 的人都会被问到概念本质类比生命周期Prompt一次性的指令文本口头交代随对话消失Tool可调用的外部函数/API工具手套常驻但不知道自己该干啥Skill一组流程 指令 工具的集合操作手册可保存、可复用、可分发Agent能感知、决策、调用工具执行任务的实体员工由模型驱动加载 skills 后干活HarnessAgent 的运行环境与调用循环工位 管理制度承载 agent 执行很多人的误区是把 skill 当成一个超长 prompt。实际上一个完整的 skill 往往包含多个文件除了 instructions 或 SKILL.md 这种主文档还有脚本、模板、参考样例。它是一套“资源包”不只是几行文字。还有一个常被搞混的点tool 和 skill 的区别。Tool 是“手”skill 是“脑子里的规程”。你可以给 agent 一个 Python 执行工具但它用 Python 写爬虫还是写数据分析取决于 agent 自己的临时发挥而 skill 则规定好了第一步用 Python 拉数据第二步清洗第三步画图并保存到指定目录。所以skills 可以调用 tools但 tools 本身不等于 skills。1.3 为什么今年“Skills”突然爆火前面提到AI 编程工具已经进入了“记忆 技能”的竞争阶段。一个 Agent 如果只有模型本身的推理能力没有外部技能包它顶多是一个“聪明但失忆”的助手。而有了 skillsagent 可以像老员工一样对不同任务直接调用储存在工作记忆里的流程。这也解释了为什么 Codex、Claude Code、OpenCode、Pi Agent 都在争相支持 skills谁支持的技能格式多、谁安装 skill 更方便谁就能吸附更多开发者生态。对于我们自己写代码的这些人来说好消息是skills 一旦写好是可以在多个 agent 框架之间迁移的至少目前主流的 SKILL.md 规范在互认。坏消息是各家在安装路径、调试命令、harness 行为上有差异需要针对性地适配。2. 主流 Agent 框架里的 Skills 生态各家用各家的“方言”做 agent 开发的人应该都能感受到当前框架层的变化频率有多快。以我长期用的 Claude Code 和 Codex 为例它们对 skills 的支持方式差异其实挺大的。2.1 Claude Code 与 Codex两大流派的思路Claude Code 的思路是“把技能放进项目上下文”。它会在启动时读取.claude/skills目录下的技能文件将其中的指令注入给模型。这个方案的优点是对用户透明你能直接在对话里感知到“这个技能生效了没有”。缺点是技能太多会挤占上下文窗口影响模型处理当前任务的空间。Codex 的思路更偏向“按需加载”。它把技能视为一个独立资源只有当任务描述与技能描述匹配时才会被加载执行。这种方式的上下文开销更小但对技能描述description的写作质量要求更高——描述写不好模型根本不会触发你的技能。我见过很多开发者的 skill 写得很好但因为 description 里没有写上“什么时候用这个技能”结果一直没被触发。在安装路径上Claude Code 手动装 GitHub 上的 skills 一般是 clone 到.claude/skills/目录Codex 通常放到~/.codex/skills/或者项目下的.codex/skills/。这块没有行业统一标准各框架之间互不兼容的情况很常见。我的习惯是在项目.cursor或.claude下都保留一份关键技能的软链接避免切换工具时丢失行为。2.2 周边生态OpenCode、Pi Agent、Superpower Skills 与技能库OpenCode 是一个轻量化的 agent 终端工具它的 skills 体系跟 Codex 接近依赖 markdown 文件的头信息和目录结构。Pi Agent 则是今年社区里讨论度很高的另一个 agent 项目它强调“多技能组合调用”在某些场景下可以把多个 skill 串联成一条工作流。社区里还有一个很出名的技能集合叫 superpower skills很多人搜“superpower skills 安装”就是在找它的安装方式。这个集合把大量实用技能如代码审查、重构、文档生成打包在一起安装方式也比较友好。我试用过其中的代码审查技能确实比裸写 prompt 效果稳定因为它的检查清单非常具体比如“是否修改了公共接口但没更新所有调用方”这类细节都能覆盖到。此外社区里也涌现出不少“常用 skills 源网站”和“skills 技能库”。这些站点通常按类别整理好了各种领域的技能比如前端开发、数据可视化、LaTeX 排版等。我的建议是第一次逛这类技能库时不要疯狂下载先想清楚你日常最重复、最痛苦的任务是什么再针对性地选 2-3 个技能深度使用。否则技能包越攒越多真正用到的不超过一成反而拖慢 agent 的加载速度。这里也提醒一下从非官方渠道下载技能包时务必检查 SKILL.md 中是否包含可疑的额外指令比如要求 agent 执行 curl 脚本、上传本地文件到外部服务器等。AI 领域的供应链攻击已经开始出现了安全红线必须时刻绷紧。3. 动手开发第一个 Skills从零到能稳定复现接下来进入正题。与其到处找现成 skills不如自己动手写一个。自己写的技能有两个好处一是完全贴合你的工作流程二是能帮你看清 skills 的底层机制之后调试别人的技能包也会快很多。3.1 设计 Skills 的核心步骤先写文档再写流程我在跟很多朋友交流时发现新手最容易犯的错是一上来就写代码、写脚本。但 skills 的核心其实是“流程设计”不是“脚本编写”。我一般会先回答三个问题这个技能解决什么任务任务边界必须清晰比如“生成项目周报”而不是“写文档”。一个专家是怎么完成这个任务的把步骤拆到 5-8 步每步必须有可验证的输出。哪些地方容易出错把这些坑写进“注意事项”或“checklist”。以我最近写的一个“图片批量压缩并生成对比图”的技能为例。最初版本的流程只有三步读取图片、压缩、保存结果。但实际使用时agent 经常压缩完就忘了生成对比图。后来我在技能里加了一条硬性约束“第 3 步完成后必须生成压缩前后对比图并且当且仅当对比图存在时才能输出完成消息”问题才被解决。这就是我们常说的“可验证输出节点”。每一步之后agent 需要 self-check 才能进入下一步而不是让它自由发挥。3.2 骨架、SKILL.md 与行动清单的写法一个标准 skill 的目录结构通常是这样的my-skill/ ├── SKILL.md ├── scripts/ │ └── main.py ├── templates/ │ └── output_template.md └── examples/ └── sample_input.json其中 SKILL.md 是核心一般用 Markdown 编写。我的习惯是以下结构--- name: weekly-report description: 根据 git 提交记录生成周报。适用于项目周报、月度总结输入为 git log 或 issue 列表。 ---frontmatter 之后正文需要包含触发条件与输入格式明确这个技能什么时候被调用。执行步骤数字编号每一步尽量包含可执行的命令或文件路径。输出规范最终产物的格式与保存路径。checklist输出前的自检清单。常见错误以及对应的处理方法。我一般不会把超长示例写进 SKILL.md 本体而是放在 examples/ 目录下让模型按需读取。因为很多 agent 框架在处理超长文件时反而会“抓不住重点”。3.3 调试与迭代一次真实开发踩坑记录写完第一个 skill 后真正的痛苦才开始。我调试“代码重构”技能时前三次运行全部失败。第一次失败是因为步骤描述太模糊agent 重构完没有跑测试第二次我加了“必须运行 go test ./...”的指令但它真的老老实实跑了却因为测试环境缺依赖报错agent 直接放弃了任务报出 “Agent execution terminated due to error.” 后来我在技能里加了“若测试因依赖缺失失败先安装依赖再重试”的决策分支效果才正常。这次经历让我总结出一个调试原则永远给 agent 留“失败后怎么办”的补救路径。如果你只告诉它“做 A、做 B、做 C”当 B 失败时它很可能卡死或直接终止。而一个成熟的技能应该像老手带新人一样把“如果遇到 X就试试 Y”写清楚。调试时还有一个痛点上下文爆炸。如果技能文件太多太长agent 到后面会“忘掉”前面的步骤。我的解决方案是把一次性加载的内容控制在 2000 字左右其余内容做成参考文件在需要时由 agent 自己决定是否读取。这个“按需读取”思路也是很多主流 agent 框架默认支持的。4. 安装、使用与编排别让 Skills 变成“摆设”写好 skill 只是第一步怎么把它装进 agent并在日常流程里稳定触发才是真正考验耐心和工程能力的地方。4.1 手动安装与常用技能源很多人在搜“claude code 怎么手动装 github 上的 skills”和“opencode skills”说明安装这件事确实有门槛。以最常见的做法为例安装步骤大致是# 进入技能目录 cd ~/.claude/skills # 或者项目级目录cd .claude/skills git clone https://github.com/username/skill-repo.git # 安装后重启会话或直接询问 agent 是否识别到新技能对于 Codex路径一般是mkdir -p ~/.codex/skills cp -r /path/to/my-skill ~/.codex/skills/安装完之后一定要先问 agent“你现在能用哪些 skills”或者让它复述技能内容确认技能被正确加载。这能省下很多“我明明装好了但它根本不理会”的排查时间。关于技能源社区比较活跃的仓库通常会在 README 里写明安装方式。我的建议是优先选择那些带有 examples 目录、且每个技能都有独立 description 的仓库。如果某个技能包只有一个巨大的 markdown 文件没有任何脚本和示例它很可能只是换了个名字的“超长 prompt”对稳定产出的帮助有限。4.2 Agent Harness 与 Skills 的编排关系“harness 和 agent 区别”也是热搜里的高频问题。Harness 可以理解为 agent 的运行框架它负责调度模型、解析工具调用、管理上下文窗口、处理错误。Skills 则在 harness 的规则之下运行。实际工程中harness 决定了 skills 的能力边界上下文窗口大的 harness 可以加载更多技能说明但成本更高自动错误重试机制强的 harness能让技能里的“补救分支”发挥更大作用工具权限控制严格的 harness安全性更高但也会限制技能脚本的灵活性所以当你在 A 框架里验证了一个 skill 很正常换到 B 框架后效果大打折扣不一定是 skill 写得不好也可能是两个 harness 对上下文的裁剪策略不一样。我习惯在技能文件里写明最低框架要求比如“需要支持 128k 上下文”方便以后迁移时快速判断。另外编排多个 skills 也是今年的热门话题。比如 Pi Agent 支持把“前端开发”和“图片生成”两个 skills 组合使用先由图片生成技能产出素材再由前端开发技能把素材嵌入页面。这种组合本质上是在 harness 层做任务规划然后逐个子任务调用对应的技能包。实践中我发现组合技能时的上下文管理比单个技能难得多务必把两级技能之间的转交方式写清楚例如“输出文件路径必须以绝对路径传给下一步”否则 agent 会在中间丢链子。5. 常见问题与排查技巧实录最后这部分是我想重点分享的实战避坑清单。以下这些问题都是我自己或身边同事真实踩过的坑整理出来希望帮大家少走弯路。5.1 典型报错与解决对照表现象可能原因解决思路Agent execution terminated due to error执行命令非零退出且技能没有补救路径在技能中加入失败重试分支明确“遇到依赖缺失先安装再重试”技能没被触发agent 无视 skilldescription 写得太宽泛或没有关键词重写 description明确触发条件和输入样例技能执行到一半“失忆”忘记步骤上下文过长早期指令被截断精简 SKILL.md把示例和详细文档移到单独文件按需加载安装后 agent 不识别新技能路径不对或没有重启会话按框架要求放到正确路径重启会话并让 agent 复述技能内容多个 skills 互相冲突行为错乱技能优先级不明确在 harness 层配置技能优先级或在技能中明确“本技能不处理 X 任务”图片生成/文件输出不符合预期缺少输出校验环节添加自检节点要求 agent 生成后先检查文件是否存在、尺寸是否正确再返回结果使用外部技能后本地文件被改动技能包含可疑指令执行前审查技能源码禁用来源不明的技能包5.2 稳定性心法和安全红线关于稳定性我最深的体会是skills 开发是一个迭代过程不是一次性写作。第一版能跑通就算成功了一半后续要在真实使用中不断补充边界情况和补救分支。你可以把技能使用过程中的每一次失败记录下来每周集中更新一次技能文件。三个月后这个技能会变得越来越“懂你”。安全红线可以总结为“三不”原则不直接执行技能文件里含有的不可见代码先看后跑。不让 agent 自动上传项目内文件到未经确认的外部服务。不把高权限凭据如云厂商密钥放进技能的输入输出路径中。这些属于 AI 工程里容易被忽视的供应链安全范畴。Skill 的本质是“把代码逻辑混入文档”这既是它的威力也是它的风险。能用、好用、安全地用才是一个合格 agent 开发者的完整要求。最后再分享一个我的个人习惯重要技能都应纳入版本管理像维护代码库一样维护它们。技能文件里的内容是写给 AI 看的“需求文档”也是写给未来的自己看的“流程资产”。当 agent 开发的知识散落在多个工具和对话里时一套清晰、可复现、可版本化的 skills 体系就是团队最值得沉淀的财富。