AI编程Skills实战指南：从安装到自写的完整教程

1. 先拆解：skills到底是什么，和插件、Agent提示词有什么本质区别

最近群里聊AI编程，几乎每三天就有人问一句“skills到底怎么装”。我一开始也以为这是某个新出的IDE插件，直到自己动手在Claude Code里跑了几个skills，才明白这东西和普通插件完全是两回事。简单说，skills是给AI Agent使用的一套“操作手册”，它不只是告诉模型“你要做什么”，而是把做这件事的完整流程、工具调用方式、输出格式、判断标准都写进一个结构化的文件里，让模型在执行具体任务时能按图索骥。

我自己第一次接触到skills，是从Anthropic官方的skills仓库开始的。那个仓库里放了几十个不同领域的skills，从网页开发到数据分析都有。当时我特别好奇，为什么同一个模型，在不加载skills的时候写代码总感觉“差点意思”，一旦加载了对应的skills，表现立刻稳定了一个档次。后来仔细翻了几个SKILL.md文件才明白，skills的本质是把隐性的专家经验显式化。

举个例子，如果你让Claude Code直接“画一个网页”，它可能会给出一个中规中矩的HTML页面。但如果你加载了一个“前端开发skills”，这个skills里会写清楚：页面需要分几个模块、响应式断点怎么设、样式变量怎么命名、甚至是交互细节的验收标准。模型在生成时就不是“自由发挥”，而是像照着SOP作业一样，一步步满足你的预期。这就是skills和普通prompt最大的区别——它提供了可复用的、结构化的执行框架。

还有一个容易混淆的概念是“插件”。传统IDE插件是给编辑器加功能，比如语法高亮、代码补全，它运行在编辑器进程里。而skills是给AI模型看的一段上下文，它不改变工具本身的功能，改变的是模型“做事的套路”。你可以把skills理解为给模型塞了一份工作手册，而不是给它换了一把螺丝刀。这个区别决定了skills的安装方式和使用习惯都跟插件完全不同，后面我会详细说。

另外还要提一点，很多人问“skills是不是就是Agent提示词”。我的理解是：提示词是一次性的，而skills是可复用的、有版本的、结构化描述的提示词集合。skills通常包含元数据（名称、描述、适用场景）、指令正文、示例、参考文件路径等，甚至还能引用外部脚本。这种设计让skills可以像软件包一样分发和迭代，这是普通提示词做不到的。

如果你现在用的是Claude Code、Codex这类命令行AI编程工具，那么你大概率已经在和skills打交道了。只是你还没意识到，很多工具默认就带了一些内置skills，比如代码审查、测试生成等等。真正好玩的是自己往里面添加社区skills。下面先聊最基础也最容易被卡住的环节——手动安装GitHub上的skills。

2. 手动安装GitHub上的skills：从clone到生效的完整路径

网上很多教程会直接甩给你一行命令，比如claude skill add之类。但实际用起来，不同版本的工具、不同操作系统的路径差异，能把人折腾到怀疑人生。我踩了一圈坑之后，总结出一条比较稳的手动安装路径，分享给你参考。

2.1 先确认你的工具版本与skills目录位置

不同AI编程工具读取skills的目录不一样。以Claude Code为例，在较新的版本里，skills默认放在项目的.claude/skills目录下，同时用户级目录通常是~/.claude/skills。Codex这边则有所不同，它更倾向于使用.codex/skills或者在项目配置里声明。实操之前，先搞清楚你手上这个版本会去读哪个目录，否则你把skills放进去了它也不认。

判断方法很简单——在项目终端里运行工具的命令行，随便问一句“你现在支持skills吗”，看它的回答里有没有提到具体路径。或者直接找工具的文档页面，搜一下“skills location”关键词。我个人习惯是用find命令扫一遍：

find ~ -type d -name "skills" 2>/dev/null

这样能快速列出本机所有可能被读取的skills目录，再结合工具版本判断哪个是真正生效的。这里有个小经验：用户级目录优先于项目级目录，但也有反过来的情况，最好两个都放一份，后面我会讲为什么。

2.2 手动安装的两种思路：目录拷贝与符号链接

明确了目录之后，安装就很简单了。从GitHub上把项目clone下来，找到它包含的skills文件夹（通常是项目根目录下的skills/），然后把里面的子目录复制到你的skills目录里。

以安装一个叫“web-audit”的skills为例：

# 先clone到临时目录 git clone https://github.com/example/web-audit-skills.git /tmp/web-audit # 查看项目结构，确认skills本体 ls /tmp/web-audit # 通常会有 SKILL.md 或 skills/web-audit/SKILL.md # 复制到Claude Code的用户级skills目录 mkdir -p ~/.claude/skills cp -r /tmp/web-audit/skills/web-audit ~/.claude/skills/

复制完之后，在工具里开启一个新的会话，问一句“你会使用web-audit技能吗”，如果它明确说会，并且能在对话里提到技能的具体步骤，就说明安装成功了。

除了直接复制，还有一个更省事且便于维护的方式：符号链接。也就是把仓库里的skills目录软链到你的skills目录下，这样以后Git pull一下仓库，skills自动更新，不用反复复制。

# 先创建链接，注意你的仓库路径 ln -s /path/to/repo/skills/web-audit ~/.claude/skills/web-audit

这个方式的好处是source目录永远保持原样，你可以在仓库里直接改skills文件，同时也能让多个项目共享同一个skills实例。不过要注意，有些版本的Windows和macOS对符号链接的支持有差异，macOS默认没问题，Windows需要开启开发者模式或者管理员权限。我自己的组合是：仓库放在固定的工作区，用软链挂到用户级目录，一旦上游更新了，一条git pull就搞定了。

2.3 安装后如何验证是否生效（以及常见失败原因）

装完不等于能跑。很多时候你装了skills，但工具压根没读取到。我自己排查下来，最常见的失败原因有三个：

这里要强调一个关键点：模型是根据“当前任务”和“skill的描述”做匹配的，不是把所有skills一股脑读进上下文。如果你的skill描述过于模糊，比如写“用于网页开发”，那模型在遇到“帮我写个导航栏”时可能不会选择它。正确的描述应该是“当用户要求生成完整的响应式企业官网时使用”。描述越具体，触发越准确。

另外，验证生效最简单的方法就是故意触发它。比如我装了一个“数学建模论文排版”skills之后，我问Claude Code“帮我写一份数模论文的LaTeX骨架”，如果它真的按那套结构输出，还不忘自动插入表格和公式环境，那就说明生效了。如果它只是泛泛地写，那就是没读到或者匹配逻辑没触发。

手动安装这部分基本就是这些坑。接下来聊聊更关键的问题：社区里的skills库参差不齐，哪些值得装？哪些是智商税？

3. 值得收藏的skills源与推荐清单（含superpower skills这类全家桶）

在GitHub上一搜“skills”，能搜出成百上千个仓库。有些确实是精华，有些只是把几段prompt打包一下就叫skills。我按实际使用体验，整理了几类比较靠谱的获取渠道和具体推荐。

3.1 官方与社区skills仓库的挑选逻辑

首先认准官方仓库。Anthropic官方维护了一个anthropics/skills仓库，里面都是经过验证的基础skills，比如docx处理、pdf处理、canva设计输出等。这类skills的特点是不花哨，但非常稳。我建议新手先从官方仓库的skills开始装，熟悉一下格式和触发方式，再去社区找。

社区方面，最出名的是obra/superpowers，作者是Jesse Vincent，这个项目被称为“superpowers skills全家桶”。它包含了一套相互协作的skills，核心思想是通过“子agent”机制拆解复杂任务，让Claude Code具备更强的规划和执行能力。比如它的writing/planner技能，能让你在开始写文章之前先自动生成一份大纲并和你确认，然后按计划逐步输出。这个对于需要写长文档、做技术方案的人来说非常实用。

还有一个值得关注的仓库叫typesafe-ai/skills，主打类型安全和可测试的AI应用开发。里面有不少关于TypeScript、API设计、软件架构方面的skills。如果你在写AI相关的后端服务，这个仓库能给你很多模式参考。

挑选逻辑其实很简单：看更新频率和issue回复。一个skills仓库如果半年没动静，大概率没人维护了，装上去可能和新版本工具不兼容。另外要看SKILL.md的描述是否清晰，有没有给出具体的触发条件和使用示例。描述含糊的skills，在实际使用中十有八九不触发。

3.2 前端开发、数学建模、AI漫剧等场景的skills推荐

根据这些日子的热搜词，我发现大家在不同场景下对skills的需求差异还挺大的。先说说前端开发。前端开发skills是目前社区里最卷的领域之一，好的skills不仅能帮你写出页面，还会强制规定样式结构、组件拆分、可访问性规范。我常用的是一个叫“webapp-architect”的skills，它会根据项目规模自动决定用React还是Vue，还会生成完整的目录建议。这里建议不要装太多前端skills，装两三个重合度高的容易让模型指令冲突，反而不知道听谁的。

数学建模场景，尤其是华为杯建模比赛，很多人在找好用的Codex skills。这类skills的核心不是生成公式，而是帮你完成建模流程管理：题目理解、假设列举、模型选择、敏感性分析、论文结构。我看到社区里有一个叫“math-modeling-team”的skills，它会把建模比赛分为多个阶段，每个阶段输出特定文档，最后自动汇总成论文初稿。配合Codex使用，在时间紧任务重的比赛场景下非常管用。还有一个叫“latex-formatter”的skills，专门做数模论文里的公式排版和表格插入，省去了很多手工调LaTeX的麻烦。

AI漫剧这个领域挺新的，是指用AI生成漫画、短剧分镜之类的创作场景。这类skills通常会结合图像生成模型，比如通过Claude Code调用Midjourney或Stable Diffusion的API来生成分镜图。我在GitHub上见过一个“comic-pipeline”的skills，功能是把剧本拆成分镜脚本，然后为每个分镜生成图像提示词，最后统一导出成漫画排版。虽然不是特别成熟，但思路很值得参考。

3.3 小心“伪skills”：如何判断一个skills是否值得装

在推荐了一大堆之后，必须提醒一句：现在GitHub上很多项目打着“skills”旗号，实质就是往SKILL.md里塞了几百行惯用句。这类skills不能说完全没用，但往往缺少可执行的步骤，也没有定义输入输出格式，模型读了之后只会更迷茫。

怎么鉴别呢？我的经验是打开它的SKILL.md，看三点：

1. 有没有定义触发场景：好的skills会在description里写明“当用户要求X时使用本技能”，而不是泛泛的“用于提高效率”。
2. 有没有具体的步骤编号：好的skills会给出1、2、3、4这样的执行流程，甚至包含分支条件；伪skills往往是一大段描述文字，没有可拆分的步骤。
3. 有没有自我验证机制：高级的skills会包含“完成后检查清单”或“常见错误与处理”，比如“如果步骤2失败，检查网络连接”。这个设计非常实用，能让模型在出错时自我纠偏。

另外，如果看到仓库里有多个SKILL.md文件互相引用，说明作者考虑到了组合使用，大概率是花了心思的；如果只有一个孤零零的md文件，先别急着装，多看看issue区和讨论区，或者直接自己读一遍内容再决定。

4. 自己动手写一个skills：结构、写法与调试流程

装别人的skills永远只是第一步，真正好玩的是自己写skills。我发现一旦你开始写，就会反过来更深刻地理解那些开源skills的设计逻辑。下面用一个实际例子，从零写一个简单的“网页性能检查”skill。

4.1 SKILL.md的核心字段与YAML frontmatter

一个skills本质上就是一个目录，目录里面至少有一个SKILL.md文件。这个文件的结构分为两部分：YAML frontmatter和正文。

YAML frontmatter是开头被---包裹的metadata区，关键字段如下：

--- name: web_perf_audit description: 当用户需要对网页进行性能分析、加载速度优化、资源体积检查时使用。 ---

name字段通常是目录名，必须保持简短且唯一。description字段是模型决定是否触发该skill的依据，这是最关键的字段，你宁可写长一点、具体一点，也别图省事。比如“当用户提到网页慢、首屏加载慢、Lighthouse分数低、需要优化图片体积或JS/CSS时使用”就比“用于网页优化”好得多。

正文部分是markdown格式的指令。推荐的结构是：先写“目标”，再写“执行步骤”，然后写“输出格式”，最后写“质量检查清单”。比如：

# 网页性能检查 目标：系统性地分析一个网页的加载性能，找出瓶颈并给出改进建议。 步骤： 1. 确认目标URL，询问用户是否需要对指定页面进行测试。 2. 检查HTML结构，识别阻塞渲染的资源，包括内联脚本和样式表。 3. 分析图片、字体等静态资源体积，统计超过500KB的文件。 4. 根据问题生成优化建议，按优先级排列，标注预期提升效果。 输出格式： 以Markdown表格输出，包含“问题|位置|严重程度|优化建议|预期收益”五列。 检查清单： - 是否包含具体资源文件路径？ - 是否给出了可执行的修改方案？ - 是否区分了阻塞项和非阻塞项？

上面这个例子虽然简单，但已经涵盖了最基本的要素。更复杂的skills还可以在目录里放参考文件、脚本、模板等。比如你可以放一个checklist.md供模型读取，或者在目录里放一个Python脚本，告诉模型“运行这个脚本获取页面指标”。只要在SKILL.md里写明引用方式就行。

4.2 写一个“网页性能检查”skills的完整示例

你会发现，光有上面的SKILL.md还不够。如果不告诉模型怎么去获取性能数据，它会凭经验胡编数字。所以更完整的方式是让skill内置一个简单的采集脚本。我们可以在skills目录下放一个Python脚本run_audit.py，然后改造SKILL.md的步骤，明确指示模型先运行脚本，再基于脚本输出分析。

#!/usr/bin/env python3 import subprocess import sys url = sys.argv[1] if len(sys.argv) > 1 else "http://localhost:8080" result = subprocess.run( ["npx", "lighthouse", url, "--quiet", "--output=json"], capture_output=True, text=True, check=False, ) if result.returncode != 0: print("Lighthouse跑失败，尝试直接用requests模块检查基础状态。") # 这里可以降级到简单的HTTP检查 else: print(result.stdout[:3000])

然后在SKILL.md中写：

步骤1：运行命令 python run_audit.py <目标URL>，读取输出结果。 步骤2：如果输出包含Lighthouse JSON，解析其中的performance、accessibility、best-practices分数。 步骤3：如果评分低于90，查看对应的diagnosis信息，将具体问题汇总到优化建议表。

这个例子的威力在于：模型不再需要“凭空想象”性能指标，而是真的可以调用工具获取数据，再基于数据做分析。这才是skills和普通提示词拉开差距的地方。当然，这要求你的工作环境有Python和Node环境，如果跑不了Lighthouse，也可以让skill先用curl获取页面耗时。

4.3 调试方法：如何让模型真正遵循你的skills

写完新skills，调试是少不了的。我总结了一个三步调试法：

第一步：单独触发。开一个新的对话，明确输入“使用web_perf_audit技能检查example.com”。注意这里要说得直白，方便判断技能有没有被加载。如果它回复了，说明目录结构和frontmatter基本没问题。

第二步：隐式触发。换一种更自然的说法，比如“这个网站加载太慢了，帮我看看问题在哪”。如果模型能自动联想到刚写的skill，说明description写得足够好。如果它没有触发，多半是description里缺少相关关键词。

第三步：让模型输出调试信息。你可以在SKILL.md里加一句“如果无法获取性能数据，请明确说明你缺少哪些权限或依赖”。这样一旦模型在实际执行中卡住，它会直接告诉你原因，而不是自作聪明地用一些编造的数据糊弄你。

调试过程中我踩过最大的一个坑是：模型在读取SKILL.md时只读了前面的几行，忽略了后面的步骤。后来我意识到，这与模型上下文长度和注意力机制有关。解决办法是把关键指令尽量前置，把可选的细节放后面。比如在正文开头先写“必须遵循以下步骤：”，然后把步骤1、2、3紧跟着写；不要用太多嵌套列表，模型更容易迷失。

还有一个实用技巧：在SKILL.md里刻意留一些“检查点”，比如“在完成步骤2之后，简短向用户说明当前发现”。这会让模型在执行过程中与用户产生交互，而不是闷头把所有步骤跑完才汇报——很多任务其实需要中途确认，否则容易跑偏方向。

5. 实战中的常见坑与我的解决习惯（含tibo式的清理思路）

最后这部分，我说说自己这段时间高强度使用skills之后踩过的坑，以及慢慢摸索出来的管理习惯。这部分内容网上教程很少写，属于纯经验向。

5.1 版本冲突与技能覆盖问题

skills越来越多之后，最典型的问题就是“两个skills打架”。比如我装了一个“React代码生成”的skill，又装了一个“前端最佳实践”的skill，两者对组件拆分粒度的要求可能完全不同。模型有时候会同时读到两个skill的描述，然后选择一个它能匹配的，但执行过程中又隐约受另一个影响，最终产出的代码风格就很奇怪。

我的解决习惯是：尽量不装功能重叠的skills。装之前先看一眼SKILL.md里的description和steps，如果发现和已有的skill有70%以上重叠，就只留一个更具体的。另外对于同一领域的多个skills，最好通过调整description的关键词来区分触发场景。比如一个负责“初始化项目结构”，另一个负责“性能优化”，这样模型就能在正确的场景选择正确的工具。

还有一种情况是同一skill的多个版本冲突。我用的是软链方式管理skills仓库，如果git pull之后仓库里的skill结构变了，旧目录还残留着，就可能出现两个同名的skill目录。模型读取时会根据目录名和文件名去识别，同名会互相干扰。建议定期检查~/.claude/skills，删除那些不在用的旧目录。

5.2 工具链的prompt缓存导致skills不生效

这个问题非常隐蔽。有一次我新装了一个skill，测试时发现模型完全没反应。我反复检查目录和语法都没问题，最后重启了工具，才突然生效。后来才意识到是会话上下文缓存的问题。很多AI编程工具为了省token，会在当前会话里缓存一份“可用skills列表”，这个列表在会话启动时就生成了，如果你在会话中途新装了skill，它可能直到下一次会话才会被加载。

解决方法是：安装skill之后，务必开一个新会话再测试。如果你正在一个比较长的会话里，也可以试试发送一条特殊的重载命令，有些工具比如Claude Code支持/skills之类的斜杠命令来刷新列表。实在不行就重启工具。这个坑不算深，但容易在调试时白费半天时间。

另外，如果工具版本很老，可能根本不支持用户级skills目录，只认项目级。一旦发现怎么装都没反应，先升级工具版本。我之前就在Codex的一个旧版本上卡了两天，升级后问题直接消失。

5.3 我常用的skills管理习惯与清理策略

关于如何管理满屏的skills，我摸索出一套自己的清理哲学，灵感来自某个叫tibo的博主分享的清理方法。核心思路是：skills跟厨房用具一样，少而精，频繁使用者优先。

我不再追求“把所有热门skills都装一遍”，而是每两到三周做一次大扫除。步骤如下：

• 用命令列出所有已安装skills及大小（ls -lt ~/.claude/skills）。
• 逐个回忆：过去两周有没有触发过？触发后的产出是否明显优于不装的时候？
• 凡是超过一个月没被动用过的，直接删除。删不掉的就停用——有些工具支持在配置里禁用某个skill。
• 对于多个仓库同时提供的skill，统一收敛到一个来源，避免混着用。

清理之后，模型的上下文压力会小很多，触发准确率也会提升。不要以为装了几十个skills就是“能力更强”，实际上每个潜在可用的skills都可能占用模型的一部分上下文预算，装多了反而稀释重点。

还有一点经验，尽量给skills目录划分明确的来源区域。比如官方、社区A、社区B分别放在不同前缀的目录下，这样万一出了问题，你能快速定位是哪个来源导致的。我自己习惯在目录名前加来源缩写，比如obs-web-audit、ant-docx这种，时间长了真能救命。

最后再分享一个细节：我发现好的skills作者都会花大量时间打磨description。会写skills的人，通常会在description里列出至少五种可能触发的用户说法，包括用户自己都没意识到的变体，比如“帮我看看这个页面怎么这么慢”也会命中性能检查技能。你要是有精力，可以专门建一个“skills触发测试集”，每写或者装一个新skill，就把自然语言描述跑一遍，看看匹配率有多高。我自己跑了之后，发现不少社区热门skill的触发率其实只有四五成，这也是很多用户觉得“装了没效果”的根本原因——不是skill写得不行，而是描述写得带不动触发。

目前我折腾skills的时间加起来已经有几个月，最大的体会是：这项技术正在快速改变我们和AI协作的方式。以前写提示词像是在“给模型递小纸条”，现在写skills像是在“给模型编工作手册”。当你自己也写出一版能被反复复用的skills时，那种“把经验沉淀下来”的感觉，真的会上瘾。