AI编码Skills从安装到编写：Claude Code、Codex技能使用指南

1. 先聊清楚：AI 编码技能（skills）到底是什么

最近一年只要你在折腾 Claude Code、Codex、OpenCode 这类工具，一定躲不开一个词——skills。我最早接触这个概念是在一次团队内部代码评审上，同事把一整包"评审规范"装进了 Claude Code，之后每次拉代码评审它都会自动按公司编码规范来查，不用我再重复贴一大段提示词。那个感受很直接：原来 AI 编码助手不只会聊天，还能像装插件一样给它装"技能"。

技能的本质，说白了就是把一组结构化的指令、示例、参考文档甚至是脚本，打包成一个可以被 AI 编码工具按需加载的独立单元。传统玩法里，你想让 AI 按特定方式干活，要么把长篇提示词粘贴到对话窗口，要么写死在系统提示里。但这两个方案都很别扭：提示词会越攒越长，系统提示一改就全局生效，很容易把项目的其他任务带偏。技能的做法是提供一个小的"资料包"，AI 在对话中判断当前任务匹配这个技能时，才去读取对应的指令文件，用完即走，不影响其他会话。

Claude Code 是 Anthropic 官方支持技能生态最早也最成熟的一个，它的目录约定是这样的：

# 用户级技能，所有项目都能用 ~/.claude/skills/<skill-name>/SKILL.md # 项目级技能，只对当前仓库生效 <your-project>/.claude/skills/<skill-name>/SKILL.md

每项技能是一个独立目录，里面必须有一个 SKILL.md 文件作为入口，之外还可以放脚本、模板、参考资料等其他配套文件。SKILL.md 的前几行是 YAML 格式的元信息，声明技能的名称和适用场景，后面才是真正的指令正文。

Codex 是 OpenAI 对外推出的编码 CLI，它同样有 skills 机制，目录约定与 Claude Code 高度类似：

~/.codex/skills/<skill-name>/SKILL.md # 或者项目级 <your-project>/.codex/skills/<skill-name>/SKILL.md

OpenCode 也有自己的 skills 约定，一般放在~/.config/opencode/skills/或项目.opencode/skills/下。结构不同但设计思路几乎一致，都是"以 SKILL.md 为入口，按名触发，描述驱动加载"。

1.1 Claude Code、Codex、OpenCode 的 skills 目录约定对比

别看这三个工具的 skills 长得像，具体细节还是有差异的，装错了目录等于白装。我整理过一个对照表，方便你按工具对号入座：

注意几个容易踩坑的细节：Claude Code 在比较早的版本里曾经支持过.claude/commands/这种斜杠命令目录，很多人会把两者搞混。技能是"按需自动加载"的，斜杠命令则更多是"显式调用"。我建议把技能当作百科全书，把斜杠命令当作快捷按键，两者定位不同。Codex 那边则要留意版本号，早期版本的 Codex CLI 对技能的自动发现逻辑还在迭代，有时候你明明装了技能，它却不去读，多半是版本太旧或者 YAML 元信息写得不到位。

1.2 技能、提示词、命令、插件到底差在哪

很多刚接触 skills 的朋友会问：这跟提示词有什么区别？跟插件又有什么区别？

我打个比方。提示词是你跟 AI 说"你是个专家，请你按照以下几点来做事"，技能则是给 AI 一本小册子，里面写好了专家的行为准则、常用模板、边界红线，AI 判断该用时自己翻开看。区别在于"要不要你手动重复"——提示词每次都要写或者粘贴，技能装一次就能反复用。

命令（slash command）是技能的一种特殊形态，类似手动触发开关。普通技能靠 AI 自动判断触发，命令靠你主动唤起。插件往往带着代码层面的集成能力，比如注册新的工具调用、修改运行时行为；而技能偏向指令层面，一般不需要写代码逻辑，如果你真要在技能里执行脚本，Syntax 也允许放可执行文件，但它本质还是"指引 AI 去跑脚本"，不是改变 AI 引擎本身。

2. 手动安装 GitHub 上的 skills：以 Claude Code 为基准的完整拆解

GitHub 上技能的仓库多得吓人，但安装方式大同小异。我个人最常用、也最推荐新手先跑通的一条路，是手动 clone 后复制目录。下面我以 Claude Code 为例，把完整流程拆开讲一遍，你顺手还能学会怎么验证安装成功。

2.1 从 clone 到目录落位的标准步骤

第一步，想清楚技能要装给谁用。只给当前项目用，就放到项目的.claude/skills/目录；所有项目都能用，就放到用户级~/.claude/skills/目录。我建议新手一律先放用户级，因为不用为每个项目重复装，后面想隔离再改路径。

第二步，把目标仓库 clone 到本地：

git clone https://github.com/xxx/skills-repo.git cd skills-repo ls -la

进去先看目录结构。正规的技能仓库一般长这样：

skills-repo/ ├── README.md ├── review-code/ │ └── SKILL.md ├── generate-commit/ │ ├── SKILL.md │ └── templates/ │ └── conventional-commit.md └── docs/

第三步，复制技能目录：

mkdir -p ~/.claude/skills cp -r review-code ~/.claude/skills/

复制完检查一下：

ls -la ~/.claude/skills/review-code/ cat ~/.claude/skills/review-code/SKILL.md

能看到 SKILL.md 文件且内容完整，就算装好了。这时重新打开 Claude Code，直接在对话里描述你的需求，如果它判断能用上这个技能，会自动读取相关指令。

2.2 superpower skills、typesafe ai-skills 这类聚合包的安装差异

GitHub 上除了单个技能散装仓库，还有一批"聚合技能包"。最常见的就是搜词里反复出现的 superpower skills，还有 typesafe ai-skills 这种针对 TypeScript 生态做的技能合集。

聚合包跟散装技能最大的区别是：它往往不是单个 SKILL.md，而是一整套有着内在依赖关系的技能网络。比如 superpower skills 就包含 brainstorm、planning、TDD 等一整套相互配合的技能，它们的设计是在不同阶段逐步介入，不是一个技能独立完成任务。这种包手动一个个复制目录也能用，但如果作者提供了安装脚本，我强烈建议用脚本装。

superpower skills 仓库里通常有一个 install.sh 或者官方文档提供的 npx 安装命令：

git clone https://github.com/obra/superpowers.git cd superpowers ./install.sh

脚本做的事本质上还是把技能目录们复制到位，但它会额外处理依赖关系和配置项。typesafe ai-skills 则更偏 TypeScript 项目场景，里面有大量针对类型检查、测试生成、依赖治理的技能。安装方式同样是 clone 后按需复制，但要注意它可能依赖某些 Node.js 版本特性，装完最好跑一次冒烟测试。

2.3 装完怎么确认技能真的生效了

装完不等于生效，这是我踩过最深的坑。Claude Code 对技能的加载是"提示词描述匹配"驱动的，技能文件的元信息如果没有写清楚适用场景，AI 根本不会触发它。

验证方法分三步：

第一步，确认文件路径正确且权限没问题：

ls -la ~/.claude/skills/ stat ~/.claude/skills/<skill-name>/SKILL.md

第二步，检查 frontmatter。看 YAML 头里的name和description是否规范，有些作者会把 description 写成一个长句子，AI 反而抓不住重点。我看到写得好的 description 一般是这样的：

--- name: review-code description: 当用户需要做代码评审、检查代码质量问题、确认提交规范时使用。 ---

第三步，用一个小任务触发测试。比如装了 review-code 技能，你就随便打开一个有明显代码风格问题的文件，让 Claude Code 做评审。如果它回话里出现了技能里特有的术语或原则，说明技能生效了。如果没有任何反应，多半是 description 写得太窄，或当前版本的变通模型还不会主动读技能，去把描述扩宽一点再试。

3. 按场景挑技能：不同项目该装什么样的 skills 组合

装技能不是越多越好，而是要对症下药。我看到不少朋友把整个技能仓库全复制一遍，结果 Claude Code 每次都要在几百个技能文件里翻找，反而变迟钝。下面列几个典型场景的技能组合思路，都是我已经在真实项目里验证过的。

3.1 前端开发：代码评审、组件生成、样式对齐的技能搭配

前端项目里我最推荐配的技能，第一是代码评审类，第二是组件生成类。代码评审技能的价值在于把你团队的编码规范固化下来：组件文件命名规则、样式方案用 Tailwind 还是 CSS Module、接口调用统一走什么封装层，这些都能写进技能里。之后 AI 帮你做评审时就不会再给一堆泛泛的建议，而是按你们团队的真实约束来挑毛病。

组件生成技能也实用。它的 SKILL.md 里通常定义了组件文件的骨架，比如每个组件必须有 props 类型定义、样式文件、单元测试文件，AI 生成新组件时会自动按这个骨架补齐文件，而不是只给你一个孤零零的 .tsx。我自己还会搭配一个提交信息生成技能，用来统一 git commit 的格式，这个对维护开源项目尤其舒服。

前端技能的安装思路是"越小越精越好"。我建议为项目单独建.claude/skills/目录，只放跟当前技术栈相关的技能，不要把所有前端技能全塞到用户级目录里。

3.2 数学建模与竞赛场景：华为杯、国赛的 Codex skills 配置思路

在数学建模这个方向，技能可以发挥的作用经常被低估。搜词里反复出现"华为杯建模比赛好用的 codex skills"，其实背后的需求很明确：建模比赛时间紧，队伍需要在很短时间内完成数据处理、模型选型、论文排版等一系列固定套路的工作，而技能刚好能把套路固化下来。

以 Codex 为例，我建议给建模比赛配置这样一组技能：

第一，数据清洗技能。专门处理 CSV 里的缺失值、异常值、格式不一致的问题，SKILL.md 里给出固定的处理流程和边界判断标准。第二，模型选型技能。把问题分类和推荐模型对应关系写进去，比如回归问题优先试线性回归、树模型、再到集成模型，分类问题优先试逻辑回归、随机森林、XGBoost。第三，论文排版技能。针对比赛模板，定义图表编号、公式引用、参考文献格式这些规则。

配置方法很简单，在比赛项目的.codex/skills/下建对应目录，把规则写进去。重点提醒一句：建模比赛的技能描述里一定要强调"当前是比赛场景"，这样 Codex 在判断时更精准，不会被通用编程问题干扰。

3.3 AI 漫剧与多媒体内容生产方向：常用技能长什么样

AI 漫剧是现在视频号、抖音上非常火的一条赛道。做这类内容的人很多不是专业程序员，但他们同样会用 Claude Code、Codex 这类工具来帮助生成脚本、分镜、字幕文件、甚至是剪辑软件的标记语言。技能在这里扮演的角色是把"一套制作流程"压缩成一个可复用的指令包。

比如我可以定义一个"分镜生成技能"，它的 SKILL.md 里包含视频脚本的结构要求：开场钩子、剧情推进、冲突点、结尾反转，每一部分需要输出多少个画面提示词，画面提示词的风格标签怎么统一。还可以定义一个"字幕对齐技能"，用于把生成的对话文本自动按时间轴拆成字幕格式。AI 漫剧创作者最舒服的地方在于：只要描述清楚了内容风格和节奏要求，剩下的标准化工作技能都可以代劳。

这类技能的内容以模板和检查清单为主，不太需要脚本文件，所以写起来门槛很低，有耐心就能做出效果。

3.4 常用 skills 源网站与检索方法

技能库有固定的渠道可以参考。GitHub 上直接搜 "skills" 就能找到一批高星仓库，但更要学会筛选。我比较常用的几个入口：

• anthropics 官方发布的技能仓库，质量最稳，适合当范本学习。
• superpowers 仓库，社区里讨论度极高，适合做完整工作流的人。
• typesafe 的 skills 仓库，TypeScript 场景优先，前端工程化必看。
• 各类 "awesome skills" 汇总列表，聚合了大量按场景分类的技能链接。

找技能时不要只看星数，要学会看 README 和维护活跃度。很多仓库只是把技能堆在一起，完全没测试过，clone 下来装完发现 SKILL.md 里还有乱码，纯浪费时间。我个人的习惯是先看最近一次提交日期，如果超过三个月没更新，基本就不考虑了。

4. 自己写 AI skills：从 SKILL.md 到带脚本的复合技能

会装技能只能算入门，真正有价值的是自己写技能。因为公开仓库里的技能解决的是通用问题，而自己的项目往往有一堆"只有团队内部才知道的规则"，这些规则写进技能里，才能让 AI 真正变成了解你们团队的人。

4.1 SKILL.md 的编写规范：frontmatter 与正文的黄金比例

一个规范的 SKILL.md 由两部分组成：YAML frontmatter 和 Markdown 正文。frontmatter 是技能的门面，决定了 AI 什么时候会想起这个技能，所以要写得克制精准，描述里要包含触发场景、任务类型、关键要素，但不要写成论文。

我常用的 frontmatter 模板：

--- name: generate-api-client description: 当需要根据 OpenAPI 文档生成 TypeScript API 客户端代码时使用，包括类型定义、请求函数、错误处理封装。 ---

正文部分我习惯分四块来写：目标与边界、执行步骤、规范与禁忌、验收标准。目标与边界先写清楚这个技能做什么、不做什么，避免 AI 越权发挥；执行步骤按顺序列，AI 会按顺序走；规范与禁忌写出项目特有的约束；验收标准让 AI 完成后自查。四块结构写下来，技能的质量基本就有保障了。

4.2 脚本、参考文档、模板什么时候该拆出来

SKILL.md 不是越厚越好。当你的技能正文超过两千字时，就该考虑把一些内容拆成独立文件了。判断标准很简单：什么内容会被反复引用，就拆出去。

常见的拆法是把参考文档放到references/目录，把可执行脚本放到scripts/目录，把模板放到templates/目录。比如写一个数据库迁移技能，SKILL.md 只写流程，具体的 SQL 规范放到references/下，常用的建表语句模板放到templates/下，后期改动只动对应文件即可，不用去碰主指令。

这里有个技巧：SKILL.md 里通过相对路径引用这些子文件，AI 读入主文件后会自动去读引用的文件。路径一定要写清楚，最好用绝对路径式描述，否则 AI 可能找不到文件。

4.3 写技能时最容易被忽视的边界问题

写技能的坑比装技能更多。第一个坑是"描述与正文不符"。有些人把触发描述写得很宽，正文里却只解决一个具体场景，结果 AI 每次都误触发，浪费 token。解决办法是描述里加否定条件，比如"仅适用于后端服务项目，不适用于前端构建流程"。

第二个坑是"过度约束"。技能正文里把所有细节都定死，AI 反而没有发挥空间。我的建议是核心规范必须写死，但实现方式留白，让 AI 自己选合适的技术方案。第三个坑是不给验收标准。AI 做完了不知道自己做得对不对，你就得反复返工。加一个"输出需通过 xxx 检查"的验收段落，能让整个流程闭环。

5. 技能变多以后的治理：冲突排查、清理与维护

技能装到二三十个以后，你会发现一个新问题：AI 变得更爱"自作主张"了。它经常在你没让它用某个技能时强行触发，或者多个技能在同一个任务上抢活，最后输出的内容驴头不对马嘴。这时候就该进入治理阶段了。

5.1 多个技能抢同一类任务：怎么定位到底是谁在"作祟"

技能冲突最常见的表现是：你让 AI 生成一段前端代码，它同时加载了组件生成技能和代码风格技能，然后又因为某个技能描述里有"前端"两个字，把数据清洗技能也拉进来了。结果指令互相打架，输出风格混乱。

定位冲突的办法是开启详细日志，看 AI 到底读了哪些技能文件。Claude Code 的 debug 参数可以打出读取了哪些文件；如果没开日志，就只能用排除法：把可疑技能暂时移出 skills 目录，再触发一次任务，看行为是否恢复正常。

我实际跑下来的经验是，绝大多数冲突来源于技能的 description 写得太宽。遇到这种技能，优先改描述，而不是删掉整个技能。

5.2 tibo 风格的清理方法：给技能做定期体检

社区里流传过一套 tibo 推荐的技能清理方法，核心思路是"定期给技能做体检"，而不是等出问题再处理。我照着这个方法实践过几次，整理成了一套适合普通人的流程：

第一步，列出现有技能清单，在每条技能后面标注"最近一次被触发是什么时候、触发后有没有达到预期效果"。第二步，把超过一个月没被触发并且也想不到何时会用到的技能归档到~/.claude/skills-archive/目录，而不是直接删除，这样随时可以恢复。第三步，检查剩余技能的描述文件，看看有没有描述过宽、边界不清的情况。第四步，跑一轮回归测试，用几个标准任务触发核心技能，确认梳理完没有影响正常功能。

这个方法最大的好处是不用做一次痛苦的"大扫除"。每次只整理几条，风险可控。我大概一个季度做一次体检，技能库里始终保持着三四十个真正在用的技能。

5.3 同一台机器上多工具共用技能：一份技能吃遍 Claude Code 和 Codex 的取舍

我身边有不少朋友是 Claude Code 和 Codex 混着用的，就动过"一份技能两边共用"的念头。实际做起来可行，但要有取舍。

最简单的做法是维护一个 master 仓库，里面所有技能都用通用的 SKILL.md 格式编写，然后用脚本分发到各个工具的技能目录。我的分发脚本大概长这样：

#!/bin/bash for dir in my-skills-repo/*/; do name=$(basename "$dir") rsync -a --delete "$dir" "$HOME/.claude/skills/$name/" rsync -a --delete "$dir" "$HOME/.codex/skills/$name/" done

但这套方案有个前提：技能内容不能依赖某个工具特有的能力。比如 Claude Code 里可能用到它的工具调用来执行扩展任务，Codex 里未必支持。如果技能正文中出现大量工具特定语法，就别强行共用，给两个工具各维护一份更保险。

6. 从我自己的使用经历聊几句

从第一次接触 skills 到现在，我最深的体会其实是：技能的价值不在于它包含多少花哨的指令，而在于它能把人脑里的经验结构化。我团队里最有用的一个技能是我把过去半年踩过的前端构建坑全部写进去后生成的构建排错技能，每次遇到 webpack 或 vite 的问题它都能直接给出针对性排查路径，比我翻聊天记录效率高太多。

如果你正准备入门，我的建议是别一次装太多，先挑项目里最痛的一个场景，写一个极简技能跑通闭环，再去研究别人的高级玩法。如果已经装了不少，就按第五部分的思路好好做一次体检。技能越干净，AI 越聪明，这道理放哪个工具上都一样。