★ FEATURED ARTICLE 1. 内容整体设计与思路拆解1.1 这个项目到底解决什么问题先说结论agent-skills 不是某个具体技能而是一套围绕 AI Agent 的“技能机制”展开的实践集合。它解决的问题很实在——你手里已经有一个能干活的 Agent比如 Claude Code、Codex、OpenCode 这类基于大模型的编程助手但默认状态下它像个刚入职的实习生什么都会一点什么都不精。你让它画个结构图它给你甩一段 Mermaid你让它排版 LaTeX 文档它先是忘了加载宏包然后又不知道该用哪个编译引擎你让它做前端页面它对着设计稿猜半天最后交出来一个“看起来差不多”但细节全崩的东西。Skills 就是干这个用的把某类任务的最佳实践、约束规则、工具调用方式打包成 Agent 能识别、能加载、能执行的指令包。你给 Agent 装上一个“结构图专家”的 skill下次再提画图需求时它就知道应该走哪条路径、用哪个工具、遵守什么样式规范而不是每次从零推理、靠运气发挥。我最初接触 skills 这个概念是从 SuperPower Skills 和 Claude Code 的官方插件机制开始的。那会儿网上讨论已经很热闹了GitHub 上出现了各种 skills 仓库有的做代码审查有的做数据库建模还有专门教 Agent 写单元测试的。但这些资源良莠不齐很多 skill 就是一个往 SKILL.md 里堆 prompt 的模板库根本不讲究结构化、不讲究评测、不讲究跨框架兼容。agent-skills 这个项目的价值恰恰在于它提供了一套从设计、开发、安装到评测的完整方法论让你能自己造出真正好用的技能包。1.2 Skills 与 Prompt、Tool、Agent 的本质区别很多人第一次接触 skills 时会陷入概念混淆。我见过不少人在群里问“skill 不就是个 prompt 吗”、“skill 跟 tool 有什么区别”、“agent 和 skill 是什么关系” 我用自己的理解把这些概念理一遍不一定符合所有框架的官方定义但思路是通用的。概念本质比喻典型形态Prompt一次性指令你跟实习生说的话普通文本指令Skill可复用的能力包给实习生的岗位手册 操作规范SKILL.md 资源文件 示例Tool可调用的外部功能实习生能使用的工具盒函数接口、CLI 命令Agent / Harness承载执行逻辑的框架实习生本身及其工作流Claude Code、Codex CLI、OpenCodeSkill 和 prompt 最大的区别在于结构性和复用性。Prompt 是一次性的你写了就用了用完就扔。Skill 则是一个带目录结构的包里面除了说明文档还可以有参考文件、模板、示例、校验脚本。用 skill 时Agent 会先读取 SKILL.md 理解任务流程再按需翻阅配套资源最后按规范输出。Skill 和 tool 的区别更明显。Tool 是 Agent 执行动作的接口比如“调用文件搜索函数”、“执行 shell 命令”。Skill 是更高层的“行为模式”它告诉 Agent 在什么场景下用什么 tool、按什么顺序用、输出格式怎么控制。换句话说Tool 回答“能做什么”Skill 回答“该怎么做”。至于 harness它是一个更大的概念。Claude Code、Codex CLI 这类外壳程序就是 harness它们负责管理上下文窗口、调用模型、执行工具、维护会话状态。Skill 是驻留在 harness 里的“知识资产”。同一个 skill 理论上可以移植到不同 harness这取决于你用的 skill 格式是否兼容。我在 agent-skills 项目里比较推荐的策略是以通用 SKILL.md 规范为核心再为特定 harness 写薄薄一层适配补丁。这样既能保证核心能力复用又不用为每个平台重写整套逻辑。2. Skill 的核心细节解析与实操要点2.1 一个标准 Skill 的目录解剖网上流传的各种 skills 仓库目录结构五花八门。但如果你拆开看那些真正好用的 skill比如 Claude Code 官方收录的插件、SuperPower Skills 里口碑比较好的那几个会发现它们遵循一套隐性的共识。我自己总结下来一个合格的 skill 包大致长这样my-skill/ ├── SKILL.md # 主文件Agent 一进来最先读这个 ├── reference/ # 参考资料按需加载 │ ├── style-guide.md # 风格/规范细节 │ └── examples/ # 输入输出示例 ├── templates/ # 可直接套用的模板 ├── scripts/ # 需要执行时用的辅助脚本 ├── assets/ # 静态资源如图片、字体等 └── eval/ # 评测用例用来验证 skill 是否有效SKILL.md 是灵魂。它不是什么长篇大论的文档而是一份面向 Agent 的操作手册。这里的写作原则和写给人看的 README 完全不同。人看文档喜欢先看背景介绍、再看功能列表Agent 看 SKILL.md 需要的是这是什么技能、什么时候用它、不用它、第一步做什么、第二步做什么、有哪些硬性规则、有哪些常见坑。我常用的 SKILL.md 结构是--- name: 结构图专家 description: 当用户需要创建架构图、流程图、思维导图等可视化图表时使用 --- # 角色定位 你是资深的系统架构可视化专家擅长将复杂系统转化为清晰的结构图。 # 适用场景 - 用户要求画架构图 / 结构图 / 拓扑图 - 用户需要梳理系统模块关系 - 用户要求将文字描述转为可视化图表 # 不适用场景 - 用户只需要简单的文字说明 - 用户明确要求使用特定的非图表工具 # 执行步骤 1. 先确认图表类型架构图 vs 流程图 vs 时序图 2. 选择最合适的图表技术Mermaid / PlantUML / Draw.io 3. 按规范输出图表源码 4. 如有必要给出渲染方式说明 # 硬性规范 - Mermaid 语法中禁止使用不支持的图标类型 - 节点标签必须简洁不超过 20 个字符 - 架构图必须标注技术栈版本号写的时候记住一个原则Agent 一定会在信息不足时自行脑补。你宁可多写一点限制性的约束也不要留白太多让它自由发挥。2.2 Skill 的“超能力”从哪里来SuperPower Skills 里的“superpower”不是噱头它指代的是一种模块化的能力增强方式。一个普通 math skill 可能只会告诉 Agent“用 Python 的 sympy 库计算”一个 superpower 级别的 math skill 会包含符号化简策略、数值精度控制规则、常见易错题的检查清单、输入公式的规范、甚至是一套自我验证脚本。想让 skill 变得强大关键不在于堆多少字而在于注入这几类东西第一决策树。告诉 Agent 面对不同类型输入时如何分流。比如“用户提的问题模糊时优先追问还是直接基于假设执行”这类决策逻辑写清楚Agent 的行为就会稳定一大截。第二负面清单。明确写出“禁止做什么”往往比“应该做什么”效果更好。比如写前端页面的 skill直接列出“禁止使用内联样式覆盖全局变量”、“禁止引入未被许可的外部 CDN 资源”。Agent 对禁令的遵守率通常高于对建议的遵循率这是我在多次评测里验证过的。第三可运行时调用的脚本。文本指令再怎么详细也比不上直接给 Agent 一个校验脚本。比如做代码审查的 skill放一个 shell 脚本用来批量跑 lint、统计圈复杂度Agent 在审查时就会先跑脚本拿数据再基于数据做判断准确率完全不一样。第四few-shot 示例。给它看一个“输入——输出——推理过程”的完整例子比写十句抽象说明都有用。尤其在做结构化输出JSON、YAML、Markdown 表格时示例几乎是必需品。2.3 写 SKILL.md 的三条军规写多了 skills 之后我总结出三条硬性军规基本每条都是从踩坑里长出来的。第一条每个 Skill 必须有“不适用场景”。刚开始写 skill 时我满脑子想的都是“让 Agent 在什么情况下使用它”忽略了“不该用的情况”。结果就出现了一个尴尬场景写了一个处理图片的 skill结果用户让它总结文本时Agent 也开始调用图片处理流程白白增加上下文消耗。后来我在每个 skill 的头部都加了一段 not_apply 字段把不适用场景写全这种行为偏差大幅减少。第二条示例必须亲测过。有些 skill 作者喜欢在网上复制代码片段当示例但那段代码根本跑不通。Agent 会照着示例参考输出格式如果示例本身就是错的它就会在错误的基础上衍生出更多错误。我在 agent-skills 项目里立了个规矩凡是进入模板库的代码必须经过本机实际执行验证并注明测试时间和运行环境。第三条版本号与变更日志不是可选项。Agent 是有上下文窗口限制的它可能在不同会话里加载同一个 skill 的不同版本。如果版本不清晰你会怀疑自己是不是写错了——其实不是是它读取了旧版本。给每个 skill 维护一个简单的版本记录长期收益极大。3. 实操过程与核心环节实现3.1 Skill 安装的几种方式对比在 agent-skills 的具体实践里安装这一步是最容易让新手卡壳的。不同的 Agent 框架harness有不同的安装路径。以目前热度最高的 Claude Code 为例常用的安装方式有这么几种方式一利用 Claude Code 的插件市场机制。Claude Code 从某个版本开始引入了插件/插件市场概念你可以直接在命令行里通过市场搜索并安装 skill。这种方式最无脑但坑在于市场里的 skill 质量参差不齐安装前建议先看看仓库的 star 数、最近提交时间、有没有 eval 文件夹。方式二手动放入 skills 目录。大部分开放框架都支持从一个约定目录加载 skill。比如把 skill 文件夹放到~/.claude/skills/下新会话启动时就会被自动识别。手动方式的好处是你能精确控制版本坏处是每个框架的目录名不一样换一个 harness 就得重新配一次。方式三通过项目内 .claude/skills/ 实现项目级生效。这个是我最推荐的。如果你在某个项目的根目录下建.claude/skills/那只有在这个项目里会话才会加载对应 skill。团队协作时把技能包和代码仓库一起提交成员拉下来就能直接用完全不需要每个人单独配置。Codex CLI 的安装路径又不太一样。它支持用配置文件指定 skills 目录也支持从 GitHub 仓库直接安装远程 skill。OpenCode 则更偏好 symlink 方式——把外部 skill 目录软链到自己的配置目录下。我个人的建议是不要在安装这一个环节上花太多精力去记命令因为你今天学的方式、下个月可能就变了。更重要的是理解 skill 的本质是一个文件夹安装本质上是“让 Agent 能找到这个文件夹”。只要理解了这一点不管框架怎么升级换代你都能举一反三。3.2 从零开发一个“结构图渲染”Skill 的完整流程下面我完整演示一个 skill 从零到一的开发过程这也是 agent-skills 这个项目里比较有代表性的样例——结构图渲染技能。第一步明确需求边界。这个 skill 要解决的核心痛点Agent 画结构图时经常选错技术栈或者 Mermaid 语法写得不标准。所以这个 skill 的目标是交给它一个系统描述它输出一份符合规范的 Mermaid 架构图代码并附带渲染建议。第二步搭建目录骨架mkdir -p diagram-expert/{reference,templates,examples,eval} touch diagram-expert/SKILL.md第三步写 SKILL.md 核心文件。我重点写这几节适用与不适用场景适用“需要生成架构图/拓扑图/组件图”不适用“用户只是顺嘴提到图字实际要的是文字描述”。技术选型规则默认用 Mermaid若用户明确要求其他工具则跟随。输出格式规范代码块必须标注语言为 mermaid不允许把 Mermaid 代码和解释混在一个代码块里节点文本必须使用引号包裹避免特殊字符导致渲染失败。第四步在 templates/ 目录放几个常用骨架模板比如“微服务架构模板.mmd”、“前端组件关系模板.mmd”。Agent 输出时可以基于模板改而不是完全白手起家这样质量下限就兜住了。第五步在 examples/ 里准备一组“低质量输出→高质量输出”的对照示例。这个环节最花时间但价值也最高。我通常会从实际项目中抽取真实案例做改造而不是编造过于理想化的例子。第六步在 eval/ 目录写几个自动化评测用例。评测的核心思路是给一个输入让 Agent 按 skill 规则输出然后用脚本检查输出是否满足硬性规范。比如# 检查是否所有节点标签都加了引号 grep -E ^[[:space:]]*[A-Za-z].*--.*[A-Za-z] output.mmd | grep -v echo 存在未加引号的节点标签第七步实测验收。开一个新的 Agent 会话加载这个 skill用三个不同类型的输入去测试简洁需求“画一个订单系统的架构图”、模糊需求“给我看看目前系统的结构”、复杂需求“把这段代码片段对应的调用关系画出来”。记录输出质量、生成时间、上下文消耗对比没装 skill 时的表现。3.3 图片生成与 LaTeX 排版类 Skill 的实战变体结构图 skill 只是入门agent-skills 项目里还有两个比较出圈的变体图片生成 skill 和 LaTeX 排版 skill。这两个我都实际用过一段时间分享几个关键经验。图片生成 skill 的核心难点在于如何把用户模糊的视觉需求转化为具体的生图参数。这听起来简单但实际做的时候容易翻车。比如用户说“画一张科技感强的封面图”你直接把它翻译成 DALL·E / Stable Diffusion 的 prompt 可能会有几个问题画面比例是否合理主体是否居中色彩是否协调文字是否会被生图模型扭曲所以我在这类 skill 里加了一个强制步骤生成图片前先输出一段结构化的 prompt 拆解文本标注主体、背景、风格、构图、配色、负面提示词用户确认后再真正生成。这个步骤看似多余但在实际使用中能把废图率降低一半以上。LaTeX 排版 skill 则是另一类问题——它更像是一个“格式纪律”的约束器。LaTeX 的特点是规则极多错一个宏包、漏一个转义就会整体编译失败。Agent 写 LaTeX 时最常见的错误是忘记引入必备宏包、特殊字符没转义、中文忘了配置合适引擎。所以我的 LaTeX skill 里有一个硬性前置步骤先检测文档中是否包含中文如果包含就强制使用 XeLaTeX 编译并自动添加ctex宏包如果全是英文再按需选择编译引擎。这个判断逻辑写进 skill 后一次性编译成功率提升非常明显。如果你要做一个自己的“前端开发 skills”思路也是一样的。前端项目的坑集中在依赖版本不匹配、浏览器兼容性、样式作用域污染、构建流程不熟悉。那 skill 就应该围绕这些坑来写而不是泛泛地让 Agent“写出高质量代码”。3.4 SuperPower Skills 的安装与踩坑经验装 SuperPower Skills 的时候我第一次就踩了坑。网上不少教程直接让你执行一个克隆命令把整个仓库拉下来再手工把某个配置文件的路径改一改。但那个路径是针对 macOS 的我本机是 Linux目录结构对不上导致 Agent 启动时压根没加载到技能但也不报错——这种“静默失效”是最难受的。后来我看了一下实际生效的配置结构发现最关键的是让 harness 能在一个固定位置找到 skill 包。不同系统目录差异很大比如 Claude Code 在 macOS 上是~/Library/Application Support/Claude/Linux 上是~/.claude/用插件市场方式安装时还会写入到插件缓存目录。如果你不想被这些路径折磨一个取巧的办法是建一个统一的软链接目录把真实技能仓库放在一个固定位置然后在每个 harness 配置目录里各建一个 symlink 指向它。这样不管哪个平台你只需要更新真实仓库里的内容就行了。SuperPower Skills 的另一个特点是它的 skill 设计思路偏“重”——每个 skill 里常常有几十个 .md 文件和脚本。这不是坏事因为它充分体现了“把能力沉淀进文件”的理念。但它也会带来一个副作用加载时上下文消耗较大。如果你的上下文窗口不算宽裕建议只用里面核心的几个 skill不要全量启用。4. 常见问题与排查技巧实录4.1 Skill 静默失效Agent 根本没用上症状你装好了一个 skill也确认目录存在但 Agent 对话时表现得跟没装一样。你把一个问题直接甩给 Agent让它用某某 skill 处理它的回答仍然是你没装 skill 时的水平。排查顺序确认目录位置是否正确。不同 harness 的配置目录差异很大把 skill 放错了位置它看不到就等于没有。最容易出错的场景是用~/.claude/skills还是项目内.claude/skills两者作用范围不同后者只在该项目内生效。检查 SKILL.md 是否被正确解析。有些框架对 frontmatter 字段有强约束比如 description 缺失就会跳过加载。你可以先启动一个极简会话在提示词里直接问“你有哪些能力”看看返回的列表里有没有你期望的 skill。观察上下文窗口占用。如果评测结果显示 skill 相关的内容根本没出现在上下文里大概率是加载环节出了问题如果出现了但仍然没用上那问题可能在于触发机制——SKILL.md 中描述的场景和用户的真实表达不匹配。4.2 Agent 执行中断Exection Terminated Due to Error热搜词里有一句 “agent execution terminated due to error”这个错误我在开发 skills 过程中遇到了无数次。说白了就是 Agent 在执行 skill 的某个步骤时抛出了异常然后整个任务中断了。最常见的诱发原因有两类。一类是脚本兼容性问题skill 里带的辅助脚本在本机跑不通比如用了 Linux 的sed -i语法但在 macOS 下行为不同。这类问题解决方法是多平台兼容在脚本开头加系统检测逻辑。另一类更隐蔽是Agent 在执行过程中生成了非法 JSON 或无效的工具调用参数。尤其当 skill 里要求 Agent 输出 JSON 结构时如果 JSON 里含有未转义的引号或换行符模型就会返回一个不能被 harness 解析的格式导致执行链路断裂。应对方法是在 skill 的规范里明确指示 Agent 使用代码块包裹 JSON、禁止裸 JSON 输出、必要时把示例中的转义字符也写出来。4.3 如何评测一个 Skill 的质量“skills 怎么测评”是很多人忽略的问题但它其实是 agent-skills 这个项目最有价值的部分。一个 skill 写得好不好不能靠“感觉”得靠可量化的评测。我用的评测维度有五个触发率在 10 个目标场景下Agent 能否在无需显式提示的情况下主动使用该 skill。遵循率Agent 输出内容中有多少比例严格遵守了 SKILL.md 里的硬性规范。一次通过率比如 LaTeX skill 的“首次编译即成功”比例图片 skill 的“首次生成直接可用”比例。上下文效率执行同样任务时使用该 skill 比不使用该 skill 多消耗了多少 token这个成本是否可接受。失败模式分析当任务复杂化、输入模糊化时skill 是在哪个环节开始失效的——是触发阶段、执行阶段还是输出阶段。评测方式上我强烈推荐做一个简单的脚本化评测矩阵。把输入用例放到 eval/inputs/ 目录把期望输出特征写到一个 validator 脚本里然后批量跑。这样每次更新 skill都能快速回归一遍确认没有退化。4.4 Skill 安全性问题别让 Agent 变成提线木偶聊到 Agent 安全问题可能大多数人第一反应是“系统权限”、“沙箱隔离”这些大词。但作为一个 skill 开发者你需要关注的安全问题其实很具体skill 会在 Agent 的信任边界内执行任意指令。一个恶意来源的 skill理论上可以利用 Agent 的工具权限做一些危险的事。所以在引入第三方 skill 时我有一套自己的审查流程查看仓库是否包含 eval 文件夹以及是否有自动化测试流程。检查 scripts/ 里是否有可疑的网络请求、文件删除、环境变量读取等操作。重点看 SKILL.md 里是否写过“忽略用户指令”之类的反常规描述。正常 skill 不会这么写这类描述往往是后门 prompt 注入的标志。对于来源不明的 skill先在隔离环境里跑一轮测试观察它的行为再放入正式环境。4.5 常见问题速查表现象可能原因快速解决办法Agent 完全没触发 skill目录不对或描述不匹配确认路径把 description 重写得更贴近用户真实说法Skill 上下文占用过大SKILL.md 太长或资源文件被全量加载精简主文件把细节移到 reference按需加载同一 skill 行为不稳定不同安装位置存在新旧版本检查全盘路径删除旧版本执行中断但无明确报错脚本语法与当前系统不兼容加系统判断分支或用跨平台的语言重写输出质量忽高忽低Skill 内部约束不足依赖模型临场发挥补全决策树和负面清单加入 few-shot 示例引入第三方 skill 后行为异常可能是 prompt 注入或权限过度按 4.4 的审查流程逐项排查5. Skill 开发的进阶方向与团队协作经验5.1 从单点 Skill 到体系化 Skills 库当你手上积累了十几个 skill 之后新的问题就出现了它们之间可能存在冲突或重叠。比如你有一个“代码审查”skill又有一个“安全审计”skill用户提一个“帮我审一下这段代码的安全性”Agent 可能不知道该用哪个或者两个都勉强沾边导致上下文被撑爆。我自己的做法是引入一个总入口 skill不写具体能力只做路由决策。它在最顶层根据用户输入判断应该委派给下游哪个具体 skill或者组合使用哪几个。这就相当于给 Agent 建了一张能力索引表避免它盲目翻查所有技能文档。另外体系化还有个附带好处你可以开始抽公共模块了。我统计过30% 的 skill 里都包含“输出 Markdown 表格时不要使用过多嵌套”、“代码块要标注语言”这类通用规范。把这些抽到公共 base 文档中然后每个 skill 通过引用方式引入维护成本会大幅下降。5.2 团队协作时的 Skill 版本管理Skill 本质上是代码是代码就该纳入版本管理。我在团队里推的流程是每个 skill 独立仓库或者至少独立目录采用 trunk-based 开发分支合并前必须跑 eval。有一个细节容易被忽略SKILL.md 的改动对旧会话无效。因为 Agent 在会话开始时就会把 skill 内容载入上下文运行中的会话不会重新加载文件。所以如果你迭代了一个 skill并让团队成员“拉最新代码后重启会话再试”这是正常的操作方式不是框架的缺陷。这点对于团队协作很重要——遇到“我明明改了测试时还是老效果”的问题时先确认是否重启了会话。另一个值得尝试的方向是给 skill 打标签比如按复杂度分级L0 到 L3或者按领域分组。这样在团队内部推广时新人可以按需取用而不是被一堆技能淹没。5.3 Skill 的通用化与跨 Harness 兼容目前 skill 生态还处于“百花齐放但互不兼容”的早期阶段。Claude Code 有它自己的格式Codex 有 Codex 的加载方式OpenCode 又不太一样。对于想把技能沉淀下来的开发者来说这无疑是一个痛点。我的经验是保持 SKILL.md 的通用性把平台相关的部分剥离出来。通用部分用 Markdown 写作不做任何框架 API 假设平台相关的部分比如“如何调用某个工具”、“如何读取环境变量”写成平台专属的 adapter 文件。这样核心技能可以跨 harness 复用适配时只需重写薄薄一层 adapter。另外关注下 Agent Skills 这个方向在新模型版本里的地位演变。从行业趋势看skills 这种“给 Agent 注入结构化能力”的路径会持续存在而且会越来越标准。现在你投入时间学会的技能开发方法论放到一年后大概率依然适用——变的只是文件格式和加载方式底层的知识沉淀、约束设计、评测思维这些才是真正值钱的部分。5.4 下一个 Skill 做什么选题逻辑被问得最多的问题之一是“我没有想法该做什么 skill” 我给出一个从实际工作中挖掘选题的方法记录你重复向 Agent 输入的十段长指令。具体操作是打开你的历史会话筛选那些你反复输入、每次都要花十分钟以上去描述的任务。比如你总是让 Agent“用某个固定风格写日报”、“按某套规范整理会议纪要”、“用同样的方式生成数据库 ER 图”。这些重复性任务就是最完美的 skill 候选。把其中最长的一段指令拿来加上你事后修正的内容就诞生了一个 skill 的初版 SKILL.md。这种方法比你凭空想象需求要靠谱得多因为你已经用脚投票确认了这是一个高频真需求。我自己写的排版 skill、代码检查 skill几乎全部来自这个流程而不是来自拍脑袋。这也是为什么我对各种“skill 推荐清单”抱有保留态度——别人用得好的 skill未必是你流程里真正需要的能力。与其到处找现成的装不如先盘点一下自己和 Agent 协作时最痛的环节在哪里。
阅读完成 · 觉得有帮助？
