拓冰网站定制 
1. 从“skills”这个热词说起它到底是什么为什么突然火了如果你最近在开发者社区、AI 工具圈或者技术群里频繁看到“skills”这个词不用怀疑它说的不是传统意义上的“技能培训”或者“软技能”而是Agent Skills——一套让 AI 编程助手尤其是 Claude Code 这类 CLI Agent具备可复用、可组合、可版本管理的“能力模块”的机制。简单说它把“让 AI 干某件事”从一次性对话变成了一个可以像 npm 包一样安装、分享、迭代的工程化产物。我最早接触这个概念是在折腾 Claude Code 的时候。当时我的诉求很朴素每次让 AI 帮我写一个 React 组件它都要重新理解我的项目结构、代码规范、目录约定效率低得让人抓狂。后来发现社区里已经有人把这类“项目上下文 操作流程 约束条件”打包成了 SKILL.md 文件放进.claude/skills/目录Claude Code 启动时会自动加载。那一刻我才意识到skills 解决的不是“AI 会不会写代码”的问题而是“AI 能不能稳定地、按你的规矩写代码”的问题。这篇文章适合三类人看第一类是完全没接触过 Claude Code 或 Agent Skills但被各种热词轰炸得心痒痒的前端/后端开发者第二类是已经在用 Claude Code但每次都要重复贴上下文、效率上不去的中级用户第三类是想自己写 skills、做内部工具链沉淀的团队技术负责人。我会从概念拆解、目录结构、SKILL.md 写法、安装配置、常见报错排查、实战案例几个维度把这件事讲透。你不需要有 AI 背景只要你会用命令行、写过 Markdown就能跟着做。提示本文提到的 Claude Code 是一个命令行 AI 编程助手Agent Skills 是它的一套扩展机制。如果你还没装 Claude Code后面有专门的安装章节Windows、macOS、Linux 都覆盖。2. Agent Skills 的核心设计逻辑为什么不是“插件”而是“技能”2.1 从“提示词工程”到“技能工程”的范式转移过去两年大家聊 AI 编程绕不开“提示词工程”。你写一段 system prompt告诉 AI 你是谁、项目是什么、要遵守什么规范。但提示词有个致命问题它是扁平的、一次性的、不可组合的。你项目里有 20 个规范全塞进一个 promptAI 的注意力会被稀释而且换个项目就得重写。Agent Skills 的设计思路完全不同。它把“能力”拆成独立的目录每个目录里有一个SKILL.md作为入口可以附带脚本、模板、参考文档。Claude Code 在启动时扫描 skills 目录根据当前任务动态加载相关技能。这就像从“把整本说明书塞给新员工”变成了“给新员工一个带索引的工具箱需要什么拿什么”。我实测下来这种机制最大的好处是上下文精准。比如我有一个react-componentskill里面只写 React 组件相关的规范另一个api-designskill只写后端接口约定。当我让 Claude 写前端组件时它只加载前者不会把后端规范也读进去浪费 token。这种按需加载的设计比一股脑塞 prompt 优雅太多。2.2 SKILL.md 的定位不是文档是“可执行契约”很多人第一次看到 SKILL.md会以为它就是个说明文档。其实不是。它更像一份契约告诉 Agent 在什么场景下触发、需要遵循什么步骤、输出什么格式、有哪些禁忌。它同时被人和 AI 阅读——人看它是为了维护和迭代AI 读它是为了执行。一个合格的 SKILL.md 通常包含几个部分name和description用于元信息识别when to use说明触发条件instructions是核心操作步骤examples给出输入输出样例constraints列出禁止事项。我见过不少写得好的 skill光constraints部分就列了十几条比如“不要使用 any 类型”“不要引入新的第三方依赖”“所有异步操作必须处理错误”。这些约束才是 skill 真正的价值所在。2.3 为什么社区突然涌现大量 skills热词里出现了“superpower skills”“数学建模 skills”“AI 漫剧常用 skills”“codex nature skills”这些词说明 skills 已经从单纯的编程辅助扩散到了建模、内容创作、科研等场景。背后的原因很简单任何有固定流程的重复性工作都可以被 skill 化。数学建模比赛里数据预处理、模型选择、论文排版有固定套路做成 skill 就能让 AI 按套路输出AI 漫剧创作里分镜脚本、角色设定、提示词模板也可以 skill 化。这种“把经验固化成可复用模块”的需求是普适的所以 skills 生态在短短几个月内就膨胀起来了。GitHub 上搜awesome-claude-skills或者typesafe ai skills能找到大量开源 skill 集合。3. 环境准备Claude Code 安装与 skills 目录初始化3.1 安装 Claude Code 的三种路径Claude Code 本质是一个 Node.js CLI 工具安装方式取决于你的系统。最推荐的是用 npm 全局安装因为后续更新和 skill 管理都方便。# 确保 Node.js 版本 18 node -v # 全局安装 Claude Code npm install -g anthropic-ai/claude-code # 验证安装 claude --version如果你在 Windows 上遇到claude : 无法将“claude”项识别为 cmdlet、函数、脚本文件或可运行程序的名称这个报错八成是 npm 全局 bin 目录没加到 PATH。用npm config get prefix找到全局目录把它加到系统环境变量里重启终端即可。这个坑我踩过当时排查了半小时最后发现是 PATH 问题。macOS 用户如果不想用 npm也可以用 Homebrew 或者官方提供的安装脚本。Linux 用户注意权限问题全局安装可能需要sudo但更推荐用nvm管理 Node 版本避免权限混乱。注意热词里提到的“claude code desktop 国内下载”“claude code 桌面版”这类需求目前官方主推的还是 CLI 形态。桌面版体验和 CLI 有差异建议优先把 CLI 跑通因为 skills 机制在 CLI 下最完整。3.2 初始化项目级 skills 目录Claude Code 支持全局 skills 和项目级 skills 两种。全局的放在~/.claude/skills/项目级的放在项目根目录的.claude/skills/。我强烈建议项目级优先因为不同项目的规范差异很大全局 skill 容易互相干扰。# 在项目根目录创建 skills 目录 mkdir -p .claude/skills # 目录结构长这样 # .claude/ # skills/ # react-component/ # SKILL.md # templates/ # api-design/ # SKILL.md每个 skill 一个子目录目录名就是 skill 的标识。子目录里必须有SKILL.md其他文件模板、脚本、参考文档按需放。Claude Code 启动时会递归扫描这个目录把每个 SKILL.md 的元信息读进上下文。3.3 验证 skills 是否被正确加载装好之后怎么确认 Claude Code 真的读到了你的 skill在项目目录下启动claude然后输入/skills或者直接问它“你现在加载了哪些 skills”。如果配置正确它会列出你定义的 skill 名称和描述。如果没列出来检查三件事目录路径对不对、SKILL.md 的 frontmatter 格式对不对、文件编码是不是 UTF-8。我遇到过一种情况SKILL.md 写好了但 Claude 死活不加载。后来发现是 frontmatter 里的name字段用了中文导致解析失败。改成英文短横线命名后立刻正常。这个细节官方文档没强调但实测很关键。4. SKILL.md 怎么写从零手搓一个可用的 skill4.1 frontmatter 元信息name、description、triggerSKILL.md 的开头必须是 YAML frontmatter这是 Claude Code 识别 skill 的依据。最小可用配置如下--- name: react-component description: 按项目规范生成 React 函数组件包含 TypeScript 类型、样式约定和测试文件 ---name用英文小写加短横线不要用空格或中文。description要写清楚“这个 skill 干什么、什么时候用”因为 Claude 是根据 description 来判断是否加载的。我见过有人 description 写得太泛比如“帮助写代码”结果 Claude 在任何场景都加载它反而干扰了其他 skill。更精细的写法可以加trigger字段用关键词或文件路径模式来限定触发条件。比如--- name: api-design description: 设计 RESTful API 接口遵循项目统一的命名和错误码规范 trigger: - 设计接口 - 新增 API - *.controller.ts ---这样只有当对话里出现这些关键词或者操作的文件匹配路径模式时skill 才会被激活。这种精准触发能大幅减少上下文污染。4.2 指令主体步骤化、可执行、带约束frontmatter 之后就是正文。正文的写法决定了 skill 的质量。我的经验是用编号步骤每步一个动作避免模糊描述。对比一下差的写法“请生成符合规范的 React 组件。”——太模糊AI 不知道什么叫“符合规范”。好的写法## 操作步骤 1. 在 src/components/ 下创建同名目录目录名用 PascalCase。 2. 创建 index.tsx使用函数组件 TypeScript禁止使用 class 组件。 3. Props 类型命名为 {组件名}Props必须显式导出。 4. 样式使用 CSS Modules文件名 index.module.css。 5. 同步创建 index.test.tsx至少覆盖渲染和主要交互。 6. 在组件目录下创建 README.md说明 props 和用法。这种写法 AI 执行起来几乎不会跑偏。关键是每一步都有明确的产物和位置没有解释空间。4.3 约束与禁忌把“不要做什么”写清楚约束部分是很多人忽略的但它恰恰是 skill 区别于普通 prompt 的核心。我通常会把约束分成三类技术约束、风格约束、安全约束。技术约束比如“不要引入 lodash”“不要使用 any”“所有 API 调用必须走统一的 request 封装”。风格约束比如“组件文件不超过 200 行”“注释用中文”“变量名用 camelCase”。安全约束比如“不要硬编码密钥”“不要在前端代码里写数据库连接串”。这些约束写进 SKILL.md 后Claude 在生成代码时会主动规避。我实测过一个对比同一个组件生成任务没有约束的 skill 生成了 3 个 any 类型和 2 处硬编码 URL加了约束后一次通过零违规。这个差距在团队协作场景下是决定性的。4.4 示例与反例让 AI 学会“照着做”SKILL.md 里放示例效果比纯文字描述好得多。我习惯放两组一组正例一组反例。正例展示期望的输出反例展示常见错误。Claude 对模式匹配很敏感看到反例会主动避开。## 示例 ### 正例 输入创建一个用户卡片组件 输出src/components/UserCard/index.tsx包含 UserCardProps 类型、CSS Modules 样式、测试文件。 ### 反例 不要在组件里直接写 fetch 调用应该通过 src/api/user.ts 封装。 不要在 JSX 里写内联样式对象统一用 CSS Modules。这种正反对比的写法比单纯说“要怎样”有效得多。我带的几个新人看完这种 skill 后写出来的代码规范度明显提升。5. 安装与使用社区 skills从 GitHub 到本地5.1 找到靠谱的 skills 来源热词里出现了“skills 技能库网址”“skills 下载”“常用 skills”“skills 推荐”说明大家最关心的是去哪找现成的。目前主要的来源有几个GitHub 上的awesome-claude-skills类仓库、官方示例仓库、以及一些团队开源的内部 skill 集合。搜的时候用claude skillsagent skillsSKILL.md这些关键词组合能筛出不少。我个人的筛选标准是看 star 数、看最近更新时间、看 SKILL.md 的完整度。一个 skill 如果只有 frontmatter 没有正文或者 description 写得含糊基本可以跳过。好的 skill 通常有清晰的目录结构、详细的约束、以及实际使用案例。5.2 手动安装 GitHub 上的 skill热词里有个很具体的问题“claude code 怎么手动装 github 上的 skills”。步骤其实很简单但有几个细节容易出错。# 假设你要安装的 skill 仓库叫 awesome-skills git clone https://github.com/xxx/awesome-skills.git /tmp/awesome-skills # 找到你需要的 skill 目录比如 react-component # 复制到项目的 .claude/skills/ 下 cp -r /tmp/awesome-skills/react-component .claude/skills/ # 验证目录结构 ls .claude/skills/react-component/ # 应该看到 SKILL.md 以及可能的 templates/ scripts/ 等关键点复制的是 skill 子目录不是整个仓库。很多人直接把整个仓库塞进 skills 目录结果 Claude 扫描到一堆无关文件加载效率下降。另外复制后检查一下 SKILL.md 的 frontmatter 是否完整有些仓库的 skill 依赖特定环境变量或外部脚本需要额外配置。5.3 全局 skill 与项目 skill 的取舍全局 skill 放在~/.claude/skills/对所有项目生效。适合放那种通用性极强的 skill比如“代码审查”“提交信息生成”“单元测试模板”。项目 skill 放在.claude/skills/只对当前项目生效适合放项目特有的规范。我的做法是通用能力放全局项目规范放项目级。比如我有一个全局的commit-messageskill规定提交信息用 Conventional Commits 格式项目级的api-designskill 则规定这个项目的接口命名和错误码。这样既复用了通用能力又保证了项目特异性。注意全局 skill 和项目 skill 同名时项目级会覆盖全局。这个机制可以用来做项目级定制但也要小心命名冲突导致意外覆盖。6. 实战案例用 skills 改造一个前端项目的开发流程6.1 场景设定与痛点分析假设你维护一个中型 React TypeScript 项目团队 5 个人代码规范靠 ESLint 和口头约定。痛点很明显新人写的组件风格不统一API 调用散落各处测试覆盖率忽高忽低。每次 code review 都要花大量时间纠正格式问题而不是讨论业务逻辑。我的改造思路是把“组件开发”“API 调用”“测试编写”三件事 skill 化让 Claude Code 在生成代码时就遵守规范从源头减少 review 成本。6.2 编写三个核心 skill第一个是react-component规定组件目录结构、命名、样式方案、测试要求。第二个是api-client规定所有网络请求必须走src/api/下的封装禁止组件内直接 fetch。第三个是test-writer规定测试文件位置、命名、覆盖要求。以api-client为例SKILL.md 核心内容如下--- name: api-client description: 封装 API 请求统一错误处理和类型定义 trigger: - 调用接口 - 请求数据 - src/api/ --- ## 步骤 1. 在 src/api/ 下创建或修改对应模块文件文件名用 camelCase。 2. 每个接口导出为一个函数函数名以 fetch 开头。 3. 请求和响应类型必须显式定义放在同目录的 types.ts。 4. 错误处理统一走 src/api/errorHandler.ts禁止在业务层 try-catch。 5. 所有请求必须带超时配置默认 10 秒。 ## 约束 - 禁止在组件文件里直接写 fetch 或 axios。 - 禁止硬编码 baseURL从环境变量读取。 - 禁止在 API 层写业务逻辑。这三个 skill 写完后我让团队新人用了一周。结果是组件目录结构零偏差API 调用全部走封装测试文件自动生成。Code review 时间从平均 40 分钟降到 15 分钟省下来的时间用来讨论业务边界和性能优化。6.3 效果验证与迭代skill 不是写完就一劳永逸的。我每周会看一次 Claude Code 的生成记录找出它违反约束的情况然后反推 SKILL.md 哪里写得不够明确。比如有一次发现它把测试文件放到了__tests__目录而不是组件同级目录检查后发现是 SKILL.md 里没写清楚路径规则。补上一句“测试文件与组件文件同级”后问题消失。这种迭代过程本身就是 skill 的价值它把团队的隐性知识显性化并且可以持续优化。三个月下来我们的 skill 集合从 3 个扩展到 11 个覆盖了组件、API、测试、文档、提交信息、代码审查等环节。7. 常见问题与排查技巧实录7.1 安装与加载类问题问题现象可能原因解决方法claude命令找不到npm 全局 bin 未加入 PATH用npm config get prefix找到路径加入环境变量skill 不生效SKILL.md frontmatter 格式错误检查 YAML 语法name 用英文小写短横线skill 加载了但行为不对description 太泛导致误触发收窄 description加 trigger 关键词项目 skill 覆盖全局 skill同名冲突重命名其中一个或明确使用场景Windows 用户特别注意热词里提到的“claudes workspace requires the virtual machine platform on windows”这类报错通常和 WSL 或虚拟化环境有关。如果你在 Windows 上用 Claude Code建议直接在 WSL2 里跑避免路径和权限的兼容问题。我试过在纯 Windows 环境下折腾路径分隔符和文件权限经常出幺蛾子换到 WSL2 后一次跑通。7.2 skill 编写类问题问题一skill 太长Claude 加载后反而变慢。原因是 SKILL.md 正文太长占用了大量上下文。解决方法是把详细参考文档拆到单独文件SKILL.md 里只留核心步骤和约束用相对路径引用其他文件。Claude Code 支持按需读取子文件不会一次性全加载。问题二skill 之间互相冲突。比如react-component说用 CSS Modulesstylingskill 说用 Tailwind。解决方法是明确优先级或者在 description 里写清楚适用边界。我的做法是给每个 skill 加一个priority字段数值高的优先。问题三skill 里的脚本执行失败。有些 skill 附带 shell 脚本或 Node 脚本如果脚本依赖的环境变量没配置就会报错。建议在 SKILL.md 里写明依赖项并在脚本开头加环境检查。7.3 独家避坑技巧第一个技巧用claude --debug看 skill 加载日志。这个命令会输出详细的加载过程包括扫描了哪些目录、加载了哪些 skill、跳过了哪些文件。排查问题时比盲猜高效得多。第二个技巧skill 目录用软链接管理。如果你有多个项目共用一套 skill不要复制粘贴用软链接指向同一个源目录。这样改一处所有项目生效。ln -s ~/my-skills/react-component .claude/skills/react-component第三个技巧定期清理不用的 skill。热词里有人问“tibo 关于清理 skills 的方法推荐”说明这是普遍需求。我的做法是每月 review 一次把三个月没触发过的 skill 归档。skill 太多会导致 Claude 启动时扫描变慢而且增加误触发概率。8. 进阶方向把 skills 变成团队资产8.1 skill 的版本管理与协作当 skill 数量超过 10 个就需要版本管理了。我的做法是建一个独立的 Git 仓库专门放 skills每个 skill 一个目录用 tag 标记版本。项目里通过 git submodule 或者软链接引用。这样 skill 的变更可以走 code review 流程避免有人随手改坏。协作方面我建议给每个 skill 配一个OWNER.md写明维护人、适用项目、最近更新日期。新人接手时能快速找到负责人。这个做法是从开源项目学来的在团队内部效果很好。8.2 从 skill 到内部工具链skills 的终极形态是内部工具链的一部分。比如把 skill 和 CI 结合提交代码时自动跑 skill 里定义的检查规则或者把 skill 和文档系统结合SKILL.md 本身就是最好的项目规范文档。我见过一个团队把 skill 做成了 onboarding 工具新人入职第一天装好 Claude Code克隆 skills 仓库然后让 AI 带着他写第一个组件。整个过程不需要老员工手把手教因为规范都写在 skill 里了。这种“自解释”的开发环境才是 skills 机制最大的想象空间。8.3 跨领域迁移数学建模、内容创作、科研热词里“数学建模 skills”“AI 漫剧常用 skills”“codex nature skills”这些词说明 skills 正在向非编程领域渗透。逻辑是一样的把领域内的固定流程和约束写成 SKILL.md让 AI 按套路执行。数学建模场景下一个> Agent Skills 实战：用 SKILL.md 让 Claude Code 稳定按规范写代码
1. 从“skills”这个热词说起它到底是什么为什么突然火了如果你最近在开发者社区、AI 工具圈或者技术群里频繁看到“skills”这个词不用怀疑它说的不是传统意义上的“技能培训”或者“软技能”而是Agent Skills——一套让 AI 编程助手尤其是 Claude Code 这类 CLI Agent具备可复用、可组合、可版本管理的“能力模块”的机制。简单说它把“让 AI 干某件事”从一次性对话变成了一个可以像 npm 包一样安装、分享、迭代的工程化产物。我最早接触这个概念是在折腾 Claude Code 的时候。当时我的诉求很朴素每次让 AI 帮我写一个 React 组件它都要重新理解我的项目结构、代码规范、目录约定效率低得让人抓狂。后来发现社区里已经有人把这类“项目上下文 操作流程 约束条件”打包成了 SKILL.md 文件放进.claude/skills/目录Claude Code 启动时会自动加载。那一刻我才意识到skills 解决的不是“AI 会不会写代码”的问题而是“AI 能不能稳定地、按你的规矩写代码”的问题。这篇文章适合三类人看第一类是完全没接触过 Claude Code 或 Agent Skills但被各种热词轰炸得心痒痒的前端/后端开发者第二类是已经在用 Claude Code但每次都要重复贴上下文、效率上不去的中级用户第三类是想自己写 skills、做内部工具链沉淀的团队技术负责人。我会从概念拆解、目录结构、SKILL.md 写法、安装配置、常见报错排查、实战案例几个维度把这件事讲透。你不需要有 AI 背景只要你会用命令行、写过 Markdown就能跟着做。提示本文提到的 Claude Code 是一个命令行 AI 编程助手Agent Skills 是它的一套扩展机制。如果你还没装 Claude Code后面有专门的安装章节Windows、macOS、Linux 都覆盖。2. Agent Skills 的核心设计逻辑为什么不是“插件”而是“技能”2.1 从“提示词工程”到“技能工程”的范式转移过去两年大家聊 AI 编程绕不开“提示词工程”。你写一段 system prompt告诉 AI 你是谁、项目是什么、要遵守什么规范。但提示词有个致命问题它是扁平的、一次性的、不可组合的。你项目里有 20 个规范全塞进一个 promptAI 的注意力会被稀释而且换个项目就得重写。Agent Skills 的设计思路完全不同。它把“能力”拆成独立的目录每个目录里有一个SKILL.md作为入口可以附带脚本、模板、参考文档。Claude Code 在启动时扫描 skills 目录根据当前任务动态加载相关技能。这就像从“把整本说明书塞给新员工”变成了“给新员工一个带索引的工具箱需要什么拿什么”。我实测下来这种机制最大的好处是上下文精准。比如我有一个react-componentskill里面只写 React 组件相关的规范另一个api-designskill只写后端接口约定。当我让 Claude 写前端组件时它只加载前者不会把后端规范也读进去浪费 token。这种按需加载的设计比一股脑塞 prompt 优雅太多。2.2 SKILL.md 的定位不是文档是“可执行契约”很多人第一次看到 SKILL.md会以为它就是个说明文档。其实不是。它更像一份契约告诉 Agent 在什么场景下触发、需要遵循什么步骤、输出什么格式、有哪些禁忌。它同时被人和 AI 阅读——人看它是为了维护和迭代AI 读它是为了执行。一个合格的 SKILL.md 通常包含几个部分name和description用于元信息识别when to use说明触发条件instructions是核心操作步骤examples给出输入输出样例constraints列出禁止事项。我见过不少写得好的 skill光constraints部分就列了十几条比如“不要使用 any 类型”“不要引入新的第三方依赖”“所有异步操作必须处理错误”。这些约束才是 skill 真正的价值所在。2.3 为什么社区突然涌现大量 skills热词里出现了“superpower skills”“数学建模 skills”“AI 漫剧常用 skills”“codex nature skills”这些词说明 skills 已经从单纯的编程辅助扩散到了建模、内容创作、科研等场景。背后的原因很简单任何有固定流程的重复性工作都可以被 skill 化。数学建模比赛里数据预处理、模型选择、论文排版有固定套路做成 skill 就能让 AI 按套路输出AI 漫剧创作里分镜脚本、角色设定、提示词模板也可以 skill 化。这种“把经验固化成可复用模块”的需求是普适的所以 skills 生态在短短几个月内就膨胀起来了。GitHub 上搜awesome-claude-skills或者typesafe ai skills能找到大量开源 skill 集合。3. 环境准备Claude Code 安装与 skills 目录初始化3.1 安装 Claude Code 的三种路径Claude Code 本质是一个 Node.js CLI 工具安装方式取决于你的系统。最推荐的是用 npm 全局安装因为后续更新和 skill 管理都方便。# 确保 Node.js 版本 18 node -v # 全局安装 Claude Code npm install -g anthropic-ai/claude-code # 验证安装 claude --version如果你在 Windows 上遇到claude : 无法将“claude”项识别为 cmdlet、函数、脚本文件或可运行程序的名称这个报错八成是 npm 全局 bin 目录没加到 PATH。用npm config get prefix找到全局目录把它加到系统环境变量里重启终端即可。这个坑我踩过当时排查了半小时最后发现是 PATH 问题。macOS 用户如果不想用 npm也可以用 Homebrew 或者官方提供的安装脚本。Linux 用户注意权限问题全局安装可能需要sudo但更推荐用nvm管理 Node 版本避免权限混乱。注意热词里提到的“claude code desktop 国内下载”“claude code 桌面版”这类需求目前官方主推的还是 CLI 形态。桌面版体验和 CLI 有差异建议优先把 CLI 跑通因为 skills 机制在 CLI 下最完整。3.2 初始化项目级 skills 目录Claude Code 支持全局 skills 和项目级 skills 两种。全局的放在~/.claude/skills/项目级的放在项目根目录的.claude/skills/。我强烈建议项目级优先因为不同项目的规范差异很大全局 skill 容易互相干扰。# 在项目根目录创建 skills 目录 mkdir -p .claude/skills # 目录结构长这样 # .claude/ # skills/ # react-component/ # SKILL.md # templates/ # api-design/ # SKILL.md每个 skill 一个子目录目录名就是 skill 的标识。子目录里必须有SKILL.md其他文件模板、脚本、参考文档按需放。Claude Code 启动时会递归扫描这个目录把每个 SKILL.md 的元信息读进上下文。3.3 验证 skills 是否被正确加载装好之后怎么确认 Claude Code 真的读到了你的 skill在项目目录下启动claude然后输入/skills或者直接问它“你现在加载了哪些 skills”。如果配置正确它会列出你定义的 skill 名称和描述。如果没列出来检查三件事目录路径对不对、SKILL.md 的 frontmatter 格式对不对、文件编码是不是 UTF-8。我遇到过一种情况SKILL.md 写好了但 Claude 死活不加载。后来发现是 frontmatter 里的name字段用了中文导致解析失败。改成英文短横线命名后立刻正常。这个细节官方文档没强调但实测很关键。4. SKILL.md 怎么写从零手搓一个可用的 skill4.1 frontmatter 元信息name、description、triggerSKILL.md 的开头必须是 YAML frontmatter这是 Claude Code 识别 skill 的依据。最小可用配置如下--- name: react-component description: 按项目规范生成 React 函数组件包含 TypeScript 类型、样式约定和测试文件 ---name用英文小写加短横线不要用空格或中文。description要写清楚“这个 skill 干什么、什么时候用”因为 Claude 是根据 description 来判断是否加载的。我见过有人 description 写得太泛比如“帮助写代码”结果 Claude 在任何场景都加载它反而干扰了其他 skill。更精细的写法可以加trigger字段用关键词或文件路径模式来限定触发条件。比如--- name: api-design description: 设计 RESTful API 接口遵循项目统一的命名和错误码规范 trigger: - 设计接口 - 新增 API - *.controller.ts ---这样只有当对话里出现这些关键词或者操作的文件匹配路径模式时skill 才会被激活。这种精准触发能大幅减少上下文污染。4.2 指令主体步骤化、可执行、带约束frontmatter 之后就是正文。正文的写法决定了 skill 的质量。我的经验是用编号步骤每步一个动作避免模糊描述。对比一下差的写法“请生成符合规范的 React 组件。”——太模糊AI 不知道什么叫“符合规范”。好的写法## 操作步骤 1. 在 src/components/ 下创建同名目录目录名用 PascalCase。 2. 创建 index.tsx使用函数组件 TypeScript禁止使用 class 组件。 3. Props 类型命名为 {组件名}Props必须显式导出。 4. 样式使用 CSS Modules文件名 index.module.css。 5. 同步创建 index.test.tsx至少覆盖渲染和主要交互。 6. 在组件目录下创建 README.md说明 props 和用法。这种写法 AI 执行起来几乎不会跑偏。关键是每一步都有明确的产物和位置没有解释空间。4.3 约束与禁忌把“不要做什么”写清楚约束部分是很多人忽略的但它恰恰是 skill 区别于普通 prompt 的核心。我通常会把约束分成三类技术约束、风格约束、安全约束。技术约束比如“不要引入 lodash”“不要使用 any”“所有 API 调用必须走统一的 request 封装”。风格约束比如“组件文件不超过 200 行”“注释用中文”“变量名用 camelCase”。安全约束比如“不要硬编码密钥”“不要在前端代码里写数据库连接串”。这些约束写进 SKILL.md 后Claude 在生成代码时会主动规避。我实测过一个对比同一个组件生成任务没有约束的 skill 生成了 3 个 any 类型和 2 处硬编码 URL加了约束后一次通过零违规。这个差距在团队协作场景下是决定性的。4.4 示例与反例让 AI 学会“照着做”SKILL.md 里放示例效果比纯文字描述好得多。我习惯放两组一组正例一组反例。正例展示期望的输出反例展示常见错误。Claude 对模式匹配很敏感看到反例会主动避开。## 示例 ### 正例 输入创建一个用户卡片组件 输出src/components/UserCard/index.tsx包含 UserCardProps 类型、CSS Modules 样式、测试文件。 ### 反例 不要在组件里直接写 fetch 调用应该通过 src/api/user.ts 封装。 不要在 JSX 里写内联样式对象统一用 CSS Modules。这种正反对比的写法比单纯说“要怎样”有效得多。我带的几个新人看完这种 skill 后写出来的代码规范度明显提升。5. 安装与使用社区 skills从 GitHub 到本地5.1 找到靠谱的 skills 来源热词里出现了“skills 技能库网址”“skills 下载”“常用 skills”“skills 推荐”说明大家最关心的是去哪找现成的。目前主要的来源有几个GitHub 上的awesome-claude-skills类仓库、官方示例仓库、以及一些团队开源的内部 skill 集合。搜的时候用claude skillsagent skillsSKILL.md这些关键词组合能筛出不少。我个人的筛选标准是看 star 数、看最近更新时间、看 SKILL.md 的完整度。一个 skill 如果只有 frontmatter 没有正文或者 description 写得含糊基本可以跳过。好的 skill 通常有清晰的目录结构、详细的约束、以及实际使用案例。5.2 手动安装 GitHub 上的 skill热词里有个很具体的问题“claude code 怎么手动装 github 上的 skills”。步骤其实很简单但有几个细节容易出错。# 假设你要安装的 skill 仓库叫 awesome-skills git clone https://github.com/xxx/awesome-skills.git /tmp/awesome-skills # 找到你需要的 skill 目录比如 react-component # 复制到项目的 .claude/skills/ 下 cp -r /tmp/awesome-skills/react-component .claude/skills/ # 验证目录结构 ls .claude/skills/react-component/ # 应该看到 SKILL.md 以及可能的 templates/ scripts/ 等关键点复制的是 skill 子目录不是整个仓库。很多人直接把整个仓库塞进 skills 目录结果 Claude 扫描到一堆无关文件加载效率下降。另外复制后检查一下 SKILL.md 的 frontmatter 是否完整有些仓库的 skill 依赖特定环境变量或外部脚本需要额外配置。5.3 全局 skill 与项目 skill 的取舍全局 skill 放在~/.claude/skills/对所有项目生效。适合放那种通用性极强的 skill比如“代码审查”“提交信息生成”“单元测试模板”。项目 skill 放在.claude/skills/只对当前项目生效适合放项目特有的规范。我的做法是通用能力放全局项目规范放项目级。比如我有一个全局的commit-messageskill规定提交信息用 Conventional Commits 格式项目级的api-designskill 则规定这个项目的接口命名和错误码。这样既复用了通用能力又保证了项目特异性。注意全局 skill 和项目 skill 同名时项目级会覆盖全局。这个机制可以用来做项目级定制但也要小心命名冲突导致意外覆盖。6. 实战案例用 skills 改造一个前端项目的开发流程6.1 场景设定与痛点分析假设你维护一个中型 React TypeScript 项目团队 5 个人代码规范靠 ESLint 和口头约定。痛点很明显新人写的组件风格不统一API 调用散落各处测试覆盖率忽高忽低。每次 code review 都要花大量时间纠正格式问题而不是讨论业务逻辑。我的改造思路是把“组件开发”“API 调用”“测试编写”三件事 skill 化让 Claude Code 在生成代码时就遵守规范从源头减少 review 成本。6.2 编写三个核心 skill第一个是react-component规定组件目录结构、命名、样式方案、测试要求。第二个是api-client规定所有网络请求必须走src/api/下的封装禁止组件内直接 fetch。第三个是test-writer规定测试文件位置、命名、覆盖要求。以api-client为例SKILL.md 核心内容如下--- name: api-client description: 封装 API 请求统一错误处理和类型定义 trigger: - 调用接口 - 请求数据 - src/api/ --- ## 步骤 1. 在 src/api/ 下创建或修改对应模块文件文件名用 camelCase。 2. 每个接口导出为一个函数函数名以 fetch 开头。 3. 请求和响应类型必须显式定义放在同目录的 types.ts。 4. 错误处理统一走 src/api/errorHandler.ts禁止在业务层 try-catch。 5. 所有请求必须带超时配置默认 10 秒。 ## 约束 - 禁止在组件文件里直接写 fetch 或 axios。 - 禁止硬编码 baseURL从环境变量读取。 - 禁止在 API 层写业务逻辑。这三个 skill 写完后我让团队新人用了一周。结果是组件目录结构零偏差API 调用全部走封装测试文件自动生成。Code review 时间从平均 40 分钟降到 15 分钟省下来的时间用来讨论业务边界和性能优化。6.3 效果验证与迭代skill 不是写完就一劳永逸的。我每周会看一次 Claude Code 的生成记录找出它违反约束的情况然后反推 SKILL.md 哪里写得不够明确。比如有一次发现它把测试文件放到了__tests__目录而不是组件同级目录检查后发现是 SKILL.md 里没写清楚路径规则。补上一句“测试文件与组件文件同级”后问题消失。这种迭代过程本身就是 skill 的价值它把团队的隐性知识显性化并且可以持续优化。三个月下来我们的 skill 集合从 3 个扩展到 11 个覆盖了组件、API、测试、文档、提交信息、代码审查等环节。7. 常见问题与排查技巧实录7.1 安装与加载类问题问题现象可能原因解决方法claude命令找不到npm 全局 bin 未加入 PATH用npm config get prefix找到路径加入环境变量skill 不生效SKILL.md frontmatter 格式错误检查 YAML 语法name 用英文小写短横线skill 加载了但行为不对description 太泛导致误触发收窄 description加 trigger 关键词项目 skill 覆盖全局 skill同名冲突重命名其中一个或明确使用场景Windows 用户特别注意热词里提到的“claudes workspace requires the virtual machine platform on windows”这类报错通常和 WSL 或虚拟化环境有关。如果你在 Windows 上用 Claude Code建议直接在 WSL2 里跑避免路径和权限的兼容问题。我试过在纯 Windows 环境下折腾路径分隔符和文件权限经常出幺蛾子换到 WSL2 后一次跑通。7.2 skill 编写类问题问题一skill 太长Claude 加载后反而变慢。原因是 SKILL.md 正文太长占用了大量上下文。解决方法是把详细参考文档拆到单独文件SKILL.md 里只留核心步骤和约束用相对路径引用其他文件。Claude Code 支持按需读取子文件不会一次性全加载。问题二skill 之间互相冲突。比如react-component说用 CSS Modulesstylingskill 说用 Tailwind。解决方法是明确优先级或者在 description 里写清楚适用边界。我的做法是给每个 skill 加一个priority字段数值高的优先。问题三skill 里的脚本执行失败。有些 skill 附带 shell 脚本或 Node 脚本如果脚本依赖的环境变量没配置就会报错。建议在 SKILL.md 里写明依赖项并在脚本开头加环境检查。7.3 独家避坑技巧第一个技巧用claude --debug看 skill 加载日志。这个命令会输出详细的加载过程包括扫描了哪些目录、加载了哪些 skill、跳过了哪些文件。排查问题时比盲猜高效得多。第二个技巧skill 目录用软链接管理。如果你有多个项目共用一套 skill不要复制粘贴用软链接指向同一个源目录。这样改一处所有项目生效。ln -s ~/my-skills/react-component .claude/skills/react-component第三个技巧定期清理不用的 skill。热词里有人问“tibo 关于清理 skills 的方法推荐”说明这是普遍需求。我的做法是每月 review 一次把三个月没触发过的 skill 归档。skill 太多会导致 Claude 启动时扫描变慢而且增加误触发概率。8. 进阶方向把 skills 变成团队资产8.1 skill 的版本管理与协作当 skill 数量超过 10 个就需要版本管理了。我的做法是建一个独立的 Git 仓库专门放 skills每个 skill 一个目录用 tag 标记版本。项目里通过 git submodule 或者软链接引用。这样 skill 的变更可以走 code review 流程避免有人随手改坏。协作方面我建议给每个 skill 配一个OWNER.md写明维护人、适用项目、最近更新日期。新人接手时能快速找到负责人。这个做法是从开源项目学来的在团队内部效果很好。8.2 从 skill 到内部工具链skills 的终极形态是内部工具链的一部分。比如把 skill 和 CI 结合提交代码时自动跑 skill 里定义的检查规则或者把 skill 和文档系统结合SKILL.md 本身就是最好的项目规范文档。我见过一个团队把 skill 做成了 onboarding 工具新人入职第一天装好 Claude Code克隆 skills 仓库然后让 AI 带着他写第一个组件。整个过程不需要老员工手把手教因为规范都写在 skill 里了。这种“自解释”的开发环境才是 skills 机制最大的想象空间。8.3 跨领域迁移数学建模、内容创作、科研热词里“数学建模 skills”“AI 漫剧常用 skills”“codex nature skills”这些词说明 skills 正在向非编程领域渗透。逻辑是一样的把领域内的固定流程和约束写成 SKILL.md让 AI 按套路执行。数学建模场景下一个>