1. 从“skills”这个热词说起它到底在解决什么问题最近半年不管是在技术社区还是各种开发者群组里“skills”这个词出现的频率高得离谱。你随便翻一下热搜词列表就能看到claude code skills、codex skills、agent skills测试、skills开发、skills推荐、前端开发skills、superpower skills……这些词背后其实指向同一个东西——给AI编程助手装上一套可复用的“技能包”。我最早接触这个概念是在折腾Claude Code的时候。当时我的第一反应是这不就是prompt模板吗但用了一段时间之后我发现它比prompt模板要深得多。Skills本质上是一组结构化的指令、工具调用逻辑和上下文约束的集合它让AI agent在特定场景下能够按照预设的流程去执行任务而不是每次都靠用户临时写一大段提示词来“求”它做对。打个比方如果没有skillsAI编程助手就像一个刚入职的聪明实习生——能力很强但你不告诉他公司的代码规范、部署流程、测试要求他就按自己的理解乱来。而skills就是那本《员工手册》加上一套标准作业程序SOP你把它交给实习生他就能按照你们团队的规矩干活了。这篇文章我打算从实际使用的角度把skills这个东西拆开来讲清楚。包括它跟Claude Code、Codex这些工具怎么配合怎么自己开发一个skills安装配置过程中会遇到哪些坑以及我在实际项目中总结出来的一些经验。不管你是刚听说这个概念的新手还是已经在用但总觉得哪里不对劲的老手应该都能从里面找到有用的东西。注意本文讨论的所有工具和平台均为通用开发工具内容聚焦于技术实现和工程实践。2. Skills的核心机制与设计逻辑拆解2.1 Skills和普通Prompt的本质区别在哪里很多人第一次接触skills会把它等同于“写一个好的提示词”。这个理解不能说错但太浅了。我举个具体的例子来说明区别。假设你要让AI帮你写一个React组件。普通prompt的做法是请帮我写一个React组件要求 1. 使用TypeScript 2. 使用函数式组件 3. 样式用CSS Modules 4. 需要包含单元测试 5. 遵循项目的ESLint规范而skills的做法是你创建一个叫做react-component-generator的skill里面定义了触发条件当用户提到“创建组件”“新建组件”等关键词时激活执行流程先读取项目的tsconfig.json确认TS配置再读取.eslintrc确认代码规范然后按照模板生成组件文件、样式文件、测试文件约束规则组件必须使用React.FC类型标注样式文件必须与组件同名测试覆盖率要求等输出格式生成的文件列表和每个文件的完整内容看出区别了吗普通prompt是“一次性”的你每次都要重新写skills是“持久化”的写一次之后每次都能用而且它能够主动去读取项目上下文根据实际情况调整输出。更关键的是skills可以被组合和嵌套。你可以有一个“代码审查”的skill一个“生成测试”的skill一个“部署”的skill然后在一个复杂任务中让agent依次调用它们。这种组合能力才是skills真正的威力所在。2.2 Claude Code、Codex和Skills之间的三角关系现在市面上支持skills机制的AI编程工具主要有两个阵营Anthropic的Claude Code和OpenAI的Codex。它们对skills的支持方式不太一样我分别说一下。Claude Code的skills机制相对来说更成熟一些。它通过.claude/目录下的配置文件来定义skills支持YAML格式的元数据描述和Markdown格式的指令内容。你可以在项目根目录创建一个.claude/skills/文件夹里面每个子文件夹就是一个skill。Claude Code在启动时会自动加载这些skills并根据对话内容判断是否需要激活。Codex的skills支持则更偏向于通过codex.json或者项目级的配置文件来定义。Codex的skills系统相对来说更轻量但灵活性也不错。它支持通过--skill参数在命令行指定要加载的skill也支持在配置文件中声明默认加载的skills列表。两者共同的核心理念是让AI agent具备领域特定的知识和流程而不是每次都从零开始理解你的需求。我个人的使用体验是Claude Code的skills更适合复杂的、多步骤的工作流比如完整的feature开发流程Codex的skills更适合快速的一次性任务比如代码格式化、生成文档等。当然这只是我自己的感受具体用哪个还是看你的实际场景。2.3 为什么skills突然变得这么重要这个问题值得单独说一下。我觉得有三个原因第一AI编程助手的普及速度远超预期。现在几乎每个团队都在用Claude Code、Codex或者类似的工具但大部分人只是把它当做一个“更聪明的代码补全”来用。真正发挥出这些工具全部能力的人都在用skills。第二项目复杂度在增加。以前一个项目可能就几种技术栈现在一个前端项目可能同时涉及React、Vue、Svelte后端可能同时有Node.js、Python、Go。每种技术栈都有自己的最佳实践和规范靠人脑记根本不现实。Skills就是把这些规范“外化”到配置文件里。第三团队协作的需要。当团队里有五个人都在用AI编程助手时如果没有统一的skills配置每个人生成的代码风格都不一样。有了skills至少能保证AI生成的代码在基本规范上是一致的。3. 手把手搭建你的第一个Skill3.1 环境准备与工具安装在开始写skill之前你得先把基础环境搭好。这里我以Claude Code为例因为它的skills生态目前最完善。安装Claude Code的步骤不复杂但有几个细节容易踩坑# 如果你已经有Node.js环境建议18以上 npm install -g anthropic-ai/claude-code # 验证安装 claude --version安装完成之后你需要进行初始化配置。在项目根目录运行claude init这个命令会引导你完成基本配置包括API密钥设置、默认模型选择等。如果你是在Windows环境下使用建议在WSL2里面操作原生Windows的支持虽然有了但偶尔会有路径相关的小问题。提示如果你在安装过程中遇到网络相关的报错检查一下npm的registry配置是否正确。国内用户可以考虑切换到国内镜像源来加速下载。Codex的安装稍微不同# 通过npm安装 npm install -g openai/codex # 或者通过HomebrewmacOS brew install codexCodex安装完之后同样需要配置API密钥。你可以通过环境变量设置export OPENAI_API_KEYyour-api-key-here或者把它写到.env文件里Codex会自动读取。3.2 Skill的文件结构与配置详解一个标准的Claude Code skill目录结构是这样的.claude/ skills/ my-first-skill/ skill.yaml # 元数据和触发条件 instructions.md # 具体的指令内容 templates/ # 可选的模板文件 component.tsx scripts/ # 可选的辅助脚本 validate.shskill.yaml是整个skill的核心配置文件它定义了name: react-component-generator description: 自动生成符合项目规范的React组件 version: 1.0.0 author: your-name # 触发条件 triggers: - pattern: 创建组件|新建组件|generate component type: regex # 依赖的工具 tools: - read_file - write_file - run_command # 上下文要求 context: - file: tsconfig.json required: true - file: .eslintrc.js required: false # 参数定义 parameters: - name: componentName description: 组件名称使用PascalCase required: true - name: withTest description: 是否生成测试文件 default: trueinstructions.md则是用自然语言写的执行指令这部分是给AI看的所以写法很关键。我后面会专门讲怎么写好这个文件。3.3 写好Instructions的五个关键原则Instructions写得好不好直接决定了skill能不能按照你的预期工作。我踩过不少坑之后总结了五条原则原则一用步骤化的语言不要用描述性的语言。不要说“这个skill用于生成组件”而要说“第一步读取tsconfig.json第二步根据componentName生成文件名第三步……”原则二明确输入和输出的格式。AI需要知道它应该接收什么格式的参数以及最终输出应该长什么样。最好给出具体的示例。原则三定义边界条件。如果componentName不符合PascalCase怎么办如果tsconfig.json不存在怎么办这些异常情况都要在instructions里面说清楚。原则四不要假设AI知道你的项目结构。即使你觉得某个信息“显而易见”也要写出来。比如你的组件放在src/components/目录下这个信息必须明确写出来。原则五保持instructions在500-2000字之间。太短了信息不够太长了AI可能会忽略中间的部分。如果确实需要更长的指令考虑拆分成多个skill。下面是一个实际的instructions示例# React组件生成器 ## 执行步骤 1. 读取项目根目录下的tsconfig.json确认jsx配置项的值 2. 读取.eslintrc.js如果存在提取代码规范相关配置 3. 根据用户提供的componentName参数执行以下操作 - 在src/components/目录下创建同名文件夹 - 生成index.tsx文件内容使用函数式组件模板 - 如果withTest参数为true生成index.test.tsx文件 - 生成index.module.css样式文件 ## 组件模板要求 - 使用React.FC类型标注 - Props接口命名为{ComponentName}Props - 默认导出组件 - 样式通过CSS Modules引入 ## 异常处理 - 如果src/components/目录不存在先创建该目录 - 如果同名组件已存在提示用户并询问是否覆盖 - 如果tsconfig.json不存在使用默认的TypeScript配置4. 实战用Skills搭建一套完整的前端开发工作流4.1 场景定义与Skill拆分策略光讲理论没意思我拿一个实际项目来演示。假设我们要搭建一套前端开发的工作流覆盖从创建组件到提交代码的全过程。首先要想清楚哪些环节适合做成skill我的判断标准是重复性高每次开发都要做的事情规则明确有清晰的输入输出和判断标准容易出错人工操作时经常遗漏或搞错的环节按照这个标准我把前端开发工作流拆成了四个skillSkill名称功能触发场景component-generator生成组件文件新建组件时test-writer生成单元测试组件写完后code-reviewer代码规范检查提交前commit-helper生成commit messagegit commit时这四个skill可以独立使用也可以串联起来形成完整的工作流。4.2 逐个Skill的实现细节component-generator这个skill我前面已经展示过基本结构了这里补充几个实际使用中总结的细节。第一个细节是关于模板文件的。我建议把组件模板放在templates/目录下用占位符标记需要替换的部分import React from react; import styles from ./index.module.css; interface {{ComponentName}}Props { // TODO: 定义props } const {{ComponentName}}: React.FC{{ComponentName}}Props (props) { return ( div className{styles.container} {/* TODO: 实现组件内容 */} /div ); }; export default {{ComponentName}};然后在instructions里面告诉AI读取模板文件把{{ComponentName}}替换成实际的组件名。第二个细节是关于文件命名。不同团队对组件文件的命名规范不一样有的用PascalCaseButton.tsx有的用kebab-casebutton.tsx。这个应该做成skill的参数让用户自己选择。test-writer这个skill的关键在于它需要先读取组件文件理解组件的props和功能然后生成对应的测试用例。Instructions大概是这样# 单元测试生成器 ## 前置条件 - 目标组件文件必须存在 - 项目必须已安装jest和testing-library/react ## 执行步骤 1. 读取目标组件的源代码 2. 分析组件的props接口 3. 为每个prop生成对应的测试用例 4. 生成边界条件测试空值、异常值等 5. 输出测试文件到组件同目录下 ## 测试模板要求 - 使用React Testing Library - 每个测试用例有清晰的描述 - 包含快照测试 - mock外部依赖code-reviewer这个skill比较特殊它不生成文件而是对已有代码进行分析。它的instructions需要定义清楚检查规则# 代码规范检查器 ## 检查项 1. 命名规范变量用camelCase组件用PascalCase常量用UPPER_SNAKE_CASE 2. 导入顺序React相关 第三方库 本地模块 样式文件 3. 未使用的变量和导入 4. console.log残留 5. any类型的使用应该尽量避免 6. 组件文件是否超过300行超过建议拆分 ## 输出格式 按照严重程度分级 - ERROR必须修复 - WARNING建议修复 - INFO提示信息commit-helper是最简单但最实用的一个skill。它读取git diff的输出根据变更内容生成符合Conventional Commits规范的commit message# Commit Message生成器 ## 执行步骤 1. 运行git diff --staged获取暂存的变更 2. 分析变更类型feat/fix/refactor/docs/test/chore 3. 分析变更范围哪个模块/文件 4. 生成commit message ## 格式要求 type(scope): description ## 示例 feat(auth): add login form validation fix(api): handle timeout error in user service refactor(utils): extract date formatting logic4.3 把Skills串联成工作流单个skill好用但真正提升效率的是把它们串起来。Claude Code支持在instructions里面引用其他skill# 完整开发工作流 当用户说开发一个新功能时依次执行 1. 调用component-generator创建组件 2. 调用test-writer生成测试 3. 调用code-reviewer检查代码 4. 调用commit-helper生成提交信息 每个步骤完成后等待用户确认再进入下一步。这种串联方式让AI agent能够自主完成一个完整的开发流程你只需要在关键节点做确认就行了。我实测下来一个中等复杂度的组件从创建到提交原来大概需要20-30分钟用这套工作流之后能压缩到5-8分钟。5. 踩坑实录Skills使用中的常见问题与排查5.1 安装配置阶段的典型报错问题一Claude Code提示“your organization has disabled claude subscription access”这个报错通常出现在企业环境下。原因是你的组织管理员在后台关闭了Claude Code的访问权限。解决办法是联系管理员在组织设置里面开启对应的权限。如果你用的是个人账号检查一下订阅是否过期。问题二Codex报错“codex is ignoring 1 unrecognized configuration setting”这个警告说明你的配置文件里面有一个Codex不认识的配置项。通常是因为版本不匹配——你参考的文档可能是旧版本的新版本已经废弃了某个配置项。解决办法是检查Codex的版本然后对照官方文档更新配置文件。常见的废弃配置包括model现在用default_model代替和temperature现在通过model_params设置。问题三cc switch local proxy failed while handling codex endpoint /responses这个报错一般出现在同时使用多个AI工具的时候端口冲突导致的。检查一下是不是有其他程序占用了相同的端口。另外确认一下你的代理配置是否正确有时候是环境变量HTTP_PROXY设置有问题。问题四安装Claude Code时npm报错“in order to access this application, you must install the j2se plugin”这个报错说明你的Java环境有问题。虽然Claude Code本身是Node.js写的但它某些依赖可能需要Java运行时。安装一个JRE或者JDK就能解决# Ubuntu/Debian sudo apt install default-jre # macOS brew install openjdk # Windows # 下载并安装Oracle JDK或OpenJDK5.2 Skill不生效的排查思路Skill写了但AI不按照预期执行这是最常见的问题。我总结了一个排查清单排查项检查方法常见原因文件路径确认skill在.claude/skills/目录下路径拼写错误或层级不对YAML格式用在线YAML验证器检查缩进错误、特殊字符未转义触发条件手动输入触发词测试正则表达式写错、关键词不匹配指令长度检查instructions.md字数超过2000字导致AI忽略部分内容权限问题确认文件和目录可读文件权限设置过严版本兼容检查工具版本skill语法在新版本中已变更我遇到最多的问题是YAML格式错误。YAML对缩进非常敏感多一个空格少一个空格都可能导致解析失败。建议用专业的编辑器比如VS Code配合YAML插件来编辑能实时提示格式问题。另一个高频问题是触发条件写得太窄。比如你写了一个触发词是“创建React组件”但用户实际说的是“帮我写个组件”那就触发不了。解决办法是把触发条件写宽一点用正则表达式的|来匹配多种说法。5.3 性能优化与最佳实践Skills用多了之后你会发现启动速度变慢了。这是因为每次启动时工具都要加载和解析所有的skill文件。我总结了几个优化技巧技巧一按需加载。不是所有skill都需要在启动时加载。把不常用的skill标记为lazy: true只在被触发时才加载。技巧二合并相关skill。如果你有五个skill都是关于React组件开发的考虑合并成一个大的skill用参数来区分不同的功能。这样可以减少文件数量和加载时间。技巧三精简instructions。定期审查instructions.md删除过时的内容和冗余的描述。我一般每个月会花半小时做一次清理。技巧四使用缓存。Claude Code支持对skill的解析结果进行缓存。在配置文件中开启cache: true可以显著提升重复启动的速度。提示如果你发现某个skill经常导致AI输出不稳定先检查instructions里面有没有模糊的表述。比如“生成合适的测试”这种说法就太模糊了AI每次的理解可能都不一样。改成“为每个prop生成一个测试用例包括正常值和边界值”就明确多了。6. 进阶玩法Skills的组合、嵌套与自动化6.1 Skill之间的依赖管理当你的skill数量超过十个之后依赖管理就变成一个必须考虑的问题。比如test-writer依赖于component-generator先执行commit-helper依赖于code-reviewer先通过。Claude Code支持在skill.yaml中声明依赖关系name: test-writer depends_on: - component-generator preconditions: - check: file_exists path: src/components/{{componentName}}/index.tsx error: 请先创建组件文件这样当依赖不满足时工具会给出明确的提示而不是让AI在那里瞎猜。6.2 用Skills实现自动化代码审查代码审查是skills最能发挥价值的场景之一。传统的代码审查要么靠人工慢且容易遗漏要么靠ESLint之类的工具只能检查语法层面的问题。Skills可以做更深层次的审查。我配置了一套审查skill它会检查业务逻辑一致性新代码是否符合现有的业务规则错误处理完整性所有异步操作是否有错误处理性能隐患是否有不必要的重渲染、内存泄漏风险安全规范是否有硬编码的敏感信息、未验证的用户输入这套skill配合CI/CD流水线使用每次PR提交时自动运行审查结果直接评论在PR上。用了三个月之后我们团队的代码review时间平均缩短了40%。6.3 团队协作中的Skills共享一个人用skills和团队用skills是两回事。团队使用需要考虑版本控制把.claude/skills/目录纳入git管理这样每个人都能获取最新的skill配置。权限分级不是所有人都应该能修改skill。建议设置一个skills-admin角色只有这个角色的人才能合并skill的变更。文档化每个skill都要有清晰的README说明它的功能、使用方法和注意事项。我见过太多团队因为skill没有文档导致新人根本不知道怎么用。定期review每个季度review一次所有的skill删除不再使用的更新过时的内容。Skills和代码一样不维护就会腐烂。7. 我个人的一些经验体会说了这么多技术和操作层面的东西最后聊几句我自己的感受。Skills这个东西刚出来的时候我觉得它就是个花哨的prompt管理工具。但用了一年多之后我的看法完全变了。它实际上是在解决一个更根本的问题如何把人的领域知识转化为AI可以执行的规则。这件事的意义远超“提升编码效率”。当我把团队的前端开发规范写成skill之后我发现新人上手的速度明显加快了。以前一个新人要花两周才能熟悉我们的代码规范现在他只要用Claude Code配合我们的skills第一天就能生成符合规范的代码。当然他仍然需要理解为什么要有这些规范但至少不会在格式问题上浪费时间了。另一个让我意外的收获是写skill的过程本身就是在梳理和优化流程。有好几次我在写instructions的时候突然意识到“等等我们现在的流程里有个步骤是多余的。”或者“这个环节其实可以自动化。”写skill逼着你把模糊的流程变得清晰这个价值可能比skill本身还大。如果你还没开始用skills我的建议是从一个小场景开始。不要一上来就想着搭建完整的工作流先写一个最简单的skill——比如自动生成commit message——用一周时间感受一下。等你习惯了这种工作方式再逐步扩展。如果你已经在用skills了但觉得效果一般我建议你回头检查一下instructions的质量。大部分skill不好用问题都出在instructions写得太模糊。试着把每一步都写得像给一个新员工培训那样详细效果会好很多。这个领域变化很快新的工具和玩法层出不穷。但核心逻辑是不变的把重复的事情标准化把标准的事情自动化。Skills只是实现这个目标的一种手段理解了这个逻辑不管工具怎么变你都能快速适应。