从零构建Agent Skills库：概念拆解、手写实战与跨框架复用

自己动手写 Agent Skills从概念拆解到可复用的 skill 库前几个月我一直在折腾各类 coding agentClaude Code、Codex、OpenCode 换着用慢慢发现一个特别明显的瓶颈每次换一个 agent之前积累的那套“调教经验”基本就废掉一半提示词重写、工具链重配、业务背景重新灌输非常折腾。后来我开始把各种能力拆成一个个独立的 skills也就是 agent skills情况才真正好转。现在不管是做前端页面生成、LaTeX 排版、图片生成还是数据处理我都是靠一整套 skill 库来驱动换底层的 agent 框架也只是换个加载方式能力本身不用重写。这篇文章就围绕 agent-skills 这件事展开把我从概念理解、目录设计、手写 skill、现成 skills 安装、到排错踩坑的完整过程记录下来。如果你正在接触 agent 开发或者被 system prompt 越长越难维护折磨又或者搜过 superpower skills、claude code skills、codex skills 这类关键词那这篇应该能帮你省不少时间。1. 先对齐一个基础认知Agent 和 Skill 的分工逻辑1.1 agent、skill、harness 到底差在哪很多人第一次接触 agent skills 的时候第一反应是“这不就是 prompt 模板吗”。我一开始也是这么想的后来发现这个理解不太准确。这里得先把几个概念理清楚agent、skill、harness。agent 是那个真正“干活”的智能体它负责理解用户意图、规划步骤、调用工具、判断结果是否满意。你可以把它理解成一个员工它有自己的思维方式、对话记忆和决策逻辑。skill 则是这个员工身上的“专业技能包”是某个具体领域内一套可复用的操作流程、规范要求和辅助脚本。而 harness 更偏底层是 agent 运行的环境和工具框架决定 agent 能调用哪些工具、以什么方式调用、上下文窗口怎么管理。这三者的关系我一般用“司机、路书和车”来类比agent 是司机负责判断路况、打方向盘skill 是路书告诉司机到达某个目的地应该走哪条路线、注意哪些标志harness 是车本身提供方向盘、油门、刹车这些基本操作能力。好司机配好路书和好车才是完整方案。说得通俗一点agent 解决“怎么想”的问题harness 解决“能做什么”的问题skill 解决“遇到某类具体事情该怎么做”的问题。这也是为什么现在很多团队把技能沉淀为 skills而不是继续堆提示词——技能包本质上是在 agent 的通用推理能力和具体业务操作之间加了一层结构化的中间表达。1.2 为什么不能把所有能力都塞进 system prompt早期做 agent 开发大家都习惯把所有背景说明、输出格式、禁忌事项一股脑写进 system prompt。我见过有人写好几千字里面塞了十几个项目的业务规则、三套代码风格、五六种输出模板。结果是什么第一上下文被大量挤占。system prompt 越长留给真正对话和资料分析的 token 就越少agent 的推理质量明显下降。第二规则之间互相冲突。不同项目的代码风格要求混在一起agent 经常不知道该听哪条输出结果一会儿符合这个项目一会儿符合那个项目。第三维护成本极高。改一个项目的规则要动整段 prompt稍有不慎就影响其他项目。skills 的引入恰好解决这个问题。每个 skill 是一个独立的、按需加载的能力模块agent 在遇到相关任务时才去读取对应 skill 的内容平时完全不占用上下文。这就像工具箱里的一把把专用扳手平时放在箱子底层只有修到对应零件时才拿出来用。这样 system prompt 可以保持精简业务知识沉淀在 skill 里还支持不同项目按需组合。1.3 一个 skill 的标准构成与工作方式skill 的具体形态在不同框架里略有差异但核心结构大同小异。一般来说一个 skill 里至少包含这几个部分技能说明文档通常叫 SKILL.md 或者 skill.md描述这个技能是干什么的、在什么场景下使用、有哪些步骤和规范可执行的辅助脚本可能是 Python、JavaScript、Shell 或者其他语言的脚本用于执行具体的操作示例文件或模板给 agent 参考的输入输出样例元信息包括技能名称、版本、作者、触发条件、依赖环境等agent 的工作方式大概是这样当你给它一个任务它会先分析任务类型判断有没有匹配的 skill如果匹配上就把 skill 说明文档读取进来再按文档里的步骤执行执行过程中如果需要调用脚本就走工具调用通道。整个过程对用户来说是自动的但这个自动背后依赖 skill 写得好不好。所以写 skill 本质上是在写“agent 的 SOP”。你写得越清晰、越具体、越可执行agent 的表现就越稳定。这也是为什么我后来把主要精力从写 prompt 转移到了写 skills 上因为 skills 才是能把个人经验沉淀下来、跨环境复用的真正载体。2. 我从零搭一套 agent-skills 库的完整方案2.1 目录怎么分、命名怎么定先说说我搭 skill 库时的目录结构。一开始我图省事把所有 skill 文件平铺放一个目录里结果 skill 一多就乱套agent 加载时也容易出现命名混淆。后来我参考了几个开源项目的做法改成按场景分类的树形结构。我现在的 agent-skills 目录大概是这样的agent-skills/ ├── README.md ├── frontend/ # 前端相关技能 │ ├── web-component-builder/ │ ├── tailwind-theme/ │ └── image-to-page/ ├── document/ # 文档排版类技能 │ ├── latex-typography/ │ ├── markdown-format/ │ └── pdf-report/ ├── media/ # 多媒体相关技能 │ ├── image-generation/ │ ├── video-script/ │ └── audio-edit/ ├── data/ # 数据处理类技能 │ ├── csv-cleaning/ │ └── excel-analysis/ └── shared/ # 共享工具脚本 ├── request.py └── file_utils.py命名方面我总结出几个原则skill 目录名全部小写、用连字符分隔比如 web-component-builder 而不是 WebComponentBuilder每个 skill 目录内自成一体入口文件统一叫 SKILL.md方便 agent 扫描识别共享脚本放在 shared 目录里各个 skill 按需引用避免代码重复。2.2 一份可直接套用的 skill 模板一个合格的 SKILL.md 应该让 agent 在读完一遍之后能明确知道“什么时候用”“怎么用”“注意事项是什么”。我把我常用的模板贴出来你可以直接抄这份结构--- name: skill-name description: 一段简洁的描述说明这个 skill 的适用场景和解决的问题 version: 1.0.0 author: your-name tags: [tag1, tag2] triggers: - 触发这个 skill 的关键词或场景描述 --- # Skill Name ## 适用场景 在什么情况下应该使用这个 skill什么情况下不应该使用。 ## 前置条件 需要什么样的环境、依赖、API Key、网络条件等。 ## 执行步骤 1. 第一步做什么 2. 第二步做什么 3. 判断依据是什么 ## 输出规范 输出的格式要求包括结构、风格、质量标准。 ## 常见错误 列出 agent 执行时容易犯的错以及如何避免。 ## 示例 给一个简短的示例帮助 agent 理解期望的结果。模板里的 YAML 头部信息很重要尤其是 triggers 部分。agent 会先读这段元信息来判断是否要加载这个 skill如果 triggers 写得太笼统agent 可能在需要的时候不触发写得太具体又会误触发。我一般是参考产品需求文档的方式写 triggers既写场景关键词也写用户意图描述。2.3 给 skill 做好“元信息”和调用声明很多人在写 skill 时忽略元信息觉得这是浪费篇幅但实际使用中恰恰是元信息决定了一个 skill 好不好用。我在元信息里会重点写几项。第一是 description要能一眼看出这个 skill 是干什么的比如“根据产品需求生成可运行的 React 组件”而不是笼统的“前端开发技能”。第二是 dependency比如“需要 Python 3.10 以上环境需要安装 requests 库”agent 在执行前能自己检查环境是否满足。第三是 output context也就是执行完这个 skill 之后应该给用户提供一个什么样的交付物或总结。还有一点非常关键但容易忽略就是 skill 的“调用声明”。所谓调用声明是指在 SKILL.md 里写清楚这个 skill 应该由 agent 来自动判断何时调用还是必须由用户显式指定。有些场景适合自动触发比如“用户提到 PDF 导出”就自动触发 latex-typography有些场景需要用户显式指定避免误操作比如涉及删除文件、修改代码库的 skill。这些看起来都是细节但写 skill 这件事本质上就是细节决定成败的活。一个元信息写得清楚的 skillagent 能准确触发写得模糊agent 就会在错误的时间和场景里突然“自作主张”。3. 手写一个真正能用的 skill以 LaTeX 排版和图片生成为例3.1 LaTeX 排版 skill 的完整实现LaTeX 排版是我写文档时的高频需求也是我第一个完整写好的 skill。写这个 skill 的初衷很简单我每次让 agent 生成论文或报告模板时它总是按照自己的理解胡编 LaTeX 语法导致编译报错。与其每次纠正不如让它按一套规范走。这个 skill 的实现思路分成三层。第一层是“规范层”在 SKILL.md 里写清楚 LaTeX 版本使用、字体编码要求、包引入规范、章节结构模板。第二层是“检查层”写了一个 Python 脚本用来检查生成的 .tex 文件里有没有常见的语法错误比如没配对的环境、错误的转义符号。第三层是“编译层”脚本调用 latexmk 编译器执行编译如果有报错就解析日志转成可读的中文提示。核心的检查脚本我存在 skill 目录下的 scripts/check_tex.py 里大致逻辑是这样#!/usr/bin/env python3 import re import sys def check_tex_file(filepath): with open(filepath, r, encodingutf-8) as f: content f.read() errors [] # 检查常见错误未配对的环境 envs re.findall(r\\begin\{(\w)\}, content) for env_name in set(envs): begin_count len(re.findall(r\\begin\{%s\} % env_name, content)) end_count len(re.findall(r\\end\{%s\} % env_name, content)) if begin_count ! end_count: errors.append(f环境 {env_name} 未配对begin {begin_count} 次end {end_count} 次) # 检查中文支持 if ctex not in content and re.search(r[\u4e00-\u9fa5], content): errors.append(文档包含中文但未引入 ctex 宏包或相关中文配置) return errors if __name__ __main__: tex_file sys.argv[1] result check_tex_file(tex_file) if result: for err in result: print([ERROR], err) sys.exit(1) else: print([OK] 检查通过可以尝试编译)我在 SKILL.md 里的执行步骤部分写得很细要求 agent 生成 .tex 文件后先运行这个检查脚本确认无误再编译。如果检查脚本返回错误必须逐个修复后才能交付给用户。这一步非常有效实测下来 LaTeX 编译的一次通过率从原来的不到四成提升到了九成以上。3.2 图片生成 skill 的完整实现图片生成类 skill 是另一个很典型的需求尤其是配合前端开发和 AI 漫剧场景时经常需要生成配图、封面、分镜。写这个 skill 的关键不是教 agent 怎么“画图”而是给它一套标准化的请求封装和参数规范。我的图片生成 skill 目录里包含两部分一部分是 SKILL.md写清楚支持的图片风格、尺寸规格、禁用内容、输出路径规范另一部分是 scripts/generate_image.py封装了调用图片生成接口的完整逻辑。脚本里的核心参数包括尺寸、风格、输出格式、质量等级我还在 SKILL.md 里给了一套“提示词转译规则”要求 agent 把用户的中文需求转成结构化的英文 prompt再传给脚本。关于提示词转译规则我的经验是多写几组对照示例。比如用户说“生成一张科技感的海报背景”agent 要转成 “futuristic tech background, blue and cyan gradient, abstract circuit lines, high detail, no text” 这种格式。没有对照示例的话agent 经常会把用户需求原封不动传过去导致生成结果一言难尽。这类 skill 还有一个坑图片生成接口通常有并发限制和超时问题。所以脚本里我加了重试和超时控制同时把生成结果保存到独立目录避免和源码混在一起。SKILL.md 里也会提醒 agent如果生成失败不要盲目重试超过三次而应该先检查参数是否合理。3.3 用 pi agent / claude code / codex 加载同一份 skill 的对比在我写 skill 的过程中最大的惊喜是发现同一份 skill 可以横跨多个 agent 框架使用。我自己实际测过 pi agent、Claude Code、Codex 和 OpenCode 四种环境加载这份 agent-skills 库的方式各有不同但核心内容基本都能复用。pi agent 是我最近用得比较顺的一个它在加载 skill 时会主动扫描指定的 skills 目录然后根据任务自动匹配。Claude Code 则更依赖配置文件的指引我需要在项目配置里手动声明 skills 的路径然后再告诉 agent 什么时候去读。Codex 对 skill 的支持方式比较直接基本上就是把 skill 的说明文档读取到上下文里所以 SKILL.md 写得越清晰Codex 的表现越好。三者的对比我整理过一张表方便你参考agent 框架加载方式自动匹配能力适用场景pi agent自动扫描指定 skills 目录较强能按任务语义触发日常开发、快速原型Claude Code配置声明 按需读取中等需要配置引导复杂项目、长链路任务Codex直接读取说明文档中等依赖文档写得好代码生成、编辑重构OpenCode插件化加载较强支持自定义触发自由度和可扩展性要求高的场景这里我想特别强调一个经验不要为了跨框架兼容而把 skill 写得过于通用。我一开始为了让所有人都能用把 SKILL.md 写得模棱两可结果哪个框架都不满意。后来改成主文档写通用规范、附录写各框架适配说明反而效果好得多。4. 现成 skills 的获取、安装与二次修改4.1 值得关注的 skills 源网站和仓库虽然自己写 skill 很有成就感但很多通用型 skill 根本没必要从零写。现在 skills 的生态已经比较丰富了GitHub 上有不少高质量的 skills 集合仓库也有几个专门的 skills 网站提供搜索和下载。我常用的几个渠道包括GitHub 上搜索 “awesome-agent-skills” 之类的主题汇总仓库、Superpower Skills 这类打包型技能库、还有各种开发者分享的独立 skill 仓库。Superpower Skills 之所以流行是因为它把很多高频能力文档处理、网页抓取、数据分析等都封装成了开箱即用的模块新手不用懂底层实现拿到就能用。但这里我要泼一盆冷水现成 skills 的质量参差不齐而且很多仓库已经停止维护。你在安装一个第三方 skill 之前最好先看三样东西commit 活跃度、仓库 star 数和 issues 里有没有人报 bug、license 是否允许商用和二次修改。这三样过关了再装不迟。4.2 手动安装 GitHub 上 skills 到 claude code 的步骤关于怎么手动装 GitHub 上的 skills 到 Claude Code很多人问过我。其实步骤并不复杂我以安装一个 LaTeX 排版 skill 为例完整走一遍流程。第一步在 GitHub 上找到目标 skill 仓库把它 clone 到本地。第二步查看仓库结构找到 SKILL.md 文件所在目录确认它的依赖脚本和环境要求。第三步把这个 skill 目录复制或者软链到你的项目 skills 目录下同时保持目录名和 SKILL.md 中的 name 字段一致。第四步在 Claude Code 的项目配置里声明 skills 路径让 agent 能扫描到新加的目录。第五步重启 agent 进行验证测试给它一个简单任务检查 skill 是否被正确加载。需要注意的是不同的 Claude Code 版本在 skills 配置上的写法有差异。老版本是直接修改 claude_desktop_config.json 这类的配置文件新版本则在项目根目录的 .claude 配置里声明。我建议你以你所用版本的官方文档为准不要照抄别人的旧配置。4.3 安装后一定要做的三件事很多人在 GitHub 上看到 skills 仓库clone 下来直接用出了问题就怪仓库不好。我的经验是安装之后一定要做三件事否则迟早踩坑。第一件事是检查依赖。很多 skill 依赖特定版本的 Python、Node.js 或者某些库你的环境里如果没有skill 一运行就报错。第二件事是试跑示例。大部分成熟的 skill 仓库都会提供 example 或者 demo 目录你先让它跑一个 demo确认链路通了再真正使用。第三件事是审查安全边界。尤其要注意 skill 会不会读取你的密钥、上传数据到外部服务、执行危险命令。我见过一个图片处理 skill 会偷偷把文件传到第三方图床这种一定要改掉。做完这三件事一个第三方 skill 才能真正算“纳入你的体系”。很多人忽略这一点后来出了问题又来问其实很多问题在安装阶段就能避免。5. 踩坑记录运行中常见的错误与排查5.1 “agent execution terminated due to error.” 这类报错怎么定位使用 agent 过程中最让人头疼的问题之一就是突然报一个 “agent execution terminated due to error.”然后整个任务就中断了。这个报错特别笼统如果你不了解 agent 的底层机制很容易一头雾水。我排查这类问题的经验是分四步走。第一步看日志。不要只看控制台的最终输出要往前翻找到报错之前的会话记录看 agent 在执行哪一步出了问题。第二步查调用链。如果 skill 脚本里调了外部 API 或子进程确认是不是这一步超时或返回了异常。第三步检查上下文长度。有时候是上下文窗口超限导致 agent 被强制终止这是非常常见的诱因。第四步逐步缩小范围。把你给 agent 的任务改成最小复现用例一次次加复杂度定位到具体触发条件。还有一个经验之谈这类问题很多时候并不是代码逻辑错误而是 agent 在执行某个步骤时产生了“它自己都解释不了的状态”相当于死机了。与其尝试修复这个状态不如让任务从上一个检查点重新开始效率反而更高。5.2 skill 之间打架命名冲突和上下文污染skill 数量多了之后大概率会遇到 skill 之间“打架”的问题。最典型的是命名冲突两个不同来源的 skill 都叫 image 相关名字agent 匹配时搞混了该用 A 的结果用了 B。另一个问题是上下文污染一个 skill 执行完环境变量、临时文件没有清理干净下一个 skill 执行时读取到了残留数据运行结果莫名其妙。我解决命名冲突的办法很简单在每个 skill 的 SKILL.md 里都加上唯一的名称前缀并且把目录名也加上这个前缀。比如我的项目名是 agent-skills那所有 skill 的 name 字段都写成 agent-skills-xxx 的格式这样可以最大限度避免和第三方 skill 冲突。至于上下文污染我强制要求每个 skill 的脚本在执行前、执行后都做环境清理。执行前清理是怕上次残留影响本次执行后清理是怕本次影响下次。这个规范写进了我所有 skill 模板的“执行步骤”里虽然多做了一点工作但长期收益非常明显。5.3 环境不一致导致的幂等性问题还有一个容易踩的坑是环境不一致导致所谓“幂等性”问题。同一个 skill在第一次运行时表现完美第二次运行却报错。很多人第一反应是代码有 bug其实往往是环境状态变了。举个例子我的图片生成 skill 第一次运行时把生成结果放到了 /tmp/agent-skills/media 目录第二次运行时这个目录已经存在脚本判断“目录已存在”就直接跳过了生成步骤逻辑逻辑上没问题但用户却是要重新生成的。这就是典型的“状态残留导致行为不一致”。解决这个问题需要在 SKILL.md 里把幂等规则写清楚哪些场景应该是“覆盖执行”哪些应该是“跳过执行”有哪些前置条件需要 agent 先检查。我在每个 skill 里都增加了一段叫“执行前检查”的内容要求 agent 先确认当前状态再决定是执行还是跳过。这个小小的规范帮我少踩了很多环境不一致的坑。6. 关于 skill 生态的几点个人判断6.1 superpower skills 这类包为什么受欢迎如果你关注 agent 开发圈一定听说过 Superpower Skills 这类打包型技能库。我一开始不太理解为什么它这么火用了一段时间之后才明白它本质上是把 agent 使用的“最佳实践”和“高质量提示词”打包出售或者开源降低了普通用户的上手门槛。我觉得这类包受欢迎有三个原因。第一它提供了一个标准化的 skill 格式用户不需要理解底层细节装上去就能用。第二它覆盖了很多高频场景比如邮件写作、会议纪要、文档总结普通人日常需求基本都能覆盖。第三它培养了一种“开箱即用”的用户习惯。大家越来越不想在配置 agent 上花时间只想有工具能“直接干活”。不过也要看清本质这类包只是帮你节省了从零开始的时间并不能一劳永逸地解决所有问题。真正贴合你业务需求的 skill最好还是自己动手写或者基于现成包二次开发这样才最有针对性。6.2 安全边界skill 也是代码写 skill 越久我越有一个强烈的感受skill 本质上是代码而且是一种会主动执行、自动调用的代码所以它带来的安全风险比普通代码更高。普通代码至少需要人手动触发运行而 skill 是 agent 自动加载、自动调用的这就意味着一个恶意的、没被检查的 skill完全可能在后台执行你不知情的操作。我见过某些第三方 skill 会读取环境变量、收集系统信息、甚至向外部服务器发送请求。这些行为如果发生在 agent 自动执行过程中用户很难及时发现。所以我现在的安全原则有三条第一不是自己写的 skill安装后必须逐行审计核心脚本第二skill 运行要尽量限制在沙箱环境里不要给它完整的系统权限第三SKILL.md 中涉及网络访问、文件删除、命令执行的步骤必须显著标注让 agent 在遇到这些操作时向用户二次确认。安全不是可有可无的事尤其是 agent 能力越来越强的现在。6.3 agent 学习路线里 skill 到底占什么位置最后聊聊学习路线的话题。很多人问我要怎么学 agent 开发要不要先学某个框架要不要直接开始写 skills。我的看法是先理解基础知识再动手写一个最简 skill然后不断迭代。我建议的学习路径大概是这样的先了解 agent 的基本工作原理包括模型调用、工具调用、上下文管理这些概念然后选择一个你日常使用最多的场景以它为切入点尝试写一个最简单、能跑通的 skill接着把 skill 接入不同的 agent 框架里做兼容测试理解各框架的差异最后才是搭建自己的 skills 库系统化管理。skill 在整个学习路线里既是“产品化”的载体也是“能力沉淀”的载体。它不像模型层那么底层、也不像应用层那么琐碎——它是一种非常巧妙的中间抽象。你今天写一个 skill明天换工具、换框架这个小知识库依然是你的资产。这种积累带来的复利效应是单纯学一个 agent 框架没法比的。写到这里我自己的一个体会是写 skills 最难的从来不是技术而是把自己脑子里零散的经验用 agent 能理解的方式结构化地表达出来。一开始你会觉得“这也要写成规则这也太麻烦了吧”但只要坚持写下去你会发现自己的思维方式都在变清晰。如果你准备动手搞一套自己的 agent-skills 库建议先从一个小场景开始别贪多先让它跑通再慢慢加。等你积攒了十几个顺手的小 skill 之后再回头看会发现之前那些翻来覆去的“调教”终于有了沉淀的形状。