这段时间把 Claude 的 agent skills、Codex 的 skills 生态、GitHub 上那些热门 skills 仓库都翻了一遍又拉着几个常见的 skills 下载平台实测了整个周末。绕了挺多弯路也踩了几个特别典型的坑。这篇东西不做概念科普直接讲我在实际使用里对 skills 的理解——它到底解决什么问题、常见平台怎么选、怎么装、怎么写、怎么排查。先说结论skills 这个事本质上是把告诉 agent 怎么干活这件事从一次性对话提示词变成了可复用、可分发、可版本管理的工程化资产。它的价值不在技术多高深而在信息组织方式的变革。下面我按实际动手顺序展开聊。1. 重新认识 skillsagent 能力的最小复用单元1.1 skills 到底解决什么问题你要理解 skills得先理解 agent 在没有 skills 时有多痛苦。平时我们用大模型写代码、写文案思路是在对话里把需求描述清楚。但 agent 不一样尤其是 Claude Code、Codex CLI 这种跑在终端里的编程型 agent它会自主决定调用哪些工具、按什么顺序调用、看到结果后怎么调整。问题来了如果 agent 没有任何结构化指引它面对一个给我把登录页改成响应式布局的需求时可能东试一把西试一把改完左侧边栏忘了右侧卡片调完颜色忘了字号。skills 解决的就是这个问题。它是一个定义好的能力包里面包含了对某项任务的详细操作规范、评价标准、常见坑位、参考示例甚至可以直接调用的脚本。agent 在遇到相关任务时会把这份操作手册读进去然后照着规范来干。我举一个具体例子。你给 agent 一个生成视频分镜的需求如果没 skills它大概率会输出一个泛泛的分镜模板镜头号、景别、台词、画面描述都有但节奏松散、切分不合理。如果你装了一个分镜 skills里面会写明故事结构怎么拆解、每个节拍控制在几秒、景别变化频率、转场逻辑、文案与画面的对应规则。agent 拿着这套规范去生成产出的东西立刻有了专业感。这也解释了为什么网上skill 推荐热度这么高——它本质上是把高手的经验模板化、打包化了。1.2 生态里的几个关键玩家市面上提到 skills至少有四类完全不同的东西这个非常容易混淆。第一类是 GitHub Skills。这是 GitHub 官方做的一套学习路径系统通过仓库内的交互式课程教你怎么用 GitHub 功能比如 Actions、Copilot、Codespaces。它的本质是教程 练手环境跟 agent 技能没有直接关系。第二类是 Claude Agent Skills。Anthropic 在 Claude Code 和 API 层面推的能力框架把技能定义成 SKILL.md 加附属脚本、资源的目录结构按需加载。这是目前社区讨论度最高、生态最活跃的方向。第三类是 Codex Skills。OpenAI 的 Codex CLI 也支持类似机制。它更偏向软件开发场景从工程流程、代码规范到命令行操作都能封装成技能。第四类是社区自发的 skills 集合比如 superpower skills、各种 awesome-skills 仓库、独立博主做的付费/免费技能包。这中间的品质差异极大需要自己甄别。还有不少产品在往这个方向靠比如 Reasonix、Trae、Cursor 里的自定义规则体系其实都借鉴了同一套思路。理解这个生态后你会发现一个明显趋势未来 agent 的竞争力很大程度上取决于它的技能仓库够不够丰富、够不够专业。2. 核心机制拆解一个 skill 文件里到底装了什么2.1 SKILL.mdagent 的操作手册几乎所有主流 skills 框架核心入口都是一个 Markdown 文件通常命名为 SKILL.md。它的作用不是给人类看的文档而是给 agent 看的操作手册。我见过不少人第一次打开一个 skill 文件夹时很疑惑就这么个 Markdown这里面的内容也就比普通提示词长一点而已。但关键在于SKILL.md 的书写方式跟普通提示词有本质区别。普通提示词是对话时临时写的需求描述而 SKILL.md 是按照结构化规范写的、面向复用场景的指令集通常包含以下区块技能名称与用途描述让 agent 判断什么情况下该调用它适用场景与禁用场景避免误用输入参数说明明确需要哪些信息执行步骤按顺序列出操作流程质量标准即做完后怎么验收常见错误与规避方法示例输入输出或参考模板这个格式其实是把师傅带徒弟的过程文本化了。agent 每次干活前读一遍干活中按步骤执行干完后按质量标准自查。2.2 元数据与依赖声明SKILL.md 文件本身还有一个常见写法就是在文档开头放 YAML 格式的元数据块。它定义技能的名字、描述、版本可能还有作者和依赖关系。这块信息非常重要因为 agent 载入技能时会先根据描述判断是否与当前任务匹配。如果描述写得含糊比如a useful skill for codingagent 可能压根不知道什么时候该用。反过来如果描述里写清楚for building HTML/CSS responsive layout with mobile-first approach匹配准确率会高很多。依赖声明则解决更复杂的问题。有些技能不只是文本指令还需要外部脚本、配置文件、数据模板的配合。比如一个前端组件调试技能可能会附带一个检查页面可访问性的 Node 脚本一个分镜生成技能可能会附带几个景别示例图。因此 SKILL.md 的元数据或正文中必须说清楚这些依赖文件的路径和使用条件。2.3 为什么说 skills 是提示词 工具的混合体我一开始也以为 skills 就是把大段提示词存成文件装好之后让 agent 每次对话都记住。但用了几周后我发现它比普通提示词精妙的地方在于按需加载。agent 在每次请求时不会把所有技能内容读一遍那样既消耗 token又增加上下文噪声容易让模型跑偏。正确的机制是agent 根据任务描述从技能列表中检索出最相关的 1-3 个技能然后完整读取这些技能的 SKILL.md。这相当于把几本工具书放在书架上需要哪本就抽哪本而不是把所有书的内容全背下来干活。这个设计逻辑非常重要它让技能库可以无限扩充而不拖累日常使用。你自己写技能的时候也要注意区分技能说明书和参考手册的关系。说明书要短平快讲清步骤参考手册可以长但要通过路径引用让 agent 按需读取。3. 实操落地从市场下载到本地配置的全流程3.1 常见 skills 下载平台怎么选先说平台。因为 skills 还是个新生事物没有像 App Store 那样统一规范的市场所以选择平台时你得先知道自己要装进哪个 agent。GitHub 仓库这是最核心的分发渠道覆盖面最广。好处是版本管理清楚、能看到源码和问题反馈坏处是你得自己甄别质量而且内容太多搜索效率低。官方市场与目录Anthropic 官方有 skills 目录OpenAI 对 Codex 也整理了一套示例。这些经过初步审核稳定性好但数量有限。第三方社区站比如 superpower skills 这类专门目录站会有分类、推荐机制用起来方便。但更新速度参差不齐且要注意授权条款。国内开发者整理的导航仓库在 GitHub 上搜awesome claude skills或codex skills list能找到很多集合帖资源密度高适合逐个查阅。我的建议是从官方市场或大型集合站起步装 2-3 个广泛好评的技能先用起来再根据你实际的工作流找细分技能。不要一上来就全量拉取几百个技能管理成本和识别成本都会失控。3.2 在 Claude 环境里安装 skills以我常用的 Claude Code 环境为例安装过程分成三步。第一步确定技能存放目录。Claude Code 对 skills 的扫描路径通常是~/.claude/skills/下的子目录具体路径会随版本变化建议用/skills命令查看当前版本支持的位置。每个技能必须独占一个子目录目录名一般用短横线分隔的小写单词比如frontend-coding。第二步把整个技能目录克隆或复制进来。这里有个极易踩坑的地方技能目录里不要有多余的嵌套SKILL.md 必须直接放在该技能子目录的根下。如果解压后得到一个多套一层的目录agent 就识别不到。第三步重启 agent 会话或运行重新加载命令。大多数 CLI 工具会在新会话启动时自动扫描技能目录但如果你当前已有一个运行中的会话加载新技能不会立即生效需要重开对话。我在实测中还发现某些 agent 对技能目录的读取权限有要求。克隆下来的技能文件如果是 root 所有或权限过严会导致读取失败。最简单的方式是用普通用户身份克隆并确认目录有可读权限。3.3 在 Codex 环境里安装 skillsCodex CLI 的 skills 机制跟 Claude 有点类似但细节不同。它通常把技能放在项目级别或用户级别项目级意味着只对该仓库生效用户级则全局可用。我建议能放项目级就放项目级。这样不同项目可以绑定不同技能集合避免全局技能过多导致检索干扰。你开发电商前端项目就只加载前端相关技能你写分镜脚本就单独建一个内容创作项目目录只放分镜、文案类技能。安装完成后可以手动触发一次技能相关指令来验证。比如你装的是一个后端 API 设计技能直接在对话里要求 agent 按这个技能来设计一个登录接口看看它是否识别并采纳了技能中定义的步骤和规范。如果它完全无视了技能内容多半是路径或命名出了问题而不是技能写得不好。3.4 安装后怎么验证技能生效验证这一环很多人会跳过但我建议别省。最快捷的验证方式是查看 agent 的上下文窗口或调试日志。以 Claude Code 为例你可以在调试模式里看到它加载了哪些技能文件。如果你看不到加载记录大概率路径不对。另一个有效方法是做一次技能前后对比在没有技能的情况下让 agent 完成一个任务然后装上技能再让它做同款任务对比输出质量。这个方法也适合你在社区里讨论某个技能到底有没有用时给出有力证据。我自己验证分镜技能时对比过一次前版输出是流水账后版输出有了镜头节奏设计差别一眼可见。限制 | 原因 | 规避方式 路径不对 | 目录多套一层或 SKILL.md 不在根目录 | 严格按文档整理目录 描述模糊 | 元数据里技能描述不够具体 | 重写描述明确触发场景 权限不足 | 克隆文件不可读 | 检查目录权限普通用户运行 新技能未加载 | 会话未重启 | 重启会话或手动 reload4. 自己动手写 skills一套可以复用的模板4.1 设计技能的三层结构从会用别人的技能到写自己的技能中间最关键的是理解技能设计结构。我习惯把技能拆成三层触发判断层、执行流程层、质量校验层。触发判断层解决的是什么时候该用这个技能的识别问题。对应的就是 SKILL.md 开头的 description 字段和适用场景描述。这一层写得越精准agent 越不容易误调用。执行流程层是整个技能的核心。它要回答打开一个需求后具体按什么顺序做什么。一个常见的误区是只写目标不写步骤比如生成一个精美的登录页没有任何中间步骤agent 还是得靠瞎猜执行。正确的做法是把流程拆成一系列可执行动作先读取需求文件再提取页面区块然后逐个敲定布局、色彩、字体、交互最后输出完整代码。质量校验层解决做完了怎么验收的问题。你需要给 agent 一个自检清单让它输出前自己过一遍。比如前端技能里的检查清单会有页面是否有移动端断点、标签语义是否完整、图片是否带 alt、按钮是否有 focus 状态。有了这一层产出的稳定性会显著提升。4.2 一个实战模板示例前端页面生成技能我拿自己常写的一个前端技能来做示例你直接抄结构改内容就能上手。技能目录叫frontend-page-builder里面就一个SKILL.md文件。技能内容的大致框架--- name: frontend-page-builder description: Build responsive HTML/CSS pages with mobile-first approach and accessibility checks. Use when user requests a landing page, dashboard, or UI component. --- # Frontend Page Builder ## Purpose Creates production-grade static pages using semantic HTML and modern CSS. ## Input - page goals, content blocks, reference links - target device ratio and style preference ## Steps 1. Parse requirements and list page sections. 2. Establish a CSS reset and design tokens (colors, spacing, radius). 3. Build sections one by one in semantic HTML. 4. Apply styles with mobile-first media queries. 5. Validate accessibility with the checklist below. ## Quality Checklist - Contains only one H1 per page - Every image has an alt attribute - All buttons have focus-visible styles - Layout adapts below 480px width - No horizontal scroll on mobile你不用把每个细节都写得像代码注释一样冗长但关键决策点必须明确。我写技能的技巧是想象你在给一个很聪明、但没做过这行的实习生写操作手册。他会做什么傻事你就在常见错误里写什么。4.3 测试与迭代的实操方子写完技能后不要直接拿去正式任务上用先在测试目录里跑 2-3 个真实小任务观察它哪里被误解、哪里执行不动。这个过程跟调 prompt 很像但反馈更结构化因为你能从 agent 的步骤日志里看到它的决策链。有朋友问我要不要给技能加版本号。我的答案是要而且最好在元数据里写清楚。技能是会被反复迭代的版本号能帮你区分两版之间的效果变化。我自己用v0.1.0起步实验性修改直接改主版本稳定后打 tag 同步到 Git。迭代节奏上我发现最有效的做法是每跑完一个任务根据真实输出反推哪里需要给 agent 更多约束或更多示例。有时候加一句不要让卡片溢出容器这种具体规则比写十句空泛的注意美观管用得多。这套方法坚持两周后你写的技能会越用越顺手。5. 常见问题与排查技巧实录5.1 为什么加载了技能agent 还是不听话这是我见过最多的问题。不少人装了热门技能后发现agent 的表现没有明显变化于是觉得 skills 是个噱头。实际情况通常是触发判断出了问题。agent 决定是否用某个技能依据的是任务描述和技能 description 的匹配度。假如你装的技能 description 写的是Create beautiful landing page design with modern CSS techniques你给 agent 的指令却很含糊比如帮我做个页面吧它可能不会主动想起这个技能。解决的办法有两个方向一是在需求描述里明确指出使用 frontend-page-builder 技能来完成这个页面二是把技能 description 写得覆盖更多泛化表达让 agent 更容易联想到。两者都做了效果最稳定。还有一种容易被忽略的情况agent 的上下文里技能内容太多把它淹没了。一些大型技能附带大量示例代码agent 读取时会被细节带偏忘记主线流程。这时建议把示例代码从 SKILL.md 里拆出去作为独立文件用路径引用核心文档只保留流程和规则。5.2 路径、权限与文件编码的坑我知道有人卡在安装环节半天最后发现是目录套娃的问题。技能整个文件夹解压后如果最外层多了一层同名目录agent 扫描时就会出现找不到技能的结果。解决办法很原始但有效打开目录树看一眼确认 SKILL.md 在技能根目录下而不是在深层嵌套里。另一个高频坑是文件名大小写和编码。SKILL.md 这几个字母大小写必须完全一致写成 skill.md 或 Skill.md 都会导致识别失败。文件内容如果用带 BOM 的 UTF-8 编码解析时可能报错最好用无 BOM 的 UTF-8。Windows 上尤其要留意换行符问题尽量让 Git 自动转换 LF/CRLF避免意想不到的解析异常。权限问题在共享服务器上更普遍。如果你有 root 权限操作时别偷懒用 root 直接克隆技能到用户目录会导致普通用户读不了。正确做法是用运行 agent 的普通用户身份克隆确保文件所有权一致。5.3 下载平台上的质量诈骗陷阱技能市场鱼龙混杂我在实测里已经见到了好几类问题。一类是改名搬运。把同一份开源技能换个名字、加个封面就挂到社区站上收取积分或收费下载。避免办法很简单下载前在 GitHub 上搜索技能关键字找到原仓库比对文件内容内容一致的选原仓库至少能保证更新来源。一类是参数注水。SKILL.md 写得很长、很唬人实际上大量内容都是大而化之的正确废话执行步骤不严谨。对这种技能我有个快速的筛选技巧看常见错误和质量清单两个部分。如果它们写得足够具体连边界情况都提到说明作者真在实战中打磨过如果只有确保代码质量注意用户体验这种空话果断放弃。还有一类是安全性问题。有些技能会附带脚本安装后自动执行。我建议所有从第三方下载的技能在运行前先打开脚本文件看清它做了什么操作。会不会向外部发送数据有没有访问敏感目录这两点确认完毕后再在测试环境里跑一次确认安全性后再用于正式工作。你可以通过数字签名或社区反馈来辅助判断。GitHub 仓库如果有 star 数、issue 讨论和 release 历史可信度会高不少独立博客发布的技能包则要看是否有明确的更新记录和用户评论。遇到那种来源不明、发布者没有任何历史记录、页面只有一张截图和下载按钮的资源我强烈不建议碰。6. 一点个人经验作为收尾最后分享一点我自己的体会。技能这东西看起来是给 agent 用的但写多了你会发现它其实是逼着你自己重新梳理工作流。把怎么做前端页面怎么拆解分镜脚本怎么写技术方案这些平时靠脑子和习惯完成的事用清晰、可执行的语言描述出来本来就是这个时代很值得做的一件事。而且一旦你开始用技能管理自己的 agent你对模型的信任度也会跟着改变。以前我总觉得 agent 输出随机性太强给不了确定性交付现在我会先为任务配好技能再让 agent 启动输出稳定性和可审查性明显提升。个人经验是先从一两个你每天重复度最高的任务开始建技能坚持迭代两周你会真切感受到效率变化。多说一句关于下载资源的选择与其花大量时间囤积几百个技能不如先把自己工作流里最常用的 10 个场景打磨透。技能不是越多越好而是每个技能都真正解决一个明确问题。尊重边界、充分测试、保留版本记录这套习惯能让你在这个快速演进的生态里走得更稳。
这段时间把 Claude 的 agent skills、Codex 的 skills 生态、GitHub 上那些热门 skills 仓库都翻了一遍又拉着几个常见的 skills 下载平台实测了整个周末。绕了挺多弯路也踩了几个特别典型的坑。这篇东西不做概念科普直接讲我在实际使用里对 skills 的理解——它到底解决什么问题、常见平台怎么选、怎么装、怎么写、怎么排查。先说结论skills 这个事本质上是把告诉 agent 怎么干活这件事从一次性对话提示词变成了可复用、可分发、可版本管理的工程化资产。它的价值不在技术多高深而在信息组织方式的变革。下面我按实际动手顺序展开聊。1. 重新认识 skillsagent 能力的最小复用单元1.1 skills 到底解决什么问题你要理解 skills得先理解 agent 在没有 skills 时有多痛苦。平时我们用大模型写代码、写文案思路是在对话里把需求描述清楚。但 agent 不一样尤其是 Claude Code、Codex CLI 这种跑在终端里的编程型 agent它会自主决定调用哪些工具、按什么顺序调用、看到结果后怎么调整。问题来了如果 agent 没有任何结构化指引它面对一个给我把登录页改成响应式布局的需求时可能东试一把西试一把改完左侧边栏忘了右侧卡片调完颜色忘了字号。skills 解决的就是这个问题。它是一个定义好的能力包里面包含了对某项任务的详细操作规范、评价标准、常见坑位、参考示例甚至可以直接调用的脚本。agent 在遇到相关任务时会把这份操作手册读进去然后照着规范来干。我举一个具体例子。你给 agent 一个生成视频分镜的需求如果没 skills它大概率会输出一个泛泛的分镜模板镜头号、景别、台词、画面描述都有但节奏松散、切分不合理。如果你装了一个分镜 skills里面会写明故事结构怎么拆解、每个节拍控制在几秒、景别变化频率、转场逻辑、文案与画面的对应规则。agent 拿着这套规范去生成产出的东西立刻有了专业感。这也解释了为什么网上skill 推荐热度这么高——它本质上是把高手的经验模板化、打包化了。1.2 生态里的几个关键玩家市面上提到 skills至少有四类完全不同的东西这个非常容易混淆。第一类是 GitHub Skills。这是 GitHub 官方做的一套学习路径系统通过仓库内的交互式课程教你怎么用 GitHub 功能比如 Actions、Copilot、Codespaces。它的本质是教程 练手环境跟 agent 技能没有直接关系。第二类是 Claude Agent Skills。Anthropic 在 Claude Code 和 API 层面推的能力框架把技能定义成 SKILL.md 加附属脚本、资源的目录结构按需加载。这是目前社区讨论度最高、生态最活跃的方向。第三类是 Codex Skills。OpenAI 的 Codex CLI 也支持类似机制。它更偏向软件开发场景从工程流程、代码规范到命令行操作都能封装成技能。第四类是社区自发的 skills 集合比如 superpower skills、各种 awesome-skills 仓库、独立博主做的付费/免费技能包。这中间的品质差异极大需要自己甄别。还有不少产品在往这个方向靠比如 Reasonix、Trae、Cursor 里的自定义规则体系其实都借鉴了同一套思路。理解这个生态后你会发现一个明显趋势未来 agent 的竞争力很大程度上取决于它的技能仓库够不够丰富、够不够专业。2. 核心机制拆解一个 skill 文件里到底装了什么2.1 SKILL.mdagent 的操作手册几乎所有主流 skills 框架核心入口都是一个 Markdown 文件通常命名为 SKILL.md。它的作用不是给人类看的文档而是给 agent 看的操作手册。我见过不少人第一次打开一个 skill 文件夹时很疑惑就这么个 Markdown这里面的内容也就比普通提示词长一点而已。但关键在于SKILL.md 的书写方式跟普通提示词有本质区别。普通提示词是对话时临时写的需求描述而 SKILL.md 是按照结构化规范写的、面向复用场景的指令集通常包含以下区块技能名称与用途描述让 agent 判断什么情况下该调用它适用场景与禁用场景避免误用输入参数说明明确需要哪些信息执行步骤按顺序列出操作流程质量标准即做完后怎么验收常见错误与规避方法示例输入输出或参考模板这个格式其实是把师傅带徒弟的过程文本化了。agent 每次干活前读一遍干活中按步骤执行干完后按质量标准自查。2.2 元数据与依赖声明SKILL.md 文件本身还有一个常见写法就是在文档开头放 YAML 格式的元数据块。它定义技能的名字、描述、版本可能还有作者和依赖关系。这块信息非常重要因为 agent 载入技能时会先根据描述判断是否与当前任务匹配。如果描述写得含糊比如a useful skill for codingagent 可能压根不知道什么时候该用。反过来如果描述里写清楚for building HTML/CSS responsive layout with mobile-first approach匹配准确率会高很多。依赖声明则解决更复杂的问题。有些技能不只是文本指令还需要外部脚本、配置文件、数据模板的配合。比如一个前端组件调试技能可能会附带一个检查页面可访问性的 Node 脚本一个分镜生成技能可能会附带几个景别示例图。因此 SKILL.md 的元数据或正文中必须说清楚这些依赖文件的路径和使用条件。2.3 为什么说 skills 是提示词 工具的混合体我一开始也以为 skills 就是把大段提示词存成文件装好之后让 agent 每次对话都记住。但用了几周后我发现它比普通提示词精妙的地方在于按需加载。agent 在每次请求时不会把所有技能内容读一遍那样既消耗 token又增加上下文噪声容易让模型跑偏。正确的机制是agent 根据任务描述从技能列表中检索出最相关的 1-3 个技能然后完整读取这些技能的 SKILL.md。这相当于把几本工具书放在书架上需要哪本就抽哪本而不是把所有书的内容全背下来干活。这个设计逻辑非常重要它让技能库可以无限扩充而不拖累日常使用。你自己写技能的时候也要注意区分技能说明书和参考手册的关系。说明书要短平快讲清步骤参考手册可以长但要通过路径引用让 agent 按需读取。3. 实操落地从市场下载到本地配置的全流程3.1 常见 skills 下载平台怎么选先说平台。因为 skills 还是个新生事物没有像 App Store 那样统一规范的市场所以选择平台时你得先知道自己要装进哪个 agent。GitHub 仓库这是最核心的分发渠道覆盖面最广。好处是版本管理清楚、能看到源码和问题反馈坏处是你得自己甄别质量而且内容太多搜索效率低。官方市场与目录Anthropic 官方有 skills 目录OpenAI 对 Codex 也整理了一套示例。这些经过初步审核稳定性好但数量有限。第三方社区站比如 superpower skills 这类专门目录站会有分类、推荐机制用起来方便。但更新速度参差不齐且要注意授权条款。国内开发者整理的导航仓库在 GitHub 上搜awesome claude skills或codex skills list能找到很多集合帖资源密度高适合逐个查阅。我的建议是从官方市场或大型集合站起步装 2-3 个广泛好评的技能先用起来再根据你实际的工作流找细分技能。不要一上来就全量拉取几百个技能管理成本和识别成本都会失控。3.2 在 Claude 环境里安装 skills以我常用的 Claude Code 环境为例安装过程分成三步。第一步确定技能存放目录。Claude Code 对 skills 的扫描路径通常是~/.claude/skills/下的子目录具体路径会随版本变化建议用/skills命令查看当前版本支持的位置。每个技能必须独占一个子目录目录名一般用短横线分隔的小写单词比如frontend-coding。第二步把整个技能目录克隆或复制进来。这里有个极易踩坑的地方技能目录里不要有多余的嵌套SKILL.md 必须直接放在该技能子目录的根下。如果解压后得到一个多套一层的目录agent 就识别不到。第三步重启 agent 会话或运行重新加载命令。大多数 CLI 工具会在新会话启动时自动扫描技能目录但如果你当前已有一个运行中的会话加载新技能不会立即生效需要重开对话。我在实测中还发现某些 agent 对技能目录的读取权限有要求。克隆下来的技能文件如果是 root 所有或权限过严会导致读取失败。最简单的方式是用普通用户身份克隆并确认目录有可读权限。3.3 在 Codex 环境里安装 skillsCodex CLI 的 skills 机制跟 Claude 有点类似但细节不同。它通常把技能放在项目级别或用户级别项目级意味着只对该仓库生效用户级则全局可用。我建议能放项目级就放项目级。这样不同项目可以绑定不同技能集合避免全局技能过多导致检索干扰。你开发电商前端项目就只加载前端相关技能你写分镜脚本就单独建一个内容创作项目目录只放分镜、文案类技能。安装完成后可以手动触发一次技能相关指令来验证。比如你装的是一个后端 API 设计技能直接在对话里要求 agent 按这个技能来设计一个登录接口看看它是否识别并采纳了技能中定义的步骤和规范。如果它完全无视了技能内容多半是路径或命名出了问题而不是技能写得不好。3.4 安装后怎么验证技能生效验证这一环很多人会跳过但我建议别省。最快捷的验证方式是查看 agent 的上下文窗口或调试日志。以 Claude Code 为例你可以在调试模式里看到它加载了哪些技能文件。如果你看不到加载记录大概率路径不对。另一个有效方法是做一次技能前后对比在没有技能的情况下让 agent 完成一个任务然后装上技能再让它做同款任务对比输出质量。这个方法也适合你在社区里讨论某个技能到底有没有用时给出有力证据。我自己验证分镜技能时对比过一次前版输出是流水账后版输出有了镜头节奏设计差别一眼可见。限制 | 原因 | 规避方式 路径不对 | 目录多套一层或 SKILL.md 不在根目录 | 严格按文档整理目录 描述模糊 | 元数据里技能描述不够具体 | 重写描述明确触发场景 权限不足 | 克隆文件不可读 | 检查目录权限普通用户运行 新技能未加载 | 会话未重启 | 重启会话或手动 reload4. 自己动手写 skills一套可以复用的模板4.1 设计技能的三层结构从会用别人的技能到写自己的技能中间最关键的是理解技能设计结构。我习惯把技能拆成三层触发判断层、执行流程层、质量校验层。触发判断层解决的是什么时候该用这个技能的识别问题。对应的就是 SKILL.md 开头的 description 字段和适用场景描述。这一层写得越精准agent 越不容易误调用。执行流程层是整个技能的核心。它要回答打开一个需求后具体按什么顺序做什么。一个常见的误区是只写目标不写步骤比如生成一个精美的登录页没有任何中间步骤agent 还是得靠瞎猜执行。正确的做法是把流程拆成一系列可执行动作先读取需求文件再提取页面区块然后逐个敲定布局、色彩、字体、交互最后输出完整代码。质量校验层解决做完了怎么验收的问题。你需要给 agent 一个自检清单让它输出前自己过一遍。比如前端技能里的检查清单会有页面是否有移动端断点、标签语义是否完整、图片是否带 alt、按钮是否有 focus 状态。有了这一层产出的稳定性会显著提升。4.2 一个实战模板示例前端页面生成技能我拿自己常写的一个前端技能来做示例你直接抄结构改内容就能上手。技能目录叫frontend-page-builder里面就一个SKILL.md文件。技能内容的大致框架--- name: frontend-page-builder description: Build responsive HTML/CSS pages with mobile-first approach and accessibility checks. Use when user requests a landing page, dashboard, or UI component. --- # Frontend Page Builder ## Purpose Creates production-grade static pages using semantic HTML and modern CSS. ## Input - page goals, content blocks, reference links - target device ratio and style preference ## Steps 1. Parse requirements and list page sections. 2. Establish a CSS reset and design tokens (colors, spacing, radius). 3. Build sections one by one in semantic HTML. 4. Apply styles with mobile-first media queries. 5. Validate accessibility with the checklist below. ## Quality Checklist - Contains only one H1 per page - Every image has an alt attribute - All buttons have focus-visible styles - Layout adapts below 480px width - No horizontal scroll on mobile你不用把每个细节都写得像代码注释一样冗长但关键决策点必须明确。我写技能的技巧是想象你在给一个很聪明、但没做过这行的实习生写操作手册。他会做什么傻事你就在常见错误里写什么。4.3 测试与迭代的实操方子写完技能后不要直接拿去正式任务上用先在测试目录里跑 2-3 个真实小任务观察它哪里被误解、哪里执行不动。这个过程跟调 prompt 很像但反馈更结构化因为你能从 agent 的步骤日志里看到它的决策链。有朋友问我要不要给技能加版本号。我的答案是要而且最好在元数据里写清楚。技能是会被反复迭代的版本号能帮你区分两版之间的效果变化。我自己用v0.1.0起步实验性修改直接改主版本稳定后打 tag 同步到 Git。迭代节奏上我发现最有效的做法是每跑完一个任务根据真实输出反推哪里需要给 agent 更多约束或更多示例。有时候加一句不要让卡片溢出容器这种具体规则比写十句空泛的注意美观管用得多。这套方法坚持两周后你写的技能会越用越顺手。5. 常见问题与排查技巧实录5.1 为什么加载了技能agent 还是不听话这是我见过最多的问题。不少人装了热门技能后发现agent 的表现没有明显变化于是觉得 skills 是个噱头。实际情况通常是触发判断出了问题。agent 决定是否用某个技能依据的是任务描述和技能 description 的匹配度。假如你装的技能 description 写的是Create beautiful landing page design with modern CSS techniques你给 agent 的指令却很含糊比如帮我做个页面吧它可能不会主动想起这个技能。解决的办法有两个方向一是在需求描述里明确指出使用 frontend-page-builder 技能来完成这个页面二是把技能 description 写得覆盖更多泛化表达让 agent 更容易联想到。两者都做了效果最稳定。还有一种容易被忽略的情况agent 的上下文里技能内容太多把它淹没了。一些大型技能附带大量示例代码agent 读取时会被细节带偏忘记主线流程。这时建议把示例代码从 SKILL.md 里拆出去作为独立文件用路径引用核心文档只保留流程和规则。5.2 路径、权限与文件编码的坑我知道有人卡在安装环节半天最后发现是目录套娃的问题。技能整个文件夹解压后如果最外层多了一层同名目录agent 扫描时就会出现找不到技能的结果。解决办法很原始但有效打开目录树看一眼确认 SKILL.md 在技能根目录下而不是在深层嵌套里。另一个高频坑是文件名大小写和编码。SKILL.md 这几个字母大小写必须完全一致写成 skill.md 或 Skill.md 都会导致识别失败。文件内容如果用带 BOM 的 UTF-8 编码解析时可能报错最好用无 BOM 的 UTF-8。Windows 上尤其要留意换行符问题尽量让 Git 自动转换 LF/CRLF避免意想不到的解析异常。权限问题在共享服务器上更普遍。如果你有 root 权限操作时别偷懒用 root 直接克隆技能到用户目录会导致普通用户读不了。正确做法是用运行 agent 的普通用户身份克隆确保文件所有权一致。5.3 下载平台上的质量诈骗陷阱技能市场鱼龙混杂我在实测里已经见到了好几类问题。一类是改名搬运。把同一份开源技能换个名字、加个封面就挂到社区站上收取积分或收费下载。避免办法很简单下载前在 GitHub 上搜索技能关键字找到原仓库比对文件内容内容一致的选原仓库至少能保证更新来源。一类是参数注水。SKILL.md 写得很长、很唬人实际上大量内容都是大而化之的正确废话执行步骤不严谨。对这种技能我有个快速的筛选技巧看常见错误和质量清单两个部分。如果它们写得足够具体连边界情况都提到说明作者真在实战中打磨过如果只有确保代码质量注意用户体验这种空话果断放弃。还有一类是安全性问题。有些技能会附带脚本安装后自动执行。我建议所有从第三方下载的技能在运行前先打开脚本文件看清它做了什么操作。会不会向外部发送数据有没有访问敏感目录这两点确认完毕后再在测试环境里跑一次确认安全性后再用于正式工作。你可以通过数字签名或社区反馈来辅助判断。GitHub 仓库如果有 star 数、issue 讨论和 release 历史可信度会高不少独立博客发布的技能包则要看是否有明确的更新记录和用户评论。遇到那种来源不明、发布者没有任何历史记录、页面只有一张截图和下载按钮的资源我强烈不建议碰。6. 一点个人经验作为收尾最后分享一点我自己的体会。技能这东西看起来是给 agent 用的但写多了你会发现它其实是逼着你自己重新梳理工作流。把怎么做前端页面怎么拆解分镜脚本怎么写技术方案这些平时靠脑子和习惯完成的事用清晰、可执行的语言描述出来本来就是这个时代很值得做的一件事。而且一旦你开始用技能管理自己的 agent你对模型的信任度也会跟着改变。以前我总觉得 agent 输出随机性太强给不了确定性交付现在我会先为任务配好技能再让 agent 启动输出稳定性和可审查性明显提升。个人经验是先从一两个你每天重复度最高的任务开始建技能坚持迭代两周你会真切感受到效率变化。多说一句关于下载资源的选择与其花大量时间囤积几百个技能不如先把自己工作流里最常用的 10 个场景打磨透。技能不是越多越好而是每个技能都真正解决一个明确问题。尊重边界、充分测试、保留版本记录这套习惯能让你在这个快速演进的生态里走得更稳。
