前阵子换了一台新电脑装好 Claude Code 后我干的第一件事不是配 API Key而是打开 GitHub 把收藏夹里几十个 skills 仓库挨个 clone 下来。有朋友笑我太折腾但我真吃过亏——最早我攒了一堆“神级 prompt”散落在各种对话记录、备忘录和网页剪藏里换台电脑等于全部清零重新调教 AI 的成本高得吓人。后来接触到 Agent Skills也就是大家常说的 skills我才意识到提示词工程已经从“会话级”进化到了“资产级”以前是每次对话都手写指令现在是写一次、存下来、到处用。这篇内容就围绕 skills 展开适合三类人刚听说 skills 这个概念、想搞明白它到底是什么的小白已经在用 Claude Code 或 Codex、但只会从 GitHub 上装现成 skill 的普通用户以及打算自己写 skill、把它变成生产力工具的进阶玩家。我会把自己手动安装、踩坑、写 skill、清理维护的完整过程都写出来争取让你看完就能直接上手。1. Skills 到底是什么从一段复制粘贴的咒语到一个可复用的“外挂大脑”先讲一个类比。以前用 AI 干活就像每次请一个临时工你得从头交代背景、流程、输出格式、注意事项。遇到复杂的活儿比如“帮我审查前端代码规范”你每次都要写一大段指令说清楚要看哪些文件、按什么标准审、输出什么格式的 report。写多了你会发现这段指令本身才是真正的生产力——AI 模型就在那里谁给的指令质量高谁拿到的结果就好。1.1 我的第一个 skill从“糊墙”到“贴瓷砖”我第一次真正理解 skills 的价值是在处理一个重复性任务的时候。当时我需要 AI 帮忙把一批 Markdown 文档统一转成项目周报格式包括标题层级、表格栏位、措辞风格、敏感信息标注方式每次手工写提示词都要花十来分钟而且稍微漏掉一个要求输出就变样。后来我照着社区里的做法把这段提示词写进一个文件夹里面放一个SKILL.md文件再用几句话描述这个 skill 是干什么的AI 就能在我需要的时候自动“想起”它。这个词叫什么不重要重要的是它让我第一次感觉到AI 的使用方式从“每次现写”变成了“随取随用”。就像装修从“每次现和水泥糊墙”变成了“预制好瓷砖按尺寸贴上去”效率完全不是一个量级。1.2 SKILL.md 的结构一段 YAML 头信息加一堆“作业指导书”一个标准的 skill本质上就是一个文件夹加一个SKILL.md主文件。文件夹的名字就是 skill 的名字SKILL.md是这个技能的说明书。说明书开头有一段 YAML 格式的 frontmatter用来声明这个 skill 的名字、描述、可用的工具后面跟着的是正文——也就是你希望 AI 在执行这个技能时遵循的完整指导。拿一个最简单的 hello world 举例--- name: weekly-report description: 将零散的 Markdown 笔记整理成项目周报格式。当用户提到“生成周报”“整理周报”或给出多篇笔记时使用。 --- # 周报生成流程 1. 读取用户提供的所有 Markdown 文档。 2. 按“本周进展 / 风险与阻塞 / 下周计划”三部分整理内容。 3. 每条进展必须注明对应负责人与完成度格式为 任务名负责人完成度%。 4. 遇到不确定的信息用 [待确认] 标记不要自行编造。这段内容看起来平平无奇但一旦放进~/.claude/skills/weekly-report/SKILL.mdClaude Code 启动后就会自动加载它。当你说“帮我把这周这几篇笔记整理成周报”AI 会把这个 skill 当成一份“岗位说明书SOP”严格按照里面的流程执行而不是临时猜你想要什么。1.3 为什么 skills 现在才火从“会话级提示词”到“资产级技能”之前不是没有类似的方案比如自定义 system prompt、保存 prompt 模板、用 MCP 挂外部工具但它们各自都有问题。自定义 system prompt 只对一个会话有效换个项目就得重新贴prompt 模板只是个文本文件AI 不会自动识别“什么时候该用”MCP 解决的是“AI 能不能操作外部工具”的问题管不了“AI 该怎么干活”的流程问题。skills 把几件事一次性解决了它有自动匹配机制靠 description 里的语义描述判断何时启用它有标准目录规范换台电脑同步一下就能恢复它还能携带脚本和资源文件不只是纯文本提示词而是把“知识”和“执行”合在了一起。我做了个表格方便你理解 skills 和传统方案的差异方案作用范围是否需要手动指定是否可携带资源文件复用难度system prompt单次会话每次手动配置否高每次都要重贴prompt 模板单次会话每次手动粘贴否中依赖你找到文件MCP 工具跨会话自动但只提供工具能力部分中要写服务端Agent Skills跨会话自动匹配启用是低文件夹即技能理解到这个层面你就知道为什么社区对 skills 的热情这么高。它不是换了个名字炒冷饭而是真正把“怎么用 AI”这件事从临场发挥变成了基础设施。2. 手动安装 GitHub 上的 Skills文件结构、路径规则与常见失败原因先说结论手动安装一个 skill 的完整流程就三步——把仓库弄到本地、放进指定目录、重启会话。但我实际操作下来这三步每一步都有坑而且很隐蔽尤其是第一次装的时候很容易掉进“明明放进去了却加载不出来”的困境。2.1 从仓库到本地的三步搬运第一步是获取 skill 文件。最常见的做法是把整个 GitHub 仓库 clone 下来。比如你看到一个叫awesome-claude-skills的仓库里面有code-review、doc-generator等子文件夹你可以只 clone 整个仓库也可以单独下载某个子文件夹。第二步是找到目标路径。Claude Code 里默认读取两个位置用户全局目录~/.claude/skills/和项目本地目录项目根目录/.claude/skills/。全局目录里放的是所有项目通用的技能本地目录放的是只属于当前项目的技能。两者的加载优先级有差异本地目录会覆盖全局同名 skill所以同一个技能在不同项目里可以有不同版本这个特性后面会细说。第三步是验证加载。装好后重启当前会话输入/skill命令看列表里有没有出现你刚加的技能名称。有的话就说明加载成功了。这一步看起来简单但很多人恰恰是卡在“重启了也没出现”上。2.2 路径到底放哪里不同工具的目录差异不同终端工具对 skills 的目录约定不完全一样我实际试过的有这么几种给你做个对照工具全局目录项目本地目录Claude Code~/.claude/skills/.claude/skills/Codex CLI~/.codex/skills/.codex/skills/OpenCode~/.config/opencode/skills/.opencode/skills/这里有个容易弄混的点有些老教程会把 skills 放到~/.claude/commands/或者~/.claude/plugins/下面这些目录是 slashes 命令或者插件用的规则不同。我第一次装的时候就是照着网上一个旧帖子把 skill 放到了~/.claude/commands/底下折腾了半天用/skill怎么都看不到后来才发现是目录搞错了。所以动手前先确认一下你用的工具版本对应的官方文档别用旧消息指导新版本。2.3 我遇到的三次加载失败第一次加载失败原因是“目录套娃”。GitHub 上很多 skill 仓库为了展示会把子技能放在skills/xxx路径下比如skills/code-review/SKILL.md。如果你直接把整个仓库 clone 到~/.claude/skills/下面目录结构就变成了~/.claude/skills/repo-name/skills/code-review/SKILL.md一级目录是仓库名二级目录才是code-review。Claude Code 只扫描一级目录下的技能文件夹这样嵌套两层就识别不到了。解决办法是把skills/code-review这个文件夹整个复制出来放到~/.claude/skills/的根目录下保证结构是~/.claude/skills/code-review/SKILL.md。第二次失败是 frontmatter 里面的name字段缺失。有个技能文件夹的名字叫pdf-summary但 SKILL.md 开头的name写成了pdf_reader和文件夹名对不上加载的时候报了警告AI 匹配时也出现了混乱。后来统一改成文件夹名和name一致才正常。第三次是description写得太空洞。我装了一个技能描述只有一句话“Handle file operations.”。结果实际用的时候我说“把这个 PDF 转成文字提取关键信息”AI 根本没想到要用它因为描述里没有提到 PDF、提取、关键信息这类触发词。后来我参照社区建议把 description 改成包含多个同义触发词的版本准确率立刻上来了。提示description 决定 AI 什么时候“想起”这个 skill。写得越具体触发越准。只写“Handle file operations”等于告诉 AI 这个技能只能处理“文件操作”这种宽泛话题实际场景根本匹配不到。2.4 验证 skill 被加载的快速方法除了用/skill看列表还有一个更直接的验证方法在 skill 的SKILL.md里加一行特殊的输出标记比如让 AI 在执行完任务后回复“已按 skill 流程执行”然后触发一次看是否有这句话。如果回复里出现了说明 skill 被完整加载并生效了如果没出现说明 AI 只是按照普通对话模式在回答你就要回头检查目录和 frontmatter 了。还有一个判断技巧是问 AI“你现在能使用哪些技能”不同工具的回答方式不同但多数会把已加载的 skill 名字罗列出来。注意因为模型本身的差异它未必能准确记住所有技能名所以最可靠的还是/skill命令的输出。3. 手写一个自己的 Skill以“前端开发规范审查”为例拆解格式与设计装别人的 skill 只是第一步真正让 skills 产生巨大价值的是把自己手头重复性、流程化的工作沉淀成自己的技能。毕竟每个人面对的团队规范、项目结构、输出要求都不同通用技能只能解决通用问题最贴合自己工作流的一定是自己写的。3.1 写之前先想清楚“边界”很多人第一次写 skill 容易犯一个错误把什么都塞进去恨不得写一个“万能 AI 助手”。这是不对的。skill 不是系统提示词它的定位是“特定场景下的专业工作流”边界越清晰效果越好。拿“前端开发规范审查”来说你要先想清楚几个问题这个 skill 只审查 JavaScript/TypeScript 代码还是也管 CSS 和 HTML审查的依据是什么——是你们团队自己写的规范文件还是业界通用规范输出格式是直接在对话里给建议还是生成一份完整的审查报告文件输入是什么——是让 AI 自己读项目代码还是用户粘贴代码片段我把这些问题整理成一个“功能边界表”然后再动手写设计维度我的决定输入方式用户指定文件路径或粘贴代码片段两者都支持审查范围TypeScript / React 组件代码含 JSX 语法规范来源项目根目录的FE_LINT.md不存在则用内置通用规则输出格式按“阻塞问题 / 建议优化 / 风格提示”三档列出禁止行为不自动修改代码只输出审查结果有了这个表写起来就有的放矢不会写着写着就跑偏。3.2 一份能直接改来用的 SKILL.md 示例下面是一份我实际在用的前端审查 skill 的简化版本。你可以直接复制改成你们团队的规范再使用--- name: fe-code-review description: 对前端 TypeScript/React 代码进行规范审查。当用户要求“审查前端代码”“review 组件”“检查 tsx 文件规范”或给出 .tsx/.ts 文件路径时使用。 allowed-tools: - Read - Glob - Grep --- # 前端代码规范审查 ## 审查前准备 1. 先检查项目根目录是否存在 FE_LINT.md存在则优先以该文件中的规则为准。 2. 使用 Glob 查找用户指定路径下的 .ts / .tsx 文件或读取用户粘贴的代码。 3. 限定单次审查文件数量不超过 10 个避免上下文溢出。 ## 审查维度 按以下顺序逐项检查 1. **组件结构**是否将业务逻辑与 UI 分离自定义 Hook 是否独立封装。 2. **状态管理**props 是否超过 5 个是否需要拆分组件或使用 context。 3. **样式方案**是否混用 CSS Modules 和 Tailwind类名是否语义化。 4. **类型安全**是否存在 any 类型公共函数是否缺少返回类型注解。 5. **性能隐患**是否存在不必要的 useMemo / useCallback 依赖列表渲染是否有稳定 key。 ## 输出格式 按以下三级列出问题并给出修改建议 - [阻塞] 会导致功能异常或明显性能问题的问题。 - [建议] 不符合规范但可运行的问题。 - [风格] 仅影响可读性的小问题。 每条问题必须包含文件路径、行号范围、问题描述、具体修改方式。 ## 注意事项 - 只做审查不要直接改代码。 - 用户未提供规范文件时使用内置通用规则并明确说明依据来源。3.3 从“能用”到“好用”的迭代加示例、加检查清单、加工具限制第一版 skill 通常只能说“能用”距离“好用”还有距离。我的迭代经验有三条。第一加真实案例。在 SKILL.md 里放进一两个你们团队真实出现过的典型问题示例AI 在审查时就能对照示例来判断。这比抽象描述几十条规则有效得多因为大模型对“例子”的参考能力比对“规范性条文”的执行能力强很多。第二加检查清单。把每个审查维度拆成可勾选的清单项让 AI 按照清单逐项确认避免遗漏。比如状态管理这一项可以拆成“props 数量是否超标”“是否有未使用的 setState 调用”“context 是否在组件外部解构取值”。这样 AI 的执行路径更清晰输出也更稳定。第三用好allowed-tools。在 frontmatter 里显式声明允许使用的工具等于给 AI 划定了工作范围。比如上面例子我只允许 Read、Glob、Grep 三个工具AI 就不会自作主张调用执行类工具去改代码。这一步很多人忽略但实际上是 skill 安全性控制的重要防线尤其是当你准备把 skill 分享给团队其他人用时更要限制工具权限。3.4 命名与描述的艺术description 决定 AI 什么时候想起你skill 的name和description看似只是两行元信息实际上决定了这个 skill 的生命力。name最好是“动词对象”结构比如fe-code-review、weekly-report-generator一看就知道是干什么的。description则要包含三部分适用场景、触发词、执行效果。我见过很差的 description 是“This skill handles code review.”这种描述基本等于没有。好的描述应该像这样“审查前端 TypeScript/React 代码规范按阻塞/建议/风格三级输出结果。当用户要求审查前端代码、检查 tsx 文件规范、提到组件质量问题或给出 .tsx/.ts 文件路径时使用。”这里面既有场景描述又有明确的触发词AI 匹配的准确率明显更高。写 description 的时候还有个技巧把你和同事日常对话中常说的词都放进去。比如你们的说法是“帮我看看这段代码干不干净”那“看看代码”“干净不干净”就可以写进触发词。大模型匹配描述用的是语义相似度口语化表达和书面表达它都能理解但明确写进去的触发词命中率总是最高的。4. 高热度场景下的 Skills 实战推荐数学建模、AI 漫剧与日常 Coding光会写还不够还得知道哪些场景最值得投入。我翻了近期社区里高热度的 skills 讨论主要集中在三个方向数学建模竞赛、AI 内容生产特别是 AI 漫剧、以及日常前端/Coding 提效。这几个方向的热度不是没道理的因为它们都有“流程固定、重复度高、模板化输出”的特点正好是 skills 的强项。4.1 数学建模从“生成论文模板”到“全流程提效”数学建模相关的 skills 在竞赛季特别火尤其是华为杯、国赛这类比赛前不少人会专门去找现成的建模 skill 来辅助。我自己也看过几个发现它们解决的核心痛点是三块模型选择、写作规范、数据分析。先说模型选择。建模比赛里很多队伍卡在“不知道用什么模型”一个model-selector类的 skill 可以把常见的评价模型层次分析法、熵权法、预测模型回归、时间序列、灰色预测、优化模型线性规划、遗传算法根据问题特征快速匹配。写这种 skill 的关键是把每个模型的适用条件、数据需求、局限性写明否则 AI 容易推荐一些花哨但不实用的模型。再说写作规范。论文排版是建模比赛里最容易丢分也最耗时的地方。一个paper-formatter类的 skill 可以封装 LaTeX 模板、公式编号规范、图表标签规则。你只要把论文初稿扔给它它按照规范帮你整理结构、统一格式、检查公式编号。这种技能节省的时间非常可观往年一群人熬夜调格式现在几分钟搞定。最后是敏感性分析。这类 skill 我建议自己写因为不同赛题的变量不同通用模板很难直接用。但核心套路是一致的固定分析哪些变量、变化范围多大、输出什么形式的图表。写一次以后所有比赛都能复用。注意建模 skill 辅助的是流程和表达不能替你做模型推导。我见过有的队伍过于依赖 AI 生成结果最后论文里模型和数据对不上反而吃了大亏。把 skill 定位成“提效工具”而不是“代写工具”才是正路。4.2 前端开发 skills代码审查、组件生成、样式一致前端方向是目前 skills 生态里最卷也最成熟的领域。热度最高的是代码审查类也就是我上一章示例里的那种技能。这类技能的核心价值不是替代人眼而是当一个“不厌其烦的规范检查员”把团队规范从口头传递变成自动执行。另一个很实用的是组件生成类。比如你团队定义了 Button、Modal、Table 等基础组件的标准写法写一个component-generator的 skill要求 AI 在生成组件时必须遵循团队约定包括目录结构、样式方案、props 命名、测试用例位置。这样每次新开页面都从标准组件开始代码一致性好很多review 成本也直线下降。还有样式一致性审查。这个需求往往隐性问题居多有人用内联样式有人用 CSS Modules有人直接写 Tailwind class混合在一起项目就乱了。写一个专门检查样式方案的 skill输出“混用情况清单”比靠人眼翻代码高效得多。我见过有人在团队里把这几个 skill 组合在一起形成一套“前端技能包”新代码用组件生成 skill 起步提交前用代码审查 skill 自检定期用样式审查 skill 清理技术债。这种做法很值得参考因为单个 skill 改进的是某个环节组合起来改善的是整个开发流程。4.3 AI 漫剧与内容生产把“角色设定”和“分镜脚本”变成规范产物AI 漫剧是今年内容创作圈绕不开的热词。这类内容的特点是高度模板化固定角色设定、固定画风描述、固定分镜脚本格式、固定节奏控制。每一集的内容不同但生产的流程几乎完全一致特别适合用 skills 来标准化。实际用下来最有价值的漫剧 skill 有三类。第一类是角色一致性设定封装了“角色外貌、性格、语气、代表性动作”的字段规范让 AI 在生成每集剧本时保持同一角色的设定不变避免出现上一集黑发下一集棕发的尴尬。第二类是分镜脚本生成把“场景描述、镜头运动、景别、台词、时长、转场方式”这类格式固定下来AI 生成的分镜脚本可以直接喂给绘图工具使用。第三类是画风描述词封装因为漫剧的画风描述往往是一长串风格关键词写成一个 skill 之后不用每次手动复制那串咒语。这类 skill 有个特别大的好处你可以让 AI 按固定格式批量生成多集脚本然后人工只做筛选和微调。相比每集都从零开始写整体产能拉升一个量级而且风格一致性也更有保证。内容平台对原创度的要求越来越严格模板化作业在这里反而能保证基底质量后续人工二创的空间也更清晰。4.4 推荐几个我长期在用的开源技能源和筛选方法GitHub 上 skills 仓库多如牛毛但质量参差不齐。我踩过不少坑也沉淀出一些筛选方法。首先看仓库的更新日期长期不维护的仓库里的技能大概率滞后于当前 API 能力变化建议谨慎使用。其次看 SKILL.md 里的 description 写得是否具体——一个随手写完 description 的仓库里面的技能质量通常也不高。最后看是否有独立的测试样例或使用示例这能说明作者真的跑通过。我长期在用的几个源包括社区里流行的高质量技能合集比如Superpowers系列——它是一整套面向不同场景的子技能集合适合先整体安装再按需裁剪还有各类按领域整理的 awesome 列表从数学建模到前端开发都有适合新手快速搜索。另外typesafe skills这类企业级示例也值得关注它的 skill 文件结构更规范可参考性很高适合想学习“如何把技能写到生产可用”的人。不过我想强调的是别人的 skill 只能提供通用解法真正适合你工作流的版本大概率要自己改一遍。我的习惯是先装一个开源的跑一次真实任务再按自己的需求改 SKILL.md 里的规则和示例。这个过程本身就是 skill 开发能力成长最快的方式。5. 用久了才会遇到的几件事清理、冲突、版本管理与维护心得Skills 装多了之后你会进入一个新的阶段——不再是为“没有 skill”发愁而是为“skill 太多”头疼。这个阶段的问题很少有人提前讲但几乎所有重度用户都会遇到。今天就说说我在清理和维护过程中的实际经验。5.1 skill 装多了会怎样上下文膨胀与匹配混乱很多人以为 skill 装得越多越强实际上不是这样。每个 skill 加载后都会占用上下文窗口虽然单个 skill 可能只有几千个 token但装上几十个之后累积起来就是一个不小的开销。更重要的是AI 在每轮对话里都要把你的意图和几十个 skill 的 description 做语义匹配描述相似的 skill 多了就容易触发错乱。我自己就遇到过装了一个pdf-summary和一个document-analyzer两个描述里都提到了“文档分析”。结果我让它处理 PDFAI 同时加载了两个技能输出格式反而变得混杂不如只用其中一个的时候干净。后来我把它们合并成了一个doc-insight技能问题才解决。判断 skill 是否该留我有一个简单标准看最近两周有没有实际触发过。如果一个技能两周内从没被匹配到说明它对你的工作流没有帮助要么是描述写得不够准要么是场景太窄。这时候应该优先改 description 而不是直接删掉但改完之后再观察两周仍没触发就果断清理掉。5.2 清理方法论删除、归档、重新评估的完整流程社区里关于清理 skills 的讨论很多我记得有人tibo推荐过一套“清理方法论”核心思路是先归档再删除给每个 skill 一个“观察期”。我实践下来非常有效具体流程是这样的第一步把当前所有 skill 列出来按“高频使用 / 偶尔使用 / 从未触发”三档分类。第二步把“从未触发”的 skill 移动到归档目录比如~/.claude/skills_archive/不要直接删除——因为你可能会在某个项目里突然需要它到时候从归档里找回来比重新从 GitHub 下载更省事。第三步观察两周如果归档的 skill 里有被频繁翻找、或者实际需要启用的就把它移回来同时精简它的 description。第四步归档超过一个月的直接删掉GitHub 上有原版的就记下仓库链接没有原版但以后可能用到的单独提交到自己的备份仓库。这套流程走完我的 skills 目录从七十多个降到了二十多个日常使用的匹配准确率和加载速度都有了明显提升。更重要的是留下来的每个技能我都清楚它是干什么的、为什么留而不是稀里糊涂装了一大堆。5.3 版本管理把 skills 变成“可迁移的资产”清理完剩下的 skill就是真正值得长期维护的资产了。既然是资产就得有版本管理。我强烈建议把 skills 目录纳入 Git 管理可以把整个~/.claude/skills/变成一个独立的 Git 仓库也可以放在你的 dotfiles 仓库里统一管理。具体的做法很简单cd ~/.claude/skills git init git add . git commit -m init: 初始技能库然后把仓库推到你的私有远程仓库以后换电脑、换团队、甚至换工具比如从 Claude Code 迁移到 Codex的时候只需要 clone 回来就能恢复全部技能。我用这个办法已经跨了三台设备同步技能库体验非常顺手。版本管理还有个额外的好处你可以放心大胆地改技能。改坏了用git diff看改了什么git checkout回退旧版不会因为一次实验性修改就丢掉之前调好的版本。我建议每次对 SKILL.md 做大改时都提交一次提交信息里写清楚改动原因比如“扩展触发词修复与 doc-analyzer 冲突”这样后续回溯时一目了然。5.4 我的最终建议先用手抄再收藏最后自己写skills 生态现在还处于快速演化期工具的目录约定、加载机制、甚至名词本身都可能调整。有几件事大概不会变一是流程标准化带来的效率提升是真实的二是可复用的技能资产会越来越值钱三是最贴合自己需求的技能必须自己动手磨。如果你刚开始接触 skills我的建议很简单先别急着收藏一堆仓库。找一个你每周都会做的重复性任务手动用 AI 做一遍把中间用到的指令、注意事项、输出格式记录下来然后花一个下午写成SKILL.md。这个从“手抄”到“封装”的过程比下载一百个现成的 skills 都有价值。等你写过一个完整的 skill再回头看别人的技能库你会迅速判断出哪些能直接拿来用、哪些需要改、哪些只是花架子。到那个时候skills 就不再是别人的概念而是你自己的生产力工具了。 
长河君 · 2026/10/3 11:36:52 · 阅读 1.2k 从提示词到可复用技能：Agent Skills 的安装、编写与维护指南
前阵子换了一台新电脑装好 Claude Code 后我干的第一件事不是配 API Key而是打开 GitHub 把收藏夹里几十个 skills 仓库挨个 clone 下来。有朋友笑我太折腾但我真吃过亏——最早我攒了一堆“神级 prompt”散落在各种对话记录、备忘录和网页剪藏里换台电脑等于全部清零重新调教 AI 的成本高得吓人。后来接触到 Agent Skills也就是大家常说的 skills我才意识到提示词工程已经从“会话级”进化到了“资产级”以前是每次对话都手写指令现在是写一次、存下来、到处用。这篇内容就围绕 skills 展开适合三类人刚听说 skills 这个概念、想搞明白它到底是什么的小白已经在用 Claude Code 或 Codex、但只会从 GitHub 上装现成 skill 的普通用户以及打算自己写 skill、把它变成生产力工具的进阶玩家。我会把自己手动安装、踩坑、写 skill、清理维护的完整过程都写出来争取让你看完就能直接上手。1. Skills 到底是什么从一段复制粘贴的咒语到一个可复用的“外挂大脑”先讲一个类比。以前用 AI 干活就像每次请一个临时工你得从头交代背景、流程、输出格式、注意事项。遇到复杂的活儿比如“帮我审查前端代码规范”你每次都要写一大段指令说清楚要看哪些文件、按什么标准审、输出什么格式的 report。写多了你会发现这段指令本身才是真正的生产力——AI 模型就在那里谁给的指令质量高谁拿到的结果就好。1.1 我的第一个 skill从“糊墙”到“贴瓷砖”我第一次真正理解 skills 的价值是在处理一个重复性任务的时候。当时我需要 AI 帮忙把一批 Markdown 文档统一转成项目周报格式包括标题层级、表格栏位、措辞风格、敏感信息标注方式每次手工写提示词都要花十来分钟而且稍微漏掉一个要求输出就变样。后来我照着社区里的做法把这段提示词写进一个文件夹里面放一个SKILL.md文件再用几句话描述这个 skill 是干什么的AI 就能在我需要的时候自动“想起”它。这个词叫什么不重要重要的是它让我第一次感觉到AI 的使用方式从“每次现写”变成了“随取随用”。就像装修从“每次现和水泥糊墙”变成了“预制好瓷砖按尺寸贴上去”效率完全不是一个量级。1.2 SKILL.md 的结构一段 YAML 头信息加一堆“作业指导书”一个标准的 skill本质上就是一个文件夹加一个SKILL.md主文件。文件夹的名字就是 skill 的名字SKILL.md是这个技能的说明书。说明书开头有一段 YAML 格式的 frontmatter用来声明这个 skill 的名字、描述、可用的工具后面跟着的是正文——也就是你希望 AI 在执行这个技能时遵循的完整指导。拿一个最简单的 hello world 举例--- name: weekly-report description: 将零散的 Markdown 笔记整理成项目周报格式。当用户提到“生成周报”“整理周报”或给出多篇笔记时使用。 --- # 周报生成流程 1. 读取用户提供的所有 Markdown 文档。 2. 按“本周进展 / 风险与阻塞 / 下周计划”三部分整理内容。 3. 每条进展必须注明对应负责人与完成度格式为 任务名负责人完成度%。 4. 遇到不确定的信息用 [待确认] 标记不要自行编造。这段内容看起来平平无奇但一旦放进~/.claude/skills/weekly-report/SKILL.mdClaude Code 启动后就会自动加载它。当你说“帮我把这周这几篇笔记整理成周报”AI 会把这个 skill 当成一份“岗位说明书SOP”严格按照里面的流程执行而不是临时猜你想要什么。1.3 为什么 skills 现在才火从“会话级提示词”到“资产级技能”之前不是没有类似的方案比如自定义 system prompt、保存 prompt 模板、用 MCP 挂外部工具但它们各自都有问题。自定义 system prompt 只对一个会话有效换个项目就得重新贴prompt 模板只是个文本文件AI 不会自动识别“什么时候该用”MCP 解决的是“AI 能不能操作外部工具”的问题管不了“AI 该怎么干活”的流程问题。skills 把几件事一次性解决了它有自动匹配机制靠 description 里的语义描述判断何时启用它有标准目录规范换台电脑同步一下就能恢复它还能携带脚本和资源文件不只是纯文本提示词而是把“知识”和“执行”合在了一起。我做了个表格方便你理解 skills 和传统方案的差异方案作用范围是否需要手动指定是否可携带资源文件复用难度system prompt单次会话每次手动配置否高每次都要重贴prompt 模板单次会话每次手动粘贴否中依赖你找到文件MCP 工具跨会话自动但只提供工具能力部分中要写服务端Agent Skills跨会话自动匹配启用是低文件夹即技能理解到这个层面你就知道为什么社区对 skills 的热情这么高。它不是换了个名字炒冷饭而是真正把“怎么用 AI”这件事从临场发挥变成了基础设施。2. 手动安装 GitHub 上的 Skills文件结构、路径规则与常见失败原因先说结论手动安装一个 skill 的完整流程就三步——把仓库弄到本地、放进指定目录、重启会话。但我实际操作下来这三步每一步都有坑而且很隐蔽尤其是第一次装的时候很容易掉进“明明放进去了却加载不出来”的困境。2.1 从仓库到本地的三步搬运第一步是获取 skill 文件。最常见的做法是把整个 GitHub 仓库 clone 下来。比如你看到一个叫awesome-claude-skills的仓库里面有code-review、doc-generator等子文件夹你可以只 clone 整个仓库也可以单独下载某个子文件夹。第二步是找到目标路径。Claude Code 里默认读取两个位置用户全局目录~/.claude/skills/和项目本地目录项目根目录/.claude/skills/。全局目录里放的是所有项目通用的技能本地目录放的是只属于当前项目的技能。两者的加载优先级有差异本地目录会覆盖全局同名 skill所以同一个技能在不同项目里可以有不同版本这个特性后面会细说。第三步是验证加载。装好后重启当前会话输入/skill命令看列表里有没有出现你刚加的技能名称。有的话就说明加载成功了。这一步看起来简单但很多人恰恰是卡在“重启了也没出现”上。2.2 路径到底放哪里不同工具的目录差异不同终端工具对 skills 的目录约定不完全一样我实际试过的有这么几种给你做个对照工具全局目录项目本地目录Claude Code~/.claude/skills/.claude/skills/Codex CLI~/.codex/skills/.codex/skills/OpenCode~/.config/opencode/skills/.opencode/skills/这里有个容易弄混的点有些老教程会把 skills 放到~/.claude/commands/或者~/.claude/plugins/下面这些目录是 slashes 命令或者插件用的规则不同。我第一次装的时候就是照着网上一个旧帖子把 skill 放到了~/.claude/commands/底下折腾了半天用/skill怎么都看不到后来才发现是目录搞错了。所以动手前先确认一下你用的工具版本对应的官方文档别用旧消息指导新版本。2.3 我遇到的三次加载失败第一次加载失败原因是“目录套娃”。GitHub 上很多 skill 仓库为了展示会把子技能放在skills/xxx路径下比如skills/code-review/SKILL.md。如果你直接把整个仓库 clone 到~/.claude/skills/下面目录结构就变成了~/.claude/skills/repo-name/skills/code-review/SKILL.md一级目录是仓库名二级目录才是code-review。Claude Code 只扫描一级目录下的技能文件夹这样嵌套两层就识别不到了。解决办法是把skills/code-review这个文件夹整个复制出来放到~/.claude/skills/的根目录下保证结构是~/.claude/skills/code-review/SKILL.md。第二次失败是 frontmatter 里面的name字段缺失。有个技能文件夹的名字叫pdf-summary但 SKILL.md 开头的name写成了pdf_reader和文件夹名对不上加载的时候报了警告AI 匹配时也出现了混乱。后来统一改成文件夹名和name一致才正常。第三次是description写得太空洞。我装了一个技能描述只有一句话“Handle file operations.”。结果实际用的时候我说“把这个 PDF 转成文字提取关键信息”AI 根本没想到要用它因为描述里没有提到 PDF、提取、关键信息这类触发词。后来我参照社区建议把 description 改成包含多个同义触发词的版本准确率立刻上来了。提示description 决定 AI 什么时候“想起”这个 skill。写得越具体触发越准。只写“Handle file operations”等于告诉 AI 这个技能只能处理“文件操作”这种宽泛话题实际场景根本匹配不到。2.4 验证 skill 被加载的快速方法除了用/skill看列表还有一个更直接的验证方法在 skill 的SKILL.md里加一行特殊的输出标记比如让 AI 在执行完任务后回复“已按 skill 流程执行”然后触发一次看是否有这句话。如果回复里出现了说明 skill 被完整加载并生效了如果没出现说明 AI 只是按照普通对话模式在回答你就要回头检查目录和 frontmatter 了。还有一个判断技巧是问 AI“你现在能使用哪些技能”不同工具的回答方式不同但多数会把已加载的 skill 名字罗列出来。注意因为模型本身的差异它未必能准确记住所有技能名所以最可靠的还是/skill命令的输出。3. 手写一个自己的 Skill以“前端开发规范审查”为例拆解格式与设计装别人的 skill 只是第一步真正让 skills 产生巨大价值的是把自己手头重复性、流程化的工作沉淀成自己的技能。毕竟每个人面对的团队规范、项目结构、输出要求都不同通用技能只能解决通用问题最贴合自己工作流的一定是自己写的。3.1 写之前先想清楚“边界”很多人第一次写 skill 容易犯一个错误把什么都塞进去恨不得写一个“万能 AI 助手”。这是不对的。skill 不是系统提示词它的定位是“特定场景下的专业工作流”边界越清晰效果越好。拿“前端开发规范审查”来说你要先想清楚几个问题这个 skill 只审查 JavaScript/TypeScript 代码还是也管 CSS 和 HTML审查的依据是什么——是你们团队自己写的规范文件还是业界通用规范输出格式是直接在对话里给建议还是生成一份完整的审查报告文件输入是什么——是让 AI 自己读项目代码还是用户粘贴代码片段我把这些问题整理成一个“功能边界表”然后再动手写设计维度我的决定输入方式用户指定文件路径或粘贴代码片段两者都支持审查范围TypeScript / React 组件代码含 JSX 语法规范来源项目根目录的FE_LINT.md不存在则用内置通用规则输出格式按“阻塞问题 / 建议优化 / 风格提示”三档列出禁止行为不自动修改代码只输出审查结果有了这个表写起来就有的放矢不会写着写着就跑偏。3.2 一份能直接改来用的 SKILL.md 示例下面是一份我实际在用的前端审查 skill 的简化版本。你可以直接复制改成你们团队的规范再使用--- name: fe-code-review description: 对前端 TypeScript/React 代码进行规范审查。当用户要求“审查前端代码”“review 组件”“检查 tsx 文件规范”或给出 .tsx/.ts 文件路径时使用。 allowed-tools: - Read - Glob - Grep --- # 前端代码规范审查 ## 审查前准备 1. 先检查项目根目录是否存在 FE_LINT.md存在则优先以该文件中的规则为准。 2. 使用 Glob 查找用户指定路径下的 .ts / .tsx 文件或读取用户粘贴的代码。 3. 限定单次审查文件数量不超过 10 个避免上下文溢出。 ## 审查维度 按以下顺序逐项检查 1. **组件结构**是否将业务逻辑与 UI 分离自定义 Hook 是否独立封装。 2. **状态管理**props 是否超过 5 个是否需要拆分组件或使用 context。 3. **样式方案**是否混用 CSS Modules 和 Tailwind类名是否语义化。 4. **类型安全**是否存在 any 类型公共函数是否缺少返回类型注解。 5. **性能隐患**是否存在不必要的 useMemo / useCallback 依赖列表渲染是否有稳定 key。 ## 输出格式 按以下三级列出问题并给出修改建议 - [阻塞] 会导致功能异常或明显性能问题的问题。 - [建议] 不符合规范但可运行的问题。 - [风格] 仅影响可读性的小问题。 每条问题必须包含文件路径、行号范围、问题描述、具体修改方式。 ## 注意事项 - 只做审查不要直接改代码。 - 用户未提供规范文件时使用内置通用规则并明确说明依据来源。3.3 从“能用”到“好用”的迭代加示例、加检查清单、加工具限制第一版 skill 通常只能说“能用”距离“好用”还有距离。我的迭代经验有三条。第一加真实案例。在 SKILL.md 里放进一两个你们团队真实出现过的典型问题示例AI 在审查时就能对照示例来判断。这比抽象描述几十条规则有效得多因为大模型对“例子”的参考能力比对“规范性条文”的执行能力强很多。第二加检查清单。把每个审查维度拆成可勾选的清单项让 AI 按照清单逐项确认避免遗漏。比如状态管理这一项可以拆成“props 数量是否超标”“是否有未使用的 setState 调用”“context 是否在组件外部解构取值”。这样 AI 的执行路径更清晰输出也更稳定。第三用好allowed-tools。在 frontmatter 里显式声明允许使用的工具等于给 AI 划定了工作范围。比如上面例子我只允许 Read、Glob、Grep 三个工具AI 就不会自作主张调用执行类工具去改代码。这一步很多人忽略但实际上是 skill 安全性控制的重要防线尤其是当你准备把 skill 分享给团队其他人用时更要限制工具权限。3.4 命名与描述的艺术description 决定 AI 什么时候想起你skill 的name和description看似只是两行元信息实际上决定了这个 skill 的生命力。name最好是“动词对象”结构比如fe-code-review、weekly-report-generator一看就知道是干什么的。description则要包含三部分适用场景、触发词、执行效果。我见过很差的 description 是“This skill handles code review.”这种描述基本等于没有。好的描述应该像这样“审查前端 TypeScript/React 代码规范按阻塞/建议/风格三级输出结果。当用户要求审查前端代码、检查 tsx 文件规范、提到组件质量问题或给出 .tsx/.ts 文件路径时使用。”这里面既有场景描述又有明确的触发词AI 匹配的准确率明显更高。写 description 的时候还有个技巧把你和同事日常对话中常说的词都放进去。比如你们的说法是“帮我看看这段代码干不干净”那“看看代码”“干净不干净”就可以写进触发词。大模型匹配描述用的是语义相似度口语化表达和书面表达它都能理解但明确写进去的触发词命中率总是最高的。4. 高热度场景下的 Skills 实战推荐数学建模、AI 漫剧与日常 Coding光会写还不够还得知道哪些场景最值得投入。我翻了近期社区里高热度的 skills 讨论主要集中在三个方向数学建模竞赛、AI 内容生产特别是 AI 漫剧、以及日常前端/Coding 提效。这几个方向的热度不是没道理的因为它们都有“流程固定、重复度高、模板化输出”的特点正好是 skills 的强项。4.1 数学建模从“生成论文模板”到“全流程提效”数学建模相关的 skills 在竞赛季特别火尤其是华为杯、国赛这类比赛前不少人会专门去找现成的建模 skill 来辅助。我自己也看过几个发现它们解决的核心痛点是三块模型选择、写作规范、数据分析。先说模型选择。建模比赛里很多队伍卡在“不知道用什么模型”一个model-selector类的 skill 可以把常见的评价模型层次分析法、熵权法、预测模型回归、时间序列、灰色预测、优化模型线性规划、遗传算法根据问题特征快速匹配。写这种 skill 的关键是把每个模型的适用条件、数据需求、局限性写明否则 AI 容易推荐一些花哨但不实用的模型。再说写作规范。论文排版是建模比赛里最容易丢分也最耗时的地方。一个paper-formatter类的 skill 可以封装 LaTeX 模板、公式编号规范、图表标签规则。你只要把论文初稿扔给它它按照规范帮你整理结构、统一格式、检查公式编号。这种技能节省的时间非常可观往年一群人熬夜调格式现在几分钟搞定。最后是敏感性分析。这类 skill 我建议自己写因为不同赛题的变量不同通用模板很难直接用。但核心套路是一致的固定分析哪些变量、变化范围多大、输出什么形式的图表。写一次以后所有比赛都能复用。注意建模 skill 辅助的是流程和表达不能替你做模型推导。我见过有的队伍过于依赖 AI 生成结果最后论文里模型和数据对不上反而吃了大亏。把 skill 定位成“提效工具”而不是“代写工具”才是正路。4.2 前端开发 skills代码审查、组件生成、样式一致前端方向是目前 skills 生态里最卷也最成熟的领域。热度最高的是代码审查类也就是我上一章示例里的那种技能。这类技能的核心价值不是替代人眼而是当一个“不厌其烦的规范检查员”把团队规范从口头传递变成自动执行。另一个很实用的是组件生成类。比如你团队定义了 Button、Modal、Table 等基础组件的标准写法写一个component-generator的 skill要求 AI 在生成组件时必须遵循团队约定包括目录结构、样式方案、props 命名、测试用例位置。这样每次新开页面都从标准组件开始代码一致性好很多review 成本也直线下降。还有样式一致性审查。这个需求往往隐性问题居多有人用内联样式有人用 CSS Modules有人直接写 Tailwind class混合在一起项目就乱了。写一个专门检查样式方案的 skill输出“混用情况清单”比靠人眼翻代码高效得多。我见过有人在团队里把这几个 skill 组合在一起形成一套“前端技能包”新代码用组件生成 skill 起步提交前用代码审查 skill 自检定期用样式审查 skill 清理技术债。这种做法很值得参考因为单个 skill 改进的是某个环节组合起来改善的是整个开发流程。4.3 AI 漫剧与内容生产把“角色设定”和“分镜脚本”变成规范产物AI 漫剧是今年内容创作圈绕不开的热词。这类内容的特点是高度模板化固定角色设定、固定画风描述、固定分镜脚本格式、固定节奏控制。每一集的内容不同但生产的流程几乎完全一致特别适合用 skills 来标准化。实际用下来最有价值的漫剧 skill 有三类。第一类是角色一致性设定封装了“角色外貌、性格、语气、代表性动作”的字段规范让 AI 在生成每集剧本时保持同一角色的设定不变避免出现上一集黑发下一集棕发的尴尬。第二类是分镜脚本生成把“场景描述、镜头运动、景别、台词、时长、转场方式”这类格式固定下来AI 生成的分镜脚本可以直接喂给绘图工具使用。第三类是画风描述词封装因为漫剧的画风描述往往是一长串风格关键词写成一个 skill 之后不用每次手动复制那串咒语。这类 skill 有个特别大的好处你可以让 AI 按固定格式批量生成多集脚本然后人工只做筛选和微调。相比每集都从零开始写整体产能拉升一个量级而且风格一致性也更有保证。内容平台对原创度的要求越来越严格模板化作业在这里反而能保证基底质量后续人工二创的空间也更清晰。4.4 推荐几个我长期在用的开源技能源和筛选方法GitHub 上 skills 仓库多如牛毛但质量参差不齐。我踩过不少坑也沉淀出一些筛选方法。首先看仓库的更新日期长期不维护的仓库里的技能大概率滞后于当前 API 能力变化建议谨慎使用。其次看 SKILL.md 里的 description 写得是否具体——一个随手写完 description 的仓库里面的技能质量通常也不高。最后看是否有独立的测试样例或使用示例这能说明作者真的跑通过。我长期在用的几个源包括社区里流行的高质量技能合集比如Superpowers系列——它是一整套面向不同场景的子技能集合适合先整体安装再按需裁剪还有各类按领域整理的 awesome 列表从数学建模到前端开发都有适合新手快速搜索。另外typesafe skills这类企业级示例也值得关注它的 skill 文件结构更规范可参考性很高适合想学习“如何把技能写到生产可用”的人。不过我想强调的是别人的 skill 只能提供通用解法真正适合你工作流的版本大概率要自己改一遍。我的习惯是先装一个开源的跑一次真实任务再按自己的需求改 SKILL.md 里的规则和示例。这个过程本身就是 skill 开发能力成长最快的方式。5. 用久了才会遇到的几件事清理、冲突、版本管理与维护心得Skills 装多了之后你会进入一个新的阶段——不再是为“没有 skill”发愁而是为“skill 太多”头疼。这个阶段的问题很少有人提前讲但几乎所有重度用户都会遇到。今天就说说我在清理和维护过程中的实际经验。5.1 skill 装多了会怎样上下文膨胀与匹配混乱很多人以为 skill 装得越多越强实际上不是这样。每个 skill 加载后都会占用上下文窗口虽然单个 skill 可能只有几千个 token但装上几十个之后累积起来就是一个不小的开销。更重要的是AI 在每轮对话里都要把你的意图和几十个 skill 的 description 做语义匹配描述相似的 skill 多了就容易触发错乱。我自己就遇到过装了一个pdf-summary和一个document-analyzer两个描述里都提到了“文档分析”。结果我让它处理 PDFAI 同时加载了两个技能输出格式反而变得混杂不如只用其中一个的时候干净。后来我把它们合并成了一个doc-insight技能问题才解决。判断 skill 是否该留我有一个简单标准看最近两周有没有实际触发过。如果一个技能两周内从没被匹配到说明它对你的工作流没有帮助要么是描述写得不够准要么是场景太窄。这时候应该优先改 description 而不是直接删掉但改完之后再观察两周仍没触发就果断清理掉。5.2 清理方法论删除、归档、重新评估的完整流程社区里关于清理 skills 的讨论很多我记得有人tibo推荐过一套“清理方法论”核心思路是先归档再删除给每个 skill 一个“观察期”。我实践下来非常有效具体流程是这样的第一步把当前所有 skill 列出来按“高频使用 / 偶尔使用 / 从未触发”三档分类。第二步把“从未触发”的 skill 移动到归档目录比如~/.claude/skills_archive/不要直接删除——因为你可能会在某个项目里突然需要它到时候从归档里找回来比重新从 GitHub 下载更省事。第三步观察两周如果归档的 skill 里有被频繁翻找、或者实际需要启用的就把它移回来同时精简它的 description。第四步归档超过一个月的直接删掉GitHub 上有原版的就记下仓库链接没有原版但以后可能用到的单独提交到自己的备份仓库。这套流程走完我的 skills 目录从七十多个降到了二十多个日常使用的匹配准确率和加载速度都有了明显提升。更重要的是留下来的每个技能我都清楚它是干什么的、为什么留而不是稀里糊涂装了一大堆。5.3 版本管理把 skills 变成“可迁移的资产”清理完剩下的 skill就是真正值得长期维护的资产了。既然是资产就得有版本管理。我强烈建议把 skills 目录纳入 Git 管理可以把整个~/.claude/skills/变成一个独立的 Git 仓库也可以放在你的 dotfiles 仓库里统一管理。具体的做法很简单cd ~/.claude/skills git init git add . git commit -m init: 初始技能库然后把仓库推到你的私有远程仓库以后换电脑、换团队、甚至换工具比如从 Claude Code 迁移到 Codex的时候只需要 clone 回来就能恢复全部技能。我用这个办法已经跨了三台设备同步技能库体验非常顺手。版本管理还有个额外的好处你可以放心大胆地改技能。改坏了用git diff看改了什么git checkout回退旧版不会因为一次实验性修改就丢掉之前调好的版本。我建议每次对 SKILL.md 做大改时都提交一次提交信息里写清楚改动原因比如“扩展触发词修复与 doc-analyzer 冲突”这样后续回溯时一目了然。5.4 我的最终建议先用手抄再收藏最后自己写skills 生态现在还处于快速演化期工具的目录约定、加载机制、甚至名词本身都可能调整。有几件事大概不会变一是流程标准化带来的效率提升是真实的二是可复用的技能资产会越来越值钱三是最贴合自己需求的技能必须自己动手磨。如果你刚开始接触 skills我的建议很简单先别急着收藏一堆仓库。找一个你每周都会做的重复性任务手动用 AI 做一遍把中间用到的指令、注意事项、输出格式记录下来然后花一个下午写成SKILL.md。这个从“手抄”到“封装”的过程比下载一百个现成的 skills 都有价值。等你写过一个完整的 skill再回头看别人的技能库你会迅速判断出哪些能直接拿来用、哪些需要改、哪些只是花架子。到那个时候skills 就不再是别人的概念而是你自己的生产力工具了。