最近我身边越来越多的人在讨论 Claude Code、Codex 这些 AI 编程工具里的skills。说得直白一点这个功能火起来只有一个原因它让同一套模型在不同人手里变成了两种不同水准的工具。同样一个数据分析任务有人让 AI 现场发挥生成一堆晦涩代码自己慢慢改有人却通过一个写好的 skill让 AI 自动把报告拆成摘要、图表、结论三段输出格式稳定到可以直接交付。这里的差距不在模型而在有没有一套可复用的行为手册。这篇文章我打算把 skills 从头到尾讲透它到底是什么、为什么能改变 AI 的输出质量、怎么手动装 GitHub 上的现成 skills、怎么写一个自己的 skill、以及哪些 sources 值得长期收藏。内容全部来自我这几个月在真实项目里反复试错总结出来的经验偏实操尽量少讲虚的。如果你刚接触这个概念耐心读完前两章基本就能上手如果你已经在写自己的 skills重点看第三章的调试思路和第四章的清理维护应该能帮你少踩几个坑。1. Skills不是插件是AI的第二套行为手册1.1 先从一个让我印象深刻的例子说起上个月我让 AI 帮忙整理一份项目周报。直接输入 prompt 的时候它给出一段很标准的周报本周完成、下周计划、风险点三个板块措辞干巴巴的像极了应届生第一天上班写的模板。后来我换了一套写法给它加载了一个周报生成的 skill。同样是这个模型、同一个对话上下文结果变成了一份带数据口径说明、带风险分级、甚至自动标注哪些指标需要人工复核的报告。更重要的不是内容变好了多少而是每次输出都稳定在这个水准不会因为今天 prompt 写得详细一点就好一点、明天写得潦草就垮掉。这个例子很好地解释了 skills 的价值它不是给 AI 增加新功能而是给 AI 增加一段稳定的行为约束。1.2 Skills的底层机制就是行为文档 文件系统很多第一次接触 skills 的人会把它理解成AI 插件或者更长的 prompt这个理解不能说错但会误导你后续的开发和排错思路。拆开看一个 skill 本质上就是一个文件夹里面装了一份叫SKILL.md的 Markdown 文档外加一些可选的参考资料和辅助脚本。以 Claude Code 为例典型的目录结构长这样~/.claude/skills/ # Claude Code 的全局技能目录 └── paper-review/ # 每个技能一个独立文件夹 ├── SKILL.md # 技能的核心行为文档 ├── references/ # 参考资料目录 │ └── 摘要模板.md └── scripts/ # 辅助脚本目录 └── check_format.pySKILL.md的开头有一段 YAML 格式的 frontmatter里面最重要的字段是description。这一段描述决定了 AI 在什么时候想起使用这个技能。正文部分则用普通 Markdown 写清楚这个技能的目标是什么、应该按什么步骤执行、哪些事情绝对不能做。你可以把它理解成给 AI 一本岗位手册而不是每次口头叮嘱一遍。普通 prompt 是你今天帮我这样做一下skill 是以后遇到这类事你都按这个手册来。我用一个表格概括目前主流工具对 skills 的支持情况方便你对号入座工具技能目录位置触发方式我的实测感受Claude Code~/.claude/skills/根据 description 自动匹配最成熟官方支持力度最大Codex CLI~/.codex/skills/或项目内.codex/skills/根据 description 自动匹配需要较新版本兼容性略逊OpenCode项目内.opencode/skills/等通过 agent 工具加载社区驱动配置灵活但文档分散注意上面这个表里我给的是常见路径不同版本的工具可能会有调整装之前先看一眼官方文档是最稳的。1.3 为什么比直接写prompt更管用这个问题我思考了很久后来找到了三个比较扎实的理由。第一个理由是触发的一致性。普通的 prompt 靠人每次输入你写得全AI 就执行得全你写得偷懒AI 也跟着偷懒。而 skill 的 description 字段一旦写好AI 会在适合的场景自动加载对应技能不需要你每次重复交代背景和要求。这种自动触发看起来是小改进实际体验差别非常大。第二个理由是节省上下文窗口。一个完整、严谨的 prompt 动辄一两千字如果每轮对话都塞进去上下文窗口很快就被吃掉了。skill 只有在被触发的时候才加载进模型视野日常对话不受影响。尤其在做长任务的时候这个优势会被放大。第三个理由是行为可迭代。prompt 是一次性的用完就没了skill 是一份文件随时可以改。我经常在项目里发现某个步骤写得不够清楚模型执行时理解偏了于是直接改SKILL.md里的对应段落下次执行马上变好。这种把经验沉淀成文件的体验用惯了真的回不去。不过也要提醒一句不是什么任务都适合做成 skill。我见过有人把写一封邮件这种一次性、琐碎、变化极大的任务也做成 skill结果 description 写得太泛导致 AI 动不动就加载这个技能反而干扰了正常对话。技能的核心适用场景是那些你会重复做、且流程相对固定、产出标准明确的任务。2. 手动安装GitHub上的Skills目录、路径和验证2.1 动手前先确认你的工具版本很多人在 GitHub 上看到一个 skills 仓库直接就问怎么装。实际上不同 AI 工具对 skills 的支持程度和目录约定并不完全一致第一步应该是确认你正在用的工具版本。以 Claude Code 为例skills 功能需要较新的版本才支持老版本可能没有~/.claude/skills/这个目录。Codex CLI 则是对技能这个概念有自己的一套实现部分仓库里的 strap 方式并不通用。我建议装任何 skills 之前先用下面这个命令确认一下环境# 检查 Claude Code 版本不同工具的检查命令不同这里是示例 claude --version # 确认技能目录是否存在不存在就手动创建 ls ~/.claude/skills 2/dev/null || mkdir -p ~/.claude/skills这一步花不了两分钟但能省掉后面一大半的排查时间。我一开始就是没搞清版本装完技能不生效以为是技能本身的问题折腾了半天才发现是工具版本太老根本不支持。2.2 手动安装的完整步骤安装 GitHub 上的 skill我的习惯方式是手动安装而不是依赖自动脚本。自动脚本虽然方便但你不知道它会往系统里塞什么手动安装的每一步都是可控的。以安装anthropics/skills官方仓库里的某个技能为例完整步骤如下# 1. 把仓库 clone 到临时目录 git clone https://github.com/anthropics/skills.git /tmp/anthropic-skills # 2. 进入仓库看清楚目录结构 cd /tmp/anthropic-skills ls -la # 3. 把需要的技能目录复制到 Claude Code 的全局技能目录 cp -r /tmp/anthropic-skills/技能名 ~/.claude/skills/ # 4. 验证目录结构是否正确 ls ~/.claude/skills/技能名/这里有一个常见的误区有人图省事直接把整个仓库复制到~/.claude/skills/下面结果仓库里的文档、配置文件全部被当成技能文件夹扫描轻则技能列表混乱重则出现两个技能 description 冲突AI 频繁加载错技能。记住一个技能就是一个独立的子目录复制的时候只复制这一个目录。另外Windows 用户注意路径差异。Claude Code 在 Windows 上的技能目录通常在用户主目录下路径格式类似C:\Users\你的用户名\.claude\skills\。如果你用的是 WSL目录路径又要按 WSL 的文件系统来定位。别小看这个细节路径错了技能文件就在那里但 AI 就是看不见。装完之后一定要重启会话。技能加载发生在会话启动阶段你在一个已经跑着的对话里装好技能它是不会被识别的。这个细节我踩过不止一次。2.3 SKILL.md里的元数据到底写了什么既然要手动安装你就得能看懂技能目录里的SKILL.md在写什么。随便打开一个技能文件你大概率会看到这样的结构--- name: review-math-paper description: 用于数学建模竞赛论文的审查与润色。当用户提到建模论文、优化摘要、规范公式格式时使用。 license: MIT --- # 建模论文审查与润色 ## 目标 按照竞赛标准审查建模论文重点检查摘要、模型假设、公式规范、图表标注。 ## 执行步骤 1. 通读全文提取核心模型与结论 2. 审查摘要是否包含背景、问题、方法、结果四要素 3. ...这段 frontmatter 里有三个字段值得你重点关注name技能的唯一标识相当于它的身份证号。起名最好用动词对象的格式比如review-math-paper、generate-weekly-report好认也好引用。description决定触发时机的关键字段。它写得越具体、越贴近真实任务描述AI 越能准确判断什么时候该用这个技能。反过来如果 description 写得太短太泛比如只写用于论文处理AI 会在各种无关场景都尝试加载它效果反而一团糟。license这个字段主要做合规提示。虽然个人使用一般影响不大但如果你要把别人的技能改完放进团队项目最好保留原作者的 license 声明。从安装者的角度看你需要检查的最大信息就是description。很多 GitHub 仓库里的技能 description 写得很随意装进自己的环境后要么永远不触发要么频繁误触发。遇到这种情况不用急着删自己改一下 description 再放回去通常就能解决问题。2.4 安装后不生效的排查链路我在各种社区见过太多为什么装完 skills 没反应的求助帖了这里把排查思路完整写一遍你照着走一遍基本能找到问题。第一步检查目录层级。最常见的问题是技能文件多套了一层文件夹。比如你复制之后变成~/.claude/skills/paper-review/paper-review/SKILL.mdAI 扫描的时候会找不到paper-review/SKILL.md自然就不会加载。正确的结构应该是~/.claude/skills/paper-review/SKILL.md技能目录下直接就是 SKILL.md不能再嵌套一层同名目录。第二步检查文件名。有些仓库里的文件名是skill.md或者SKILL.md.txt大小写和扩展名差了都不行。Claude Code 找的是精确的SKILL.md文件名不匹配等于没装。第三步检查 description 的匹配度。你可以在对话里主动用接近 description 的说法描述任务看 AI 是否加载技能。如果加了明显相关的关键词还是不触发建议直接看工具日志里的模型调用记录确认技能有没有被模型读到。Claude Code 里可以用 verbose 模式查看上下文加载情况这一步能看到技能文件是否真正进入了模型视野。第四步也是最容易被忽略的确认没有其他技能在争抢同一个场景。如果你的技能库里已经有五六个写报告相关的技能description 写得相似模型可能会犹豫到底加载哪一个结果一个都不加载。这种情况我会先把其他技能的 description 改得更专一降低冲突概率。3. 自己写一个Skill从0到1的实战拆解3.1 用数学建模场景设计一个Skill说完手动安装进入更进阶也更实用的部分自己写 skill。很多人觉得写技能很难其实它的门槛比想象中低。你只需要一份 Markdown 文档把遇到这类任务时该怎么做写清楚就行。我用今年华为杯数学建模竞赛这个高频场景来举例。建模论文有一个很典型的特点模型做得好不好是一回事论文能不能让评委快速看懂是另一回事。很多队伍倒在三天的最后一晚论文草草成型摘要没有竞争力公式排版混乱。我给自己写过一个建模论文审查与润色的 skillSKILL.md的核心内容大致是这样的--- name: review-math-paper description: 用于数学建模竞赛论文的审查与润色。当用户要求检查建模论文、优化摘要、规范公式符号、提升图表表现力时使用。 --- # 建模论文审查与润色 ## 目标 按照国赛/华为杯评审标准审查论文输出结构化修改建议。 ## 执行步骤 1. 通读全文提取论文的核心问题、模型方法、实验结论。 2. 审查摘要 - 是否包含背景、问题、方法、结果四要素 - 是否出现本文开头的空洞表述若有则改写为具体内容 - 摘要字数是否控制在 500 字以内 3. 审查模型假设 - 假设是否与题目约束一一对应 - 是否存在明显不合理的强假设 4. 审查公式 - 所有变量是否有定义 - 公式编号是否连续 - 符号是否全文统一 5. 审查图表 - 图题、表题是否自明 - 是否在正文中有引用位置 ## 禁止事项 - 不得虚构实验数据 - 不得删除主要模型只用备用模型 - 不建议在不清楚题意的情况下擅自改结论这份文档写得很朴素但它抓住了建模论文评审最重要的几个检查点。AI 加载之后会按照这个步骤逐项审查输出比帮我看看论文稳定得多的结果。3.2 三个写出高质量Skill的原则写了几十份 skill 之后我总结出三个核心原则分享给你。第一个原则是单任务聚焦。一个技能只解决一类问题。比如生成周报就是生成周报不要在里面顺带写顺便把下周计划也排了。任务越杂模型的注意力越分散执行效果越差。我更倾向于把一个大任务拆成两三个小技能分别维护。第二个原则是步骤要可执行。所谓可执行就是模型看到步骤后不需要再猜我到底该干什么。举例来说审查摘要就不够具体因为模型不知道审查是指什么标准而检查摘要是否包含背景、问题、方法、结果四要素就是可执行的模型可以直接拿这个清单去比对。你在写技能时把自己想象成在给实习生写工作说明步骤里不允许出现需要对方悟的内容。第三个原则是写清不做什么。这个最容易被忽略但也最实用。你告诉 AI 不要虚构数据、不要擅自删改结论、不要在不确定时编造引用它就能避免很多低级错误。我在实践中发现负向约束往往比正向指令更影响最终质量因为大模型天然倾向于自由发挥你得把发挥的空间收紧。3.3 References、Scripts和调试流程写完SKILL.md之后技能文件夹里还能放两类东西references/和scripts/。references/目录适合放相对稳定的参考资料。还拿数学建模举例我可以把国赛论文的摘要模板、往年的评审要点摘要、常见符号规范说明放在references/里。SKILL.md中用相对路径引用这些文件模型在执行时可以按需阅读。这样主文档保持精简参考资料又不至于丢失。scripts/目录则适合放辅助脚本。比如我写过一个简单的格式检查脚本check_format.py用来统计论文关键部分字数import re import sys # 简单示例统计摘要段落字数和本文开头的句子 def check_abstract(text_path): with open(text_path, r, encodingutf-8) as f: text f.read() words len(re.sub(r\s, , text)) print(f总字数{words}) if text.strip().startswith(本文): print(提示摘要开头避免使用‘本文’这类空洞表述) if __name__ __main__: check_abstract(sys.argv[1])注意脚本不是必须的。很多优质 skill 只有一份SKILL.md就能运转良好。脚本的价值在于处理那些模型不擅长的确定性检查比如字数统计、格式正则、文件批量操作。如果你还在入门阶段我建议先不碰 scripts把SKILL.md写好在说。调试 skill 的推荐流程我自己习惯这样先用一个小型示例任务测试。比如刚写好建模论文审查skill就找一篇旧论文让 AI 审查看它输出的建议是否切中要害。观察 AI 是否遵守了SKILL.md里的步骤顺序。如果它跳过某一步大概率是那一步的表达不够清晰或者步骤太多导致模型记不住需要精简。修改后再次测试直到输出稳定。最终把测试用的示例任务换成真实任务跑几轮确认通用性。这个流程看起来简单但非常有效。我见过不少人写完技能不测试就直接上生产出了问题也不知道是技能的问题还是 prompt 的问题最后只能推倒重来。3.4 一个让SKILL.md更耐用的技巧给步骤编号并注明原因这里补充一个我比较得意的写法习惯在关键步骤后面用括号或加粗注明为什么这样做。表面上看这行文字模型不会直接执行但它能显著提升模型对步骤的理解。比如检查摘要四要素后面加一句评委通常只看摘要判断论文水平模型执行时会更有侧重点。这不是玄学。大模型的推理能力在得到背景原因之后会明显增强一个孤零零的指令和一个带上下文背景的指令执行效果差距往往超出你的预期。4. 值得收藏的Skills源与实战场景选择4.1 两类值得长期收藏的GitHub源经常有人问常用 skills 源网站有哪些我观察到的优质技能来源大致可以分为两类。第一类是官方仓库典型代表是anthropics/skills。这里面的技能质量参差不齐有些是官方示例级别的但正因为官方维护目录结构和元数据规范非常适合用来学习一个标准 SKILL.md 应该怎么组织。第二类是垂直场景的社区仓库。比如typesafe等团队维护的 AI skills 集合质量就普遍较高而且覆盖了很多企业级场景。另外GitHub 上搜索awesome-ai-skills这类合集仓库也能找到大量分类整理好的技能列表。我自己的习惯是不直接收藏十几二十个仓库而是隔一段时间去搜一下某个具体场景的关键词找到那个场景里 star 最高的技能仓库只装我当下用得到的部分。技能这东西和其他开源项目不一样它不是越多越好装多了反而互相干扰。如果你想给别人推荐常用 skills 源网站我不想直接给你列十个链接然后不管了——更值得推荐的思路是上面这一段知道去哪里找、怎么判断质量、怎么按需筛选。我自己反复用、效果稳定的源其实一只手数得过来。真正高效的用法不是收藏一大堆而是用的时候能找到、选得准。4.2 按场景选Skill而不是按名气选场景和技能的匹配是比安装更值得思考的问题。拿华为杯建模这个具体场景来说适合的技能组合和我平时写代码的场景完全不一样。建模比赛时间短、任务重最有价值的技能是论文质量审查和结果可视化自动出图这两个方向。前者提高交付质量后者节省大量时间。相比之下代码规范审查这种技能在建模场景里价值就低很多因为比赛代码基本不会进入交付物。AI 漫剧又是另一个典型场景。做漫剧的人需要的是分镜生成、字幕对齐、批量抠图这一类的技能更需要配合图像处理脚本。你让一个通用的写作辅助技能去干这个活效率会低得让人着急。所以我的建议是先列清楚你未来一个月要做哪几类重复任务再针对性地找技能。技能是为任务服务的不是为了让你的工具库显得专业而存在。一个日常只写前端代码的人装一堆数据科学的技能除了增加 AI 的决策困扰没有任何好处。4.3 装多了之后清理与维护技能装多了以后最典型的问题就是 AI 会频繁加载错误的技能。我曾在社区里看到过一位开发者分享的清理思路核心观点我现在都很认同技能的 description 是有限度的多个技能描述相似场景时模型会越来越迷失。整理不是删几个文件夹那么简单而是要让每个技能的 description 都指向完全不同的、不重叠的任务空间。我的清理节奏是每两周做一次。具体操作分三步用ls ~/.claude/skills/列出现有技能根据名字回忆上次使用时间。对一个月没触发过的技能先看它的 description如果描述特别宽泛说明它大概率是备胎技能改成更狭窄的描述。如果改造后依然不常用直接移到一个archive/目录而不是彻底删除。这样需要的时候还能找回但不会干扰 AI 的技能路由。清理这件事看起来不产生新东西但对你 AI 工具的整体表现影响很大。我清理过一次之后明显感觉技能触发准确率提升了很多模型答非所问的情况变少了输出稳定性也上来了。定期维护技能库就像定期整理你的工作台一样东西越规整效率越高——这也是我自己始终推荐的做法。5. 写在最后我的使用习惯和建议最后分享几个我在实际操作中形成的习惯也许对你直接有用。第一个习惯是给技能起名尽量用英文。虽然描述内容可以写中文但name字段用英文单词加连字符的格式在引用、路径处理和命令操作时都更省心。比如review-math-paper就比论文审查好使。第二个习惯是控制 SKILL.md 的长度。我一般控制在 30 到 50 行以内步骤不超过 8 条。太长的技能文档模型读一遍的成本很高执行时反而容易顾此失彼。如果发现技能内容实在很多果断拆分成两个技能。第三个习惯是把技能目录纳入版本管理。我把~/.claude/skills/里自己写的部分单独放在一个 git 仓库里每次改动都有记录团队新成员 clone 下来直接就能用。这比用聊天记录传递 prompt 高效太多。还有一个细节想特别强调技能里的每一个步骤都应该是模型能执行的动作。我见过有人写出深入分析问题背后的深层逻辑这种玄幻表述模型看到这种词只会飘在空中。技能文档写清楚做什么、按什么顺序做、做到什么程度算完就够了水平高低不在措辞的华丽而在反馈的复用。写 skills 这几周最大的感受是AI 工具的使用水平终归会落在你把经验沉淀得多好。一份过硬的行为手册比一百句临时的帮我看一下值钱得多。希望这篇实战拆解能帮到你也欢迎你在实践中摸索出更多玩法后把经验分享给更多人。
