我最早接触 skills 这个概念的时候其实是有点懵的。那会儿我刚把 Claude Code 装好满脑子想的是怎么让它更听话一点结果在社区里看到一堆人都在聊 skills、skills我还以为是某种编程技能清单。直到某天把一个处理 PDF 的 skills 文件夹拖进~/.claude/skills里AI 突然能稳定输出格式完全一致的文档我才意识到之前一直在用裸奔版的 Agent——模型本身的聪明程度是一回事你有没有把做事的经验喂给它是另一回事。这篇东西就围绕skills这个主题展开不绕弯子。我会讲清楚它到底是什么、为什么这么设计然后重点解决几个大家搜得最多的问题Claude Code 怎么手动装 GitHub 上的 skills、common skills 源网站和值得关注的项目、AI skills 怎么写、装多了之后怎么清理、以及出现装了不生效的完整排查思路。适合正在用 Claude Code、Codex、OpenCode 这类 AI 编程工具的开发者也适合刚听说 skills 这个词、想系统学习一下的新手——看完你应该能自己动手装一个、改一个、甚至从零写一个。1. 先搞清楚一件事skills 到底是什么它解决了什么1.1 从 Agent 的新实习生困境说起把 AI Agent 想象成一个刚入职的实习生。模型本身很聪明但刚来的那天他什么都不知道不知道你团队怎么发周报、不知道你的前端项目用什么命名规范、不知道数学建模论文的图表要什么格式。你每次都临时教他他说好的我学会了但下次又忘了。skills 干的其实就是写员工手册这件事把一件事情的完整做法——什么时候做、先做什么后做什么、用什么工具、输出什么格式——写成一个结构化文件。Agent 在接到相关任务的时候会自己去翻这个手册照着上面的方法执行。它不是给模型增加知识而是给模型的执行流程装上方法论。这个设计高明在一点它不需要重新训练模型就是把文本喂给 Agent 当上下文用。所以 skills 的内容可以随意迭代今天写坏了改一行字就行不用等什么模型更新。1.2 skills 和 MCP、插件到底有什么区别这是很多人最容易混的地方我当时也绕晕过。简单粗暴地理解MCPModel Context Protocol是给 Agent 接外设的。你通过 MCP 让 Agent 能读数据库、调公司的内部 API、操作浏览器它解决的是工具接入问题。Plugin 插件是把功能打包进应用的通常带 UI属于产品层面的扩展。skills 是教 Agent 怎么做事的说明书。它不一定需要外部工具也可能只是给 Agent 一套思考框架、操作步骤和输出模板。打个比方MCP 是给实习生一台打印机插件是买一台自带操作面板的一体机skills 则是一份图文并茂的《如何用这台打印机完成月度报表装订》SOP。三者可以配合使用但解决的问题完全不同。1.3 一个 skills 文件夹里到底装了什么规格上来讲skills 通常是一个文件夹核心是一个SKILL.md文件。这个文件有 YAML 格式的 frontmatter——里面的name和description字段是 Agent 判断这个技能什么时候该用的唯一依据正文部分则包含使用时机、操作步骤、示例、注意事项这些内容。除了SKILL.md文件夹里还可以放scripts目录放一些用来辅助完成任务的脚本也可以放模板文件、参考文档。这里最容易被忽略的是description的写法。很多新手写 skills 的时候description 随意写两句完事结果装上去之后 Agent 一直不调用你还以为是自己路径放错了。实际上 Agent 的加载机制是按需注入每次对话它会扫描所有 skills 的描述判断当前任务匹配哪个技能匹配上了才把对应的SKILL.md内容注入到上下文里。所以 description 写得越具体、越接近用户真实的提问方式skills 被正确调用的概率就越高。我把这种机制理解成技能检索系统描述就是索引关键词索引烂文件再漂亮也白搭。2. 动手装第一个 skillsClaude Code 和 Codex 的安装路径2.1 Claude Code 手动安装 GitHub 上的 skills标准流程这是被问得最多的场景。你在 GitHub 上看到一个仓库里面有一堆 skills 子目录想装进 Claude Code怎么做第一步先确定你要装到哪一层用户级~/.claude/skills/当前用户的所有项目都能用。项目级.claude/skills/只对当前项目生效。适合放跟这个项目强相关的规范类技能。第二步把 GitHub 仓库拉下来但别整个仓库直接扔进去。我见过太多人犯这个错git clone一个集合仓库后直接把这个仓库放到~/.claude/skills/下面结果结构变成了~/.claude/skills/仓库名/某个技能/层级嵌套过深Agent 扫描的时候要么识别不到要么加载性能变差。正确做法是把仓库 clone 到临时目录然后把你要的那个或那几个技能子目录单独复制到~/.claude/skills/里# 1. 先建好目录 mkdir -p ~/.claude/skills # 2. 拉下仓库以官方 skills 仓库为例 git clone gitgithub.com:anthropics/skills.git /tmp/anthropic-skills # 3. 看一眼里面有哪些技能子目录 ls /tmp/anthropic-skills # 4. 只拷贝你要的那个技能比如 docx 处理 cp -r /tmp/anthropic-skills/docx ~/.claude/skills/第三步重启 Claude Code 会话。skills 是在启动时扫描的不重启不会生效。重启之后你可以在会话里开 debug 模式看加载日志确认有没有扫到对应的技能目录。2.2 Codex 和 OpenCode 的 skills 接入方式Claude Code 带火了 skills 之后其他 Agent 工具也跟进了这套思路。如果你用的是 OpenAI Codex路径非常相似把技能目录放到~/.codex/skills/即可项目级的放.codex/skills/。它同样通过SKILL.md的 frontmatter 来识别技能名称和触发描述。OpenCode 的做法略有不同它对从远程仓库装 skills的支持做得比较顺滑可以通过命令行直接添加远程技能也可以引用某个 GitHub 仓库里的技能文件。另外 OpenCode 有一个引导式编码模式本质上也是把大任务拆成标准步骤——和 skills 的理念同源只不过它把流程内置到了工具本身。对我来说跨工具使用 skills 最大的感受是目录结构和文件规范基本是通用的。我维护的 skills 集合会刻意避免依赖某个工具特有的 API只写该执行什么步骤、产出什么格式这样在 Claude Code 和 Codex 里都能直接用。如果你打算长期维护自己的技能库这一点值得从一开始就注意。2.3 skills 网页版进入到底说的是什么搜这个词的人不少我猜有两种诉求。一种是问有没有网页端可以浏览、下载 skills 资源有的很多社区维护的 skills 目录站可以直接在浏览器里按分类筛选技能包这类站点通常会标注适配工具、作者、最近更新时间、star 数比在 GitHub 上大海捞针高效得多。另一种是问我用的 Agent 有 Web 界面装完 skills 之后怎么确认生效如果你用的是 Claude 的桌面端或 Web 端装好 skills 后可以直接在对话里问你现在有哪些可用技能或者给它一个高度匹配某个 skill 描述的任务观察它是否按技能里的步骤执行。不过最可靠的还是在 CLI 里通过 debug 日志确认Web 界面一般不会暴露底层加载细节。2.4 安装阶段最容易翻车的三个点装得多了之后我把翻车原因基本收敛成了三条基本没见过第四条一是路径放错。用户级和项目级搞混或者把技能文件夹嵌了两层子目录Agent 扫描不到。二是 frontmatter 格式坏了。name或者description字段漏了、引号不对、缩进错了整个技能会被静默跳过。三是权限问题。技能目录里有脚本文件需要执行权限复制之后忘记chmod xAgent 调用脚本时直接报错。这类问题有个共性不会弹明显的错误提示只会不生效或不好用排查起来全靠经验和日志。所以我的建议是装完第一个技能后先用一个最简单的技能跑通验证链路再批量安装别一口气装 20 个然后同时排查。3. 去哪里找 skills源网站、GitHub 项目和选型标准3.1 官方和社区维护的 skills 源网站很多人上来就问skills 技能库网址我整理了一下自己常用的几类入口官方示例仓库Anthropic 官方维护的 skills 仓库里面有不少参考实现比如文档处理、画布类、构建工具类的技能。这类技能的优点是规范、和 Claude Code 匹配度高适合当标准答案看。GitHub 聚合话题搜索claude-skills、agent-skills、awesome-claude-skills这类 topic 或 Awesome 清单能找到大量社区贡献的技能集合质量参差不齐但胜在量大。社区目录站一些开发者做了可视化的 skills 目录站按场景前端、写作、数据分析、按工具Claude Code、Codex、OpenCode分类。这类站点适合快速浏览看到名字感兴趣再点进 GitHub 看详情。3.2 值得关注的几个 skills 集合项目这里说几个我实际用过、觉得有代表性的项目类型方便你做选型参考类型代表项目方向特点适合人群官方参考集anthropics/skills规范、保守、按官方最佳实践写第一次接触 skills 的人综合效率包superpower skills 这类偏工作流管理覆盖计划、头脑风暴、代码审查等安装一个就有一整套想快速提升 Agent 日常使用效率的人语言生态专项typesafe/ai-skills 这类偏后端和类型安全方向示例代码规整适合集成到现有工程体系后端/Java/Scala 生态的开发者垂直场景集合cola skills 这类目录简单、开箱即用围绕特定场景或框架打包某个具体领域有重复性任务的人表格里的案例只是方向参考重点是理解官方参考集、综合效率包、语言生态专项、垂直场景集合这四种形态的差异。你说不清自己要什么就先装官方参考集里的一两个技能用起来比什么都强。3.3 怎么快速判断一个 skills 值不值得装装得多了之后我总结了一套三分钟快速评估法。拿到一个技能仓库第一件事不是 clone是看它的SKILL.md文件看 description 写得细不细。如果 description 只是一个有用的技能这种废话说明作者没想清楚触发场景这个技能的匹配度大概率也差。看步骤是不是可执行。技能正文里如果全是抽象口号没有具体的输出格式、模板、判断标准那 Agent 即使加载了也做不出差异化结果。看依赖。有些技能依赖外部 API key、Python 包、命令行工具。装之前先看清楚自己环境里有没有这些东西别等调用了才发现缺依赖。另外尽量选最近半年有更新的项目。skills 这个领域迭代非常快Agent 的行为模式变了之后老技能的有效性会明显下降。一个一年没动的技能除非它的核心逻辑与工具版本无关否则不碰。4. 从使用到创造手把手写一个自己的 AI skills4.1 最小的 SKILL.md 长什么样写自己的 skills 没有想象中复杂。说到底它就是一个 Markdown 文件只要你清楚怎么向别人交代工作流程你就能写 skills。我建议所有新手从最简结构开始不要一上来就加脚本--- name: weekly-report description: 根据用户提供的本周工作记录生成结构化周报适合在周五使用 --- # 周报生成 ## 使用时机 当用户提供本周的工作内容、任务清单或 commit 记录并要求整理周报时使用。 ## 执行步骤 1. 收集信息阅读用户输入或从 git log 中提取过去七天的 commit 记录。 2. 整理分类按完成事项 / 进行中事项 / 风险与阻塞三类归纳。 3. 生成输出按模板输出周报模板见下方。 ## 周报模板 - 本周完成 - 正在推进 - 需要支持 - 下周计划写完之后把文件夹放进~/.claude/skills/重启会话然后给 Agent 抛一个任务帮我把这周的工作记录整理成周报它就会被触发按照模板生成。从零到生效整个过程不超过十分钟。4.2 写 AI skills 的关键步骤要粗输出标准要细我一开始写 skills 犯过的错误是步骤写得太细输出标准写得太粗。比如我花大篇幅写第一步打开文件第二步读取内容第三步分析但最后只说了句生成一份报告。结果是 Agent 执行的时候每一步都被限制死反而没有灵活性而输出端因为没有明确标准产出的东西五花八门。正确思路反过来的执行步骤给框架就好不要事无巨细输出格式和判断标准才是要认真写的地方。因为模型本身的强项就是在执行过程中灵活处理细节它需要的不是手把手教它读写文件而是告诉它最终交付物应该长什么样、什么算合格。比如周报技能里重点写清楚每类事项的措辞风格、字数限制、层级结构比写清楚怎么打开 git log有用得多。4.3 让 skills 带上脚本什么时候该加 scripts当技能需要确定性操作时就该加脚本了。比如技能要求必须把一个 JSON 文件里的字段映射成另一个格式这种操作靠模型临场发挥容易出错写一个 Python 脚本固定映射逻辑才是对的。skills 支持在文件夹里放scripts子目录在SKILL.md里注明执行步骤三时运行python scripts/transform.py即可。我曾经写过一个处理 Excel 报表的技能最开始纯粹靠 Agent 用自然语言描述操作结果每次生成的 pandas 代码都不一样命名也不一致后期维护很痛苦。后来我把核心处理逻辑固定成一个脚本SKILL.md只负责说明输入输出格式效果一下子稳定了。4.4 学习路径先用对话模拟再固化成 skills如果你想系统学习怎么写 skills我推荐一个自己验证过很高效的路径。第一步别急着写文件先打开 Agent 对话用自然语言和它过一遍你想标准化的流程让它临时按你期望的方式执行一次。第二步把这次对话里你强调过的关键约束提炼出来——这些就是 skills 正文的核心内容。第三步把流程写进SKILL.md然后测试触发。第四步跑通之后观察实际输出逐轮优化措辞。这个过程本质上是把隐性经验显性化。你在对话里临时要求 Agent记住这里的格式是一次性的写进 skills 之后就是可复用、可分享、可版本管理的资产了。我自己的技能库里大概有一半都是这么沉淀出来的不是一开始就设计好的而是遇到问题临时解决效果不错固化下来。5. 实战场景前端开发、数学建模、AI 漫剧里的 skills 应用5.1 前端开发 skillssuperpower skills 这类是怎么帮你干活的前端大概是 skills 应用最密集的领域之一。原因很简单前端开发有大量规范一致性的需求——组件怎么写、类名怎么命名、可访问性注意什么、commit 信息怎么组织。这些东西靠模型临场发挥每次都不稳定放进 skills 之后Agent 每次写代码之前都会先过一遍规范。以社区流行的 superpower skills 这类综合包为例它通常覆盖了几个固定场景开发前的计划拆解、代码审查的检查清单、提交信息的规范化、重构的安全步骤。用起来的效果是你让 Agent帮我加一个用户头像组件它不会直接开写而是先加载开发流程技能按计划、实现、自检的步骤执行自检阶段还会对照可访问性检查清单。输出的代码和质量明显比没有技能约束时高一个档次。我自己实际用下来前端场景里最值得自定义的是项目级规范技能——把你团队的代码风格、组件库用法、脚手架约定写成一个项目级 skills放在.claude/skills/下。这样同一套 Agent 换个项目就会自动切换风格因为技能是按项目加载的团队里的其他成员 clone 下来也能共享。5.2 数学建模场景数模竞赛里怎么用好 codex skills数学建模这种场景听起来和 AI 编程工具不太搭但实际非常契合。因为数模工作的核心是高度套路化的拿到题目之后做数据清洗、特征分析、画图、建模、跑结果、写论文。每一步都有固定的处理套路而比赛期间你能花的调试时间又极其有限。所以有人提到华为杯建模比赛好用的 codex skills本质上就是把这套固定流程封装成几个技能比如数据理解技能规定拿到数据集先看缺失值分布、再看类型分布、生成描述性统计可视化技能规定不同变量类型对应的图表类型模板论文排版技能规定 LaTeX 的标题层级、公式编号、三线表格式。Codex 配合这些技能之后大部分重复劳动可以直接自动化留出时间给真正的建模和论文分析。这里有个比赛场景的技巧提前把技能写好、测试好比赛第一天不要花时间去调技能直接用最保守的路径跑通全流程。技能的优化要给平时的练习时间别在赛场上当实验。5.3 AI 漫剧这类内容创作场景的 skills 思路从编程跳到内容创作skills 的思路依然成立只是封装的对象从代码规范变成了创作规则。AI 漫剧这类场景最大的痛点是人物一致性、分镜格式统一、风格不漂移。这些恰好是规则密集型问题每次生成分镜脚本都要说角色 A 穿着什么、场景是哪里、镜头怎么切重复劳动极其严重。把创作规则封装成 skill 之后你就可以不再每次手打一大段提示词了。技能里可以写明主角描述词库反派描述词库分镜脚本字段结构镜头编号景别画面内容台词时长以及画风关键词固定后缀。Agent 生成时自动套用生成出来的脚本结构每集都一致后续人工修改成本大幅下降。这类内容创作 skills 有一个和编程 skills 不同的点它的输出标准不只看格式还要看风格稳定性。所以写技能的时候要把风格关键词、禁用词、参考片段都放进去让模型有据可依。我认识的一些做 AI 内容的朋友已经把核心角色的设定写成了团队共享的 skills 文件新成员入组只要加载同一套技能产出风格立刻统一——这本身就是 skills 作为团队知识资产的价值。6. 用久了就懂的管理经清理、更新与装了不生效的排错6.1 skills 装多了之后为什么要清理、怎么清理skills 不是装得越多越好这个道理我装了三十多个技能之后才痛彻心扉地理解。Agent 每次任务都要扫描所有技能的描述来做匹配技能库过大一是启动和任务处理的扫描成本变高二是描述之间可能互相干扰一个本来不需要技能的任务因为某个技能描述写得宽被强行套上了模板反而画蛇添足。社区里讨论清理 skills 的帖子不少大家认可的基本是三层做法第一层直接删目录把长期不用的技能从~/.claude/skills/移除第二层利用配置的禁用机制在配置里排除某些技能不用物理删除第三层也是我最推荐的做项目隔离——通用技能放用户级项目专属技能只放项目级两个层级分开管理互不干扰。我个人的习惯是每个月做一次技能审计看每个技能最近有没有被成功触发。发现超过一个月没触发过的先禁用禁用后再过一个月还不需要的就删除。这套流程下来我的技能库常年保持在十五个以内每个都是真在用的。6.2 手动装不生效的完整排查链路我明明按步骤装了怎么 Agent 就是不用这个问题的排查链路其实可以非常固定以下是反复验证过的排查顺序第一步确认路径。先在命令行打印目录结构看技能文件夹是否直接在 skills 根目录下。很多人复制的时候多包了一层比如~/.claude/skills/仓库名/技能名/SKILL.md这就不符合要求。标准的应该是~/.claude/skills/技能名/SKILL.md。第二步检查 frontmatter。打开SKILL.md看头部 YAML 的name和description是否完整、格式是否正确。name不是必须和文件夹同名但强烈建议保持一致减少识别歧义。description里不要有换行符导致的格式断裂。第三步看加载日志。用 debug 模式启动 Claude Code观察启动阶段扫到的技能列表确认我们的目标技能有没有出现在列表里。如果不在说明路径或格式有问题如果在说明技能加载成功但触发失败。第四步检查触发条件。这是最容易卡住新手专家的一步——技能没生效很可能不是没装上而是 Agent 不认为当前任务需要用它。比如你的技能描述写得很具体但用户提问方式太模糊匹配不上。这时候调整description的措辞尽量覆盖各种可能提问的说法往往就解决了。第五步做最小验证。放一个最简单的技能比如用户说 hello 时回复固定短语测试整条链路是否顺畅。如果最小的都触发不了那就是环境配置层面的问题别急着怀疑技能内容。6.3 版本管理和团队共享的一点建议skills 本质上是文本文件完全可以进 Git 管理。我个人的做法是建一个 dotfiles 仓库把用户级技能目录整个纳入版本控制每次改动提交一次。这样万一某次改坏了回滚很干净。团队场景更进一步把项目级技能放在项目仓库里随代码一起分发新成员 clone 项目的同时就拿到了团队的 AI 工作规范。很多人忽略的一点是skills 文件里的描述文字不只是给 AI 看的也是给你的同事看的。一个 skill 之所以能在团队里被长期使用是因为它写得足够清晰人读了也知道流程是什么。所以我在写技能的时候有个习惯写完先发给同事看看他们人眼能不能看懂如果人看不懂AI 大概率也会理解偏。SKILL.md 本质上是一份给会读 Markdown 的实习生看的操作手册用它的人可以是机器但写它的标准应该按人也要能看懂来要求。最后说一个我踩过几次坑之后养成的习惯skills 装完不是终点前面一个月里每次实际使用后我都会顺手把这次任务里模型理解偏了的地方反馈到技能正文里加一句澄清说明、补一个反例。这么迭代几轮以后这个技能才真正从能用变成好用。技能不是一次性写出来的是养出来的——这句话放在这里大概是最合适的收尾。