agent-skills 全面拆解从 Harness 到 Agent 的技能革命开发者的下一张门票最近社区里冒出一个高频词agent-skills。如果你关注 Claude Code、Codex、OpenCode 这些 AI 编程工具不可能避开它。但很多人对它的理解停留在“给 Agent 加一段 prompt”这就大错特错了。我在实际项目中把 agent-skills 从安装、编写、调试到落地跑通踩了不少坑也总结了一套方法论。这篇东西就是把 agent-skills 背后的原理、安装流程、开发思路和真实项目对应经验一次讲透建议先收藏再细读。先说结论skills 不是 prompt是 Agent 的能力封装层。它和 Agent 的关系不是“提示词和模型”的关系而是“工具集和执行策略”的关系。理解了这一层你才能真正用好它。1. 这一轮 Agent 进化背后的核心逻辑Skills 为什么突然爆火1.1 从“会聊天”到“会干活”中间缺的就是 Skills如果你用过早期基于大模型的对话助手你会发现一个尴尬的事实它能跟你聊编码思路但让它自己去改代码、跑测试、处理文件大概率会卡在第一步。原因很简单大模型本身是一个“大脑”但它没有“手脚”。让它读文件、执行命令、调 API、写数据库这些动作需要工具支持。早期的 Agent 框架解决的是“让模型能调用工具”的问题但工具是碎片化的你得告诉它用哪个函数、传什么参数、什么时候调。这就催生了 Harness 这类执行环境的出现。Harness 是 Agent 的“身体”负责把模型的决策翻译成可执行动作调度工具、管理上下文、处理会话状态。但这里产生了一个新问题Harness 是通用的而任务场景是千变万化的。这就好比给你一副好用的筷子但菜系不同夹法完全不同。Skills 就是来解决这个问题的——它是可复用、可共享、面向特定任务的“能力包”让 Agent 不止有手有脚还知道怎么做一道具体的菜。1.2 Harness 和 Agent、Skills 到底怎么分工很多技术人员把这三个概念混在一起这会导致架构设计上的误判。我列一个比较直观的分层关系Model模型层负责推理和生成是决策中心。它决定“下一步做什么”。Harness执行层负责跑循环管理上下文窗口、工具调用、错误恢复把模型的输出变成动作。Agent智能体层一个完整的智能体实体通常由模型 Harness 一系列 Skills 记忆系统组成。它知道“我是谁、我在哪、我要达成什么”。Skills技能层特定领域的工作流封装。它告诉 Agent “遇到这种情况应该按这套流程做用这些工具按这种格式输出”。用我做前端开发的经验类比Harness 像浏览器的渲染引擎Skills 像你写的一个个 Vue/React 组件。没有渲染引擎组件跑不起来没有组件渲染引擎只能做最基础的事。Agent 是最终的产品页面模型是底层的 JS 执行引擎。这个分层想通了你就明白为什么现在各大厂都在卷 Skills 生态——因为模型可以收敛Harness 可以统一但 Skills 是无限场景的入口是真正的护城河。1.3 为什么偏偏是现在爆发模型能力恰好过了临界点两年前的 Agent 不是没做过类似尝试但当时模型指令遵循能力太弱一个几步骤的流程都执行不明白更不用说多技能调度。这两年大模型在长上下文、工具调用、指令遵循方面有了质的提升CLAUDE 和 GPT 系列已经能在一次会话中稳定执行几十步操作。只有当模型能力到了这个水平Skills 这种“复杂工作流封装”才有意义。这就像 CPU 速度不够时你写再多高级语言编译器也无法流畅运行大型应用。而且Skills 还有一个隐藏优势缓存友好。一个设计良好的 Skill 文件是静态的可以被缓存加载时不会额外消耗大量 token。你在一个大规模代码库上跑 agent-skills 时就会体会到省 token 就是省命。2. 核心概念辨析Skill 和 Agent、Harness 的区别以及为什么这对开发至关重要2.1 Skill 是“方法”Agent 是“执行者”Harness 是“运行环境”在社区里已经有好几篇争论“skill 和 agent 区别”的帖子但多数讲得云里雾里。我用一个非常落地的场景来说明。假设你要让 AI 帮你做一个数学建模项目。第一种做法你写一个很长的 prompt把建模流程、公式、输出格式全塞进去。这是最粗糙的方式每次都要消耗大量 token且容易在对话过程中偏离。第二种做法开发一个数学建模 Skill它内部定义了一套完整的流程——读取数据、数据清洗、特征选择、模型对比、结果可视化、生成报告每一步都调用对应工具每一步的输入输出格式都定义好了。当 Agent 需要完成建模任务时直接在 Skills 列表里选中这个 Skill加载流程按照它定义的步骤执行。Agent 是执行者它负责综合上下文和做出判断Skill 更像是兵书里面写好了作战计划Agent 拿着兵书去打仗。再对比 Harness。Harness 是 Agent 的运行框架它负责“怎么跑循环、怎么管理消息、怎么调用工具”。不同的 Harness 实现对 Skill 的支持程度也不一样。目前主流的 Harness 有 Claude Code 内置的 Agent SDK、Codex 的命令行环境、OpenCode 等它们各自定义了自己的 Skills 格式。2.2 Skills 分类West 到 East从完整技能到最小触发我在实际整理自己的 skills 集合时倾向于把它们分成三类完整工作流型 Skill比如 superpower skills 里的 brainstorming、coding、research面向复杂任务定义从开始到结束的完整流程。单项能力型 Skill比如网上流传的 fetch_webpage、url_to_markdown聚焦单一操作但比普通工具函数更智能加入了异常处理和重试逻辑。提示词触发型 Skill比如 skill instructions“轻量级”定义本质上是告诉模型该按什么策略思考和回答不涉及具体工具调用。这三类 Skills 在 agent 开发中都很有用。完整工作流型适合“从零到一”的创造性任务单项能力型适合精确操作触发型适合在不增加工具负担的情况下优化模型行为模式。2.3 为什么说 Skill 是“知识库”的自然延伸你留意到一个现象没有热词里同时出现了“code ai知识库怎么积累”和“skills使用”。这其实是一件事的两种形态。知识库是静态的数据资产Skills 是动态的执行方案。两者应该配合使用知识库给 Agent 提供背景知识和参考资料Skills 给 Agent 提供操作流程和工具调用方案。举个例子我在团队里搭建过一个基于 Agent 的代码迁移项目目标是把旧系统里的 Java 代码段转换成 TypeScript。我们把历史迁移案例、踩坑记录、目标代码规范放进了知识库同时写了一个“code migration” Skill定义了迁移的步骤扫描目录 → AST 解析 → 逐函数转换 → 类型标注 → 生成测试 → 自检。这个 Skill 会主动调用知识库中的案例作为参考。两者一结合迁移成功率直接提升了三成。这个经验想说明什么Skills 不是独立存在的它是 Agent 体系中的一环设计时一定要考虑和知识的配合。3. 从零搭建自己的 agent-skills安装、配置、开发全流程实录3.1 准备工作选用哪个 Harness决定了你的 Skills 怎么写Skills 的安装方式高度依赖你使用的 Agent 工具。目前最主流的三条路线Claude Code以 Claude 平台为主支持.claude/skills目录Skill 以 Markdown YAML frontmatter 方式定义。Codex CLI关注codex skills的用户不少它支持通过配置文件定义 Skill并内置了 Google Drive 的 Skill。OpenCode较新的开源 Harness社区活跃Skill 生态也在快速成长。如果你刚开始我的建议是先从 Claude Code 或 Codex CLI 入手因为它们的 Skill 格式相对成熟社区示例多。我在本地开发环境同时装了 Codex 和 Claude Code根据不同项目切换使用后面会拆解具体区别。3.2 安装 superpower skills新手也能走的弯路我看你就不必走了superpower skills 是社区里知名度极高的 Skills 集合来自 superpowers 项目。安装它需要三个步骤克隆仓库把 superpowers 仓库拉到本地。复制 Skills把仓库中的 skills 文件夹拷贝到你的 Agent 的 skills 目录下比如 Claude Code 的~/.claude/skills。重启 Agent让 Harness 识别到新 Skills。听起来很简单但我第一次装的时候踩了坑只复制了部分子目录导致 Skill 引用的公共模块找不到。这个集合里的 Skills 之间有依赖关系最好整目录复制。安装完成后可以在对话中直接输入/skills或询问 Agent “你会哪些技能”它会列出可用的 Skills 清单。如果你期望装完就立刻看到显著效果那可能会失望——很多 Skill 要结合具体任务才能触发不是装了就等于“全知全能”。3.3 如何用 AI 开发一个自定义 Skill从需求拆解到文件落地这是本篇最有实操价值的部分。我在开发 Skills 时大部分时候不是纯手写的而是让 AI 辅助我生成然后我修正。流程如下第一步明确任务边界Skill 不是越大越好。一个 Skill 只负责一类任务。比如“网页抓取”可以是一个 Skill“数据分析”可以是另一个 Skill但别做一个“全能分析助手”Skill否则模型很难判断何时触发它。第二步用对话生成 Skill 初稿我通常会给 Claude 或 GPT 这样的指令“我是一个 Claude Code 用户我要为它写一个名为web_research的 Skill功能是抓取网页内容、提取正文、去重、总结要点。请帮我写一个符合 Claude Code skills 格式的 Skill 定义文件包含 name、description、instructions 和必要的工具调用示例。”第三步修正 frontmatter 格式生成的初稿往往格式有问题。很多 Agent 对 YAML frontmatter 非常敏感缩进错了就会导致 Skill 加载失败。这时需要逐字符检查name、description等字段是否匹配 Harness 要求。第四步测试和迭代在对话中触发新 Skill看它是否能正常完成流程。如果中途报错将错误信息返回给模型让它修正。这样一轮一轮迭代后Skill 才会稳定。3.4 实测让 Codex 跑一个 web_research Skill我用自己的一个 Skill 实测一下具体效果在 Codex 环境中我先在配置文件中注册了 Skill 目录然后在对话中给出一个 URL“用 web_research 分析这个链接的内容”。Codex 首先会加载 Skill 定义然后按其中的指令抓取链接内容、提取正文、生成摘要。如果一切顺利它会在几秒内返回结构化结果。这个过程里最惊艳的不是抓取本身而是 Agent 会自己处理异常——比如网页返回 403 或者 404 时它是根据 Skill 里的 fallback 逻辑重试而不是直接报错退出。这是纯粹的 prompt 工程做不到的因为你不可能在 prompt 里把所有异常都列全而一个写好的 Skill 可以包含这样的决策树。4. 高频 Skills 推荐与工具链盘点哪些是真香哪些是智商税4.1 社区闭眼入的 Skills 名单附实测感受结合热词和大家反馈我把自己实测过的 Skills 做了个分类推荐daily-thinking 类适合做项目复盘、日志整理能帮 Agent 建立规范化的输出结构。docs-crawler 类适合抓取文档站、生成站点摘要做技术调研很好用。frontend-design 类适合前端开发者将设计稿或描述转换为代码生成骨架和组件。code-review 类自动审查代码规范、潜在 bug、安全隐患配合 CI 流程非常香。testing 类自动生成测试用例尤其适合 TDD 流程的落地。如果你是做前端开发的前端高手我强烈建议优先装 frontend-design 类的 Skills因为它能把“设计语言转代码”这件事标准化。它背后是设计令牌到 Tailwind 类名的映射准确率明显高于手工 prompt。4.2 “Harness 和 agent 区别”避坑指南别把 Harness 选择当 Skills 选择很多初学者问“我该用 Claude Code 还是 Codex”这是个经典的 Harness 选型问题。但你要意识到两者不是二选一而是可以配合的。Claude Code 的 Skills 体系更偏向“定义式”用 Markdown 文件描述流程非常直观。Codex 的 Skills 集成更贴近代码库它能把 Skills 当作一种代码产物使用适合在代码仓库内部管理。我在实际项目中把通用的 Skills比如研究、分析类都放在了 Claude Code 里把项目定制的 Skills比如代码库理解的放在了 Codex 里。这样既保留通用能力又能让项目 Skills 跟着仓库走团队协作方便。这可能是 Harness 选型里最实用的一条经验。4.3 Skill 评价标准怎么判断一个 Skill 是真的好用网上一搜一大把 Skills怎么筛我觉得看四个点就够了触发性描述文字是否清晰Agent 能不能在遇到对应任务时准确触发它。鲁棒性遇到异常情况它是直接崩溃还是自身就能处理大部分失败场景。输出规范性产出结果是否结构化能否直接被下游流程消费。扩展成本修改一个 Skill 定义是不是只改一个文件还是牵一发动全身。这四个标准立住你挑 Skills 就不容易踩坑。我见过太多“看起来很高级”的 Skills一测就现原形——不是格式错误就是逻辑写得太死。记住Skill 是给 Agent 用的“活方法”不是“死文档”。5. Agent 开发学习路线与 Skills 的结合我推荐的学习路径5.1 从入门到进阶不走弯路的四个阶段阶段一理解 Agent 是什么先弄清楚 Agent 的基本架构模型、工具、上下文、记忆、执行循环。这一步不需要代码看官方文档和几篇优质拆解文就够了。阶段二玩转 Harness选择 Claude Code 或 Codex CLI 中的一个每天用它处理工作流场景。理解 Harness 的上下文管理、工具注册、对话循环机制。阶段三从消费 Skills 到编写 Skills先装一套成熟的 Skills比如 superpower skills观察它的触发逻辑和结构。然后挑一个小需求照着现有 Skill 的格式仿写一个自己的 Skill。阶段四对 Agent 进行评测与安全加固Skills 用得多了你会关心 agent evals 和安全问题。给 Agent 一套评测集测试 Skills 的覆盖率、准确率、误触发率。安全方面注意避免 Prompt Injection 攻击——恶意网页内容可能诱导 Agent 调用不该用的 Skill 或者泄露系统信息。好的 Harness 通常有安全机制但 Skill 设计时也要有意识。5.2 三个能快速提升的实战项目如果你想通过实操来学习我建议从这三个项目开始个人知识库 Agent把笔记系统变成可检索、可自动归类的 AI 助手。涉及 RAG、文件扫描和摘要 Skills。代码评审助手把代码评审的规则和标准封装成 Skill让 Agent 对每次提交进行自动检查。涉及代码理解、规则匹配和报告生成。自动化测试生成器让 Agent 根据函数签名和注释自动生成测试用例。涉及框架理解、测试模板和断言逻辑。这三个项目分别锻炼知识管理能力、规则执行能力和代码生成能力做完之后你对 agent-skills 的理解会有一个质的飞跃。5.3 别做只会调 Skill 的“套壳开发者”写到这里我得说句实在话。当前阶段skills 的确把 Agent 的能力上限抬高了一大截但本质上它还是把人的经验固化为流程。如果你想在 agent 开发这条路上走得更远底层能力还是要自己抓学会看 Agent 的运行日志理解它每一步在干什么。学会写评测集量化 Skill 对你的业务带来的提升。学一点系统设计知道 Skill 应该放在哪里、怎么更新、怎么和别的模块交互。工具是杠杆但支点还是你自己的判断力。6. 常见问题与排查技巧实录让 Skills 从“能跑”到“跑得稳”6.1 症状、原因、解法速查表下面是我的经验整理真正开发中高频遇到的坑常见症状根本原因排查/解决方式Skill 没被触发Skill 的 description 写得不明确模型不知道何时调用重写 description明确描述适用场景和触发条件加载时 YAML 报错frontmatter 缩进或字段名错误用 YAML 校验工具检查确保 name、description 等字段正确Skill 运行一半卡住工具调用超时或者上下文被截断增加工具超时时间优化 Skill 步骤减少冗余中间输出模型调用 Skill 后跑偏Skill 内部指令不够结构化增加明确的分步指令和“必须输出格式”的限定多个 Skill 误触发不同 Skill 的 description 有重叠给每个 Skill 加“并不适用于 XXX 场景”的 negative description更新 Skill 后不生效Agent 缓存了旧版本重启 Agent或者清空 cache 目录这其中的负面描述negative description是很多新手容易忽略的。比如你有一个“代码生成”Skill 和一个“代码审查”Skill如果描述里没写明彼此边界Agent 经常会把“审查任务”错误触发到“生成任务”上。在 description 里加上一句“优先用于生成不用于评估既有代码质量”这样的约束效果立竿见影。6.2 实际排查案例superpower skills 安装不生效的完整复盘有一个案例值得写出来一位开发者在 Claude Code 里装好了 superpower skills但对话中 Agent 说找不到这些 Skills。后来排查发现他把 Skills 放到了.claude/skills.example目录下而系统只会加载.claude/skills。这个例子看起来低级但说明了一个共性问题Skills 的路径和命名一定要按照 Harness 的约定差一个字符都不行。对于 Codex还要注意 Skill 的执行权限问题。默认情况下Codex 可能不会直接允许 Skill 执行某个操作比如写入系统目录你需要在配置中授予对应权限。这个“权限模型”和 Harness 的安全机制紧密相关千万别为了省事把所有权限放开。6.3 让 Skill 和 Agent 的记忆模块协同工作热词里有“agent记忆”这也是一个关键点。Skills 定义的是“怎么做”记忆系统定义的是“你是谁、之前做过什么”。一个好的 Agent 产品一定把两者分开记忆持续积累Skills 按需加载。在设计 Skill 时你可以让 Skill 主动请求记忆模块提供上下文。比如在“客户报告生成 Skill”的指令中写明第一步读取记忆模块里的客户历史数据第二步再执行模板渲染。这样 Skill 就不再是“无状态函数”而是可以和 Agent 的整体状态协同。6.4 安全红线Skills 开发者必须知道的合规边界最后必须谈安全。Skills 赋予了 Agent 更强的能力意味着风险更高。我这里只提醒三条不加私密信息Skill 文件不要包含 API Key、密码等敏感信息这些应该放在独立配置文件或环境变量中。限制文件操作范围如果 Skill 需要操作文件尽量限定在指定目录内避免对整个系统任意读写。隔离恶意输入如果 Skill 抓取外部网页内容注意检查该内容是否包含注入指令。一个写的不安全的 Skill 可能让 Agent 把对话历史上传至恶意服务器。该关注的不只是“能不能跑起来”还有“跑起来会不会出事”。安全不是后补的是 Skill 设计时必须考虑的能力。一路用下来我对 agent-skills 的感受可以归纳成一句话它把“调教 AI”的门槛从提示词工程降到了配置工程和流程工程让更多人可以把自己的工作方法沉淀为可复用资产。但它的天花板不在于单个 Skill 的智能而在于你能不能把多个 Skills 编织成一个高效协作了。我个人的习惯是每完成一个有价值的任务就抽象出一个 Skill 沉淀下来日积月累这套 Skill 库就成了团队里的隐形资产。还没上手的同学建议今晚就从装一个你自己最需要的 Skill 开始用一个真实任务去检验它然后改成你自己的版本。这一步迈出去你就已经领先大多数人一个身位了。