拓冰网站定制 
1. 从“skills”这个热词说起它到底是什么为什么突然火了如果你最近在开发者社区、AI 工具圈或者技术群聊里频繁看到“skills”这个词不用怀疑它已经从一个普通英文单词变成了一个具有特定技术含义的专有概念。简单来说Agent Skills智能体技能是一套让 AI 编程助手具备可复用、可组合、可版本管理的能力模块的机制。你可以把它理解成给 AI 助手装的“插件包”或者“技能卡”——每一张卡定义了一类特定任务的执行逻辑、工具调用方式和上下文约束。这个概念的爆发和 Claude Code 的普及有直接关系。Claude Code 是 Anthropic 推出的命令行 AI 编程工具它本身已经能读写文件、执行命令、搜索代码但面对复杂项目时光靠通用能力是不够的。于是 Skills 机制应运而生你可以在项目里放一个SKILL.md文件告诉 Claude Code 在特定场景下该怎么做、该调用什么工具、该遵循什么规范。这就像给一个新入职的工程师发了一本《项目操作手册》他不用每次从头摸索。那为什么 skills 会突然成为热搜词我观察下来有几个原因。第一AI 编程工具从“能写代码”进入到了“能按规范写代码”的阶段通用能力已经不够用了大家需要定制化。第二Skills 的门槛足够低本质上就是写 Markdown 文件不需要学新语言、不需要编译打包前端开发者、数据科学家、甚至非技术背景的产品经理都能上手。第三社区效应GitHub 上出现了大量开源的 skills 仓库从数学建模到前端开发、从 STM32 嵌入式到 AI 漫剧生成各种场景的 skills 层出不穷形成了一种“技能库”生态。这篇文章面向的读者很明确如果你已经在用 Claude Code、Codex、OpenCode 这类 AI 编程工具但总觉得“它不够懂我的项目”那 skills 就是你要找的答案。如果你还没开始用这些工具也没关系我会从最基础的概念讲起把 skills 的设计思路、编写方法、安装配置、常见坑点全部拆开讲清楚。全文基于我自己的实操经验和社区常见实践不堆砌官方文档的套话只讲能直接抄作业的东西。2. Skills 的核心设计思路为什么是 Markdown而不是代码2.1 用自然语言定义能力降低编写门槛传统上要给 AI 助手扩展能力你得写代码、定义函数签名、注册工具调用接口。这套流程对工程师来说不算难但把大量非核心开发者挡在了门外。Skills 的设计哲学完全不同它用自然语言描述能力用 Markdown 组织内容用文件系统做版本管理。你不需要写一行 Python 或 TypeScript只需要在SKILL.md里用清晰的结构化文字告诉 AI“当用户要求做 X 的时候你应该按 Y 步骤执行注意 Z 事项。”这个选择背后有很实际的考量。AI 模型本身已经具备了强大的自然语言理解能力你用自然语言给它下指令它完全能听懂。与其费劲定义一套形式化的工具接口不如直接把领域知识写成文档让模型自己去理解和执行。这就像你给一个新员工写操作手册你不会用伪代码写而是用他能看懂的语言写清楚步骤和注意事项。当然这并不意味着 skills 就是随便写写。好的 skills 需要精确的触发条件、清晰的步骤拆解、明确的边界约束和可验证的输出标准。我见过太多人写 skills 时犯的一个错误写得太泛比如“帮我优化代码”这种 skill 等于没写因为 AI 不知道什么时候该触发、优化到什么程度算完成。正确的做法是写具体场景比如“当检测到 React 组件中存在未处理的异步状态更新时按以下步骤重构为 useReducer 模式”。2.2 文件系统即技能库天然支持组合与继承Skills 的另一个巧妙设计是用目录结构来组织技能。一个典型的 skills 目录长这样.claude/skills/ frontend-review/ SKILL.md examples/ bad-example.tsx good-example.tsx math-modeling/ SKILL.md templates/ paper-template.md stm32-debug/ SKILL.md reference/ register-map.md这种结构的好处是显而易见的。首先技能可以带附件比如示例代码、模板文件、参考文档AI 在执行 skill 时可以读取这些附件作为上下文。其次技能可以嵌套和组合一个高层 skill 可以引用底层 skill形成技能树。第三版本管理天然友好你把 skills 目录提交到 Git团队成员拉下来就能用更新技能就是提交一个 commit。我自己的项目里就用了这种结构。比如我有一个code-review技能它下面又引用了security-check和performance-check两个子技能。当 Claude Code 执行代码审查时它会先跑安全检查和性能检查再汇总成完整的审查报告。这种组合能力是纯代码方案很难做到的因为代码方案的组合需要显式调用和参数传递而 skills 的组合就是文件引用和自然语言描述灵活得多。2.3 触发机制让 AI 知道“什么时候该用这个技能”Skills 最核心也最容易出问题的地方是触发机制。你写了一个技能但 AI 怎么知道什么时候该用它目前主流的做法是在SKILL.md的头部用 YAML frontmatter 定义触发条件类似这样--- name: react-async-refactor description: 当 React 组件中存在未处理的异步状态更新、竞态条件或内存泄漏风险时触发 triggers: - 异步状态 - race condition - useEffect 清理 - 组件卸载后 setState ---这里的description和triggers就是给 AI 看的“触发信号”。当用户的请求或代码上下文匹配到这些信号时AI 就会加载对应的 skill。实测下来触发条件写得越具体误触发和漏触发的概率越低。我建议 triggers 里至少包含三类信息问题特征如“竞态条件”、代码模式如“useEffect 中没有 cleanup”、用户可能的表述如“这个组件好像有内存泄漏”。还有一个经验不要在一个 skill 里塞太多触发条件。我见过有人写了一个“万能前端技能”triggers 列了二十几条结果 AI 每次都在纠结要不要触发反而降低了效率。正确的做法是按场景拆分一个 skill 只解决一类问题触发条件控制在 3 到 5 条。3. 手把手写一个可用的 SKILL.md从零到能跑3.1 最小可用结构五段式模板写SKILL.md不需要复杂的格式但有几个关键段落是必须的。我总结了一个五段式模板经过多个项目验证基本能覆盖大部分场景--- name: skill-name description: 一句话说明这个技能解决什么问题 triggers: - 触发词1 - 触发词2 --- ## 适用场景 描述什么情况下应该使用这个技能什么情况下不应该使用。 ## 执行步骤 1. 第一步做什么 2. 第二步做什么 3. 第三步做什么 ## 注意事项 - 注意点1 - 注意点2 ## 输出要求 描述执行完成后应该输出什么格式的结果。这个模板看起来简单但每一段都有讲究。“适用场景”决定了 AI 的触发边界“执行步骤”是核心逻辑“注意事项”是避坑指南“输出要求”保证结果可验证。我建议新手先从这五段开始写写熟了再根据具体需求扩展。3.2 触发条件怎么写才精准三个实操技巧触发条件是 skills 的“开关”写不好就会出现两种情况要么 AI 该用的时候不用要么不该用的时候乱用。我踩过的坑包括触发词太泛比如只写“优化”导致 AI 在任何优化场景都触发触发词太窄比如写了一个特定函数名换个项目就失效。第一个技巧是用“问题特征 代码模式”组合触发。比如不要只写“性能问题”而是写“检测到列表渲染超过 100 项且没有虚拟化”加上“用户提到卡顿”。这样 AI 需要同时满足两个条件才触发精准度大幅提升。第二个技巧是在 description 里写清楚“不适用场景”。比如“这个技能不适用于服务端渲染场景”这样 AI 在判断时会主动排除。很多人只写适用场景不写排除场景结果 AI 在边缘情况下乱触发。第三个技巧是用 examples 目录做负样本。在 skill 目录下放一个examples/not-applicable/文件夹里面放一些不应该触发这个技能的代码示例。AI 在判断时会参考这些负样本效果比纯文字描述好得多。这个技巧是我从社区里学来的实测下来误触发率降低了大概一半。3.3 执行步骤的颗粒度太粗没用太细累赘执行步骤是 skill 的主体但颗粒度很难把握。写得太粗比如“重构代码使其更健壮”等于没说写得太细比如“在第 3 行和第 4 行之间插入一个空行”又太死板换个项目就废了。我的经验是按“决策点”来拆分步骤。每个步骤应该是一个需要 AI 做判断的节点而不是一个机械操作。比如## 执行步骤 1. 扫描目标文件中所有的 useEffect 调用识别出没有 cleanup 函数的那些。 2. 对每个有问题的 useEffect判断它是否涉及异步操作。如果是进入步骤 3如果不是进入步骤 4。 3. 对于涉及异步操作的 useEffect检查是否存在竞态条件风险。如果存在添加 AbortController 或取消标志。 4. 对于不涉及异步操作的 useEffect检查是否有事件监听器或定时器需要清理。如果有添加对应的 cleanup 函数。 5. 运行类型检查和 lint确认修改没有引入新错误。这种写法既给了 AI 明确的执行路径又保留了判断空间。AI 不需要你告诉它每一行代码怎么改它只需要知道“在什么情况下做什么决策”。这才是 skills 的正确用法。4. 安装与配置Claude Code、VS Code 和常见环境问题4.1 Claude Code 的安装与 skills 目录配置Claude Code 目前主要通过 npm 安装命令是npm install -g anthropic-ai/claude-code。安装完成后在项目根目录运行claude就能启动。Skills 的默认加载路径是项目根目录下的.claude/skills/你也可以通过环境变量CLAUDE_SKILLS_PATH指定其他路径。这里有一个很多人会踩的坑Windows 环境下需要启用虚拟机平台。如果你在 Windows 上运行 Claude Code 时看到“requires the virtual machine platform”的提示需要去“启用或关闭 Windows 功能”里勾选“虚拟机平台”和“适用于 Linux 的 Windows 子系统”然后重启。这个提示和 skills 本身没关系是 Claude Code 的运行时依赖但很多新手会卡在这里。另一个常见问题是PowerShell 里提示“无法将‘claude’项识别为 cmdlet”。这通常是 npm 全局安装路径没有加到 PATH 里。你可以用npm config get prefix查看全局安装路径然后把这个路径加到系统环境变量里。如果用的是 nvm 管理 Node 版本每次切换版本后可能需要重新确认 PATH。4.2 VS Code 集成让 skills 在编辑器里生效VS Code 里用 Claude Code 有两种方式。一种是直接用集成终端运行claude这种方式最简单skills 的加载和命令行完全一致。另一种是安装 Claude Code 的 VS Code 扩展在编辑器内直接调用。扩展方式的好处是可以在编辑器里直接看到 AI 的修改建议不用来回切换窗口。配置扩展时需要注意skills 目录必须在工作区根目录下。如果你用的是多根工作区multi-root workspace每个根目录下的.claude/skills/会被分别加载。这个设计有利有弊好处是不同项目的技能互不干扰坏处是如果你想共享一套通用技能需要在每个项目里都放一份。我的做法是把通用技能放在一个单独的仓库里然后用符号链接symlink链接到各个项目这样更新一处就能全局生效。4.3 从 GitHub 手动安装社区 skills社区里有很多高质量的 skills 仓库比如typesafe-ai/skills、superpower-skills等。手动安装的步骤一般是# 克隆仓库到临时目录 git clone https://github.com/example/skills-repo.git /tmp/skills-repo # 复制需要的技能到项目目录 cp -r /tmp/skills-repo/skills/frontend-review .claude/skills/ # 清理临时目录 rm -rf /tmp/skills-repo这里有个细节复制之前先看一下 skill 的依赖。有些 skill 依赖特定的工具或环境变量比如需要安装eslint或者设置OPENAI_API_KEY。直接复制过来但不配置依赖运行时就会报错。我建议在复制之前先读一遍SKILL.md的“前置条件”部分如果有的话确认环境满足再安装。还有一个经验不要一次性安装太多 skills。我刚开始用的时候从社区里一口气装了二十多个 skills结果 AI 每次启动都要加载所有技能描述响应速度明显变慢而且触发冲突的概率大增。后来我精简到只保留项目真正需要的五六个体验好了很多。建议按需安装用完就删。5. 实战场景skills 在不同领域的落地案例5.1 前端开发组件审查与性能优化前端是 skills 应用最成熟的领域之一。我自己的 React 项目里有一个component-review技能专门用来审查组件代码。它的触发条件是“用户要求审查组件”或者“检测到组件文件被修改”。执行步骤包括检查 props 类型定义、检查 useEffect 依赖数组、检查是否有不必要的重渲染、检查事件处理函数是否用了 useCallback。这个技能最实用的地方是它带了一套示例代码。在examples/目录下我放了bad-patterns.tsx和good-patterns.tsx两个文件里面覆盖了十几种常见的前端反模式。AI 在审查时会参考这些示例判断当前代码是否匹配反模式。实测下来这种“示例驱动”的方式比纯文字描述准确得多尤其是对于“什么样的代码算坏味道”这种主观判断。另一个前端场景是样式规范检查。我写了一个style-guard技能规定项目里必须用 CSS Modules 而不是全局样式必须用设计系统的颜色变量而不是硬编码色值。这个技能会在 AI 生成新组件时自动触发确保新代码符合规范。这比人工 review 效率高多了而且不会漏。5.2 数学建模从选题到论文的流程化技能数学建模比赛是 skills 的一个意外热门场景。我帮几个参加华为杯的朋友搭过一套建模 skills效果出乎意料地好。核心思路是把建模流程拆成几个阶段每个阶段一个 skillproblem-analysis读题、提取关键信息、判断题型优化、预测、评价等model-selection根据题型推荐模型库比如优化问题推荐线性规划、遗传算法、模拟退火code-implementation按选定模型生成 Python 代码包含数据预处理、模型训练、结果可视化paper-writing按竞赛论文格式生成摘要、问题重述、模型假设、符号说明、模型建立与求解这套 skills 的关键在于阶段之间的衔接。每个 skill 的输出格式都定义得很清楚下一个 skill 能直接读取上一个的输出。比如problem-analysis的输出是一个结构化的 JSON包含题型、约束条件、目标函数model-selection读取这个 JSON 后推荐模型。这种流水线式的设计让整个建模过程变得可管理不会出现“写到一半不知道下一步干什么”的情况。5.3 嵌入式开发STM32 调试与寄存器配置嵌入式场景对 skills 的要求更高因为涉及硬件寄存器和时序。我做过一个stm32-gpio-config技能用来生成 GPIO 初始化代码。它的核心是一张寄存器映射表放在reference/register-map.md里。AI 在生成代码时会查这张表确保寄存器地址和位定义正确。这个技能的一个关键设计是强制检查时钟使能。STM32 的 GPIO 配置必须先使能对应端口的时钟否则配置不生效。很多新手会忘记这一步导致调试半天找不到问题。我在 skill 里加了一条硬性规则“生成任何 GPIO 配置代码前必须先输出时钟使能代码并确认 RCC 寄存器地址正确。”这条规则帮我省了很多调试时间。另一个嵌入式场景是中断优先级配置。我写了一个nvic-priority技能根据 Cortex-M 的优先级分组规则自动计算 NVIC 优先级值。这个技能里包含了一个优先级分组表AI 会根据用户选择的分组模式如 Group 2自动计算抢占优先级和子优先级的位分配。这种计算如果手动做很容易出错交给 skill 处理就稳多了。5.4 AI 漫剧与内容生成创意类 skills 的写法AI 漫剧是最近兴起的一个方向用 AI 生成漫画风格的连续剧集。这个场景的 skills 和编程类完全不同它更侧重风格一致性和叙事连贯性。我试过写一个comic-panel技能用来生成分镜描述。它的触发条件是“用户要求生成漫剧分镜”执行步骤包括读取角色设定文件、读取上一集剧情摘要、生成当前分镜的文本描述和画面提示词。这个技能的核心是角色一致性检查。在reference/characters.md里定义每个角色的外貌特征、服装、性格关键词。AI 在生成分镜时会检查每个角色的描述是否和设定一致如果发现偏差就自动修正。这个检查步骤是必须的因为 AI 生成内容时很容易“忘记”之前的设定导致角色形象前后不一致。创意类 skills 的另一个经验是用“情绪曲线”控制叙事节奏。我在 skill 里定义了一个简单的情绪值范围1 到 10要求 AI 在生成每一集时标注情绪值并确保整季的情绪曲线有起伏。这个技巧是从编剧理论里借来的用在 AI 内容生成上效果很好能避免剧情平淡。6. 常见问题与排查技巧实录6.1 技能不触发或误触发排查清单技能不触发是最常见的问题。我整理了一个排查清单按优先级排序问题现象可能原因排查方法完全不触发skills 目录路径不对确认.claude/skills/在项目根目录下完全不触发SKILL.md 格式错误检查 YAML frontmatter 是否有语法错误偶尔触发触发词太泛或太窄调整 triggers增加问题特征描述误触发缺少排除条件在 description 里补充“不适用场景”触发冲突多个 skill 触发条件重叠精简 skills合并相似技能还有一个隐蔽的问题文件编码。我有一次在 Windows 上写 SKILL.md保存成了 GBK 编码结果 Claude Code 读取时乱码技能完全不触发。后来统一用 UTF-8 编码就好了。这个坑很隐蔽因为文件在编辑器里看起来是正常的只有 AI 读取时才出问题。6.2 技能执行结果不符合预期三个调整方向技能触发了但执行结果不对通常有三个调整方向。第一是步骤不够具体AI 不知道具体怎么做。比如“优化代码”改成“将嵌套的 if-else 重构为早返回模式”。第二是缺少示例AI 对“好”的标准理解不一致。在 examples 目录里放正反示例效果立竿见影。第三是输出格式没定义AI 输出的结果没法用。在 SKILL.md 里明确输出格式比如“输出一个 JSON包含 filename、line、issue、suggestion 四个字段”。我自己的经验是大部分执行问题都可以通过加示例解决。文字描述有歧义但示例代码没有歧义。如果一个 skill 执行结果不稳定第一件事就是去加示例通常加两三个正例和两三个反例问题就解决了。6.3 性能问题skills 太多导致响应变慢Skills 太多会拖慢 AI 的响应速度因为每次请求都要加载和匹配所有技能描述。我的实测数据是5 个 skills 以内基本无感10 个以上开始有可感知的延迟20 个以上延迟明显。所以控制 skills 数量是性能优化的第一要务。具体做法是按项目阶段拆分 skills比如开发阶段只加载开发相关的部署阶段只加载部署相关的。Claude Code 支持通过命令行参数指定 skills 路径你可以为不同阶段准备不同的 skills 目录。另一个做法是合并相似技能把三个小的代码审查技能合并成一个大的用内部条件分支来处理不同情况。还有一个技巧是用description字段做懒加载。Claude Code 会先读取所有 skill 的 description只有当 description 匹配当前上下文时才加载完整的 SKILL.md。所以 description 要写得精准但简短既能被匹配到又不会占用太多上下文窗口。6.4 跨平台兼容性Windows、macOS 和 Linux 的差异Skills 本身是纯文本文件跨平台没问题但执行环境有差异。Windows 上路径分隔符是反斜杠macOS 和 Linux 是正斜杠。如果你的 skill 里包含路径操作建议用相对路径或者让 AI 自己处理路径分隔符。我在 skill 里写路径时统一用正斜杠Claude Code 在 Windows 上也能正确识别。另一个差异是命令行工具。有些 skill 依赖grep、sed、awk这些 Unix 工具在 Windows 上默认没有。如果你的团队有 Windows 用户要么在 skill 里注明依赖要么改用跨平台的工具比如用 Node.js 脚本代替 shell 命令。我自己的做法是尽量不依赖外部命令能用 AI 自身能力完成的就不调工具。7. 进阶技巧让 skills 真正成为团队资产7.1 版本管理与团队协作Skills 最大的价值在于可复用和可传承。一个人写好的 skill全团队都能用而且随着使用不断迭代优化。我建议把 skills 目录纳入 Git 管理和代码一起提交。每次修改 skill 都走正常的 code review 流程确保质量。团队协作时有一个经验给每个 skill 指定一个 owner。Owner 负责维护这个 skill 的准确性和时效性其他人发现问题时找 owner 反馈。没有 owner 的 skill 很容易腐烂因为没人对它的质量负责。我们团队的做法是在 SKILL.md 的 frontmatter 里加一个owner字段写明负责人。另一个做法是建立 skill 的测试用例。在 skill 目录下放一个tests/文件夹里面放一些输入输出对。每次修改 skill 后手动跑一遍测试用例确认行为没有退化。这个做法看起来麻烦但对于核心 skill 来说非常值得能避免“改了一个地方坏了另一个地方”的问题。7.2 技能组合与流水线设计单个 skill 的能力有限真正的威力在于组合。我设计过一条完整的代码审查流水线security-check→performance-check→style-check→summary-report。每个 skill 负责一个维度最后一个 skill 汇总所有发现生成统一的审查报告。组合的关键是定义清楚 skill 之间的接口。每个 skill 的输出格式要统一下一个 skill 才能正确读取。我通常用 JSON 作为中间格式因为结构清晰、易于解析。比如security-check输出一个 JSON 数组每个元素包含file、line、severity、descriptionsummary-report读取这个数组按严重程度分组生成 Markdown 报告。流水线设计还有一个好处是可以并行执行。security-check和performance-check互不依赖可以同时跑最后汇总。Claude Code 目前不支持真正的并行执行但你可以通过分步调用来模拟先跑安全检查再跑性能检查最后汇总。虽然串行执行慢一点但结果是一样的。7.3 从社区 skills 中学习设计模式社区里的开源 skills 是很好的学习材料。我分析过几十个热门 skills总结出几个常见的设计模式。模板模式skill 里包含一个输出模板AI 按模板填充内容适合报告生成类场景。检查清单模式skill 里列出一系列检查项AI 逐项检查并标记通过或失败适合代码审查类场景。决策树模式skill 里定义一系列判断条件AI 根据条件走不同分支适合问题诊断类场景。学习这些模式的最好方式是读别人的 SKILL.md然后自己改写一遍。不要直接复制因为每个项目的需求不同。我通常会把社区 skill 下载下来读一遍理解它的设计思路然后根据自己的项目特点重写。这个过程本身就是很好的学习写几个之后就能形成自己的风格。8. 我踩过的坑和最后分享的几个技巧先说几个我踩过的坑。第一个是在 skill 里写死具体路径比如/Users/xxx/project/src/结果换台机器就失效了。后来改成相对路径或者用环境变量问题解决。第二个是skill 的触发条件写得太“聪明”用了一些复杂的正则表达式结果 AI 理解不了反而不触发。后来改成简单的关键词匹配效果好多了。第三个是一次性改太多一个 skill 里塞了十几个步骤AI 执行到一半就乱了。后来拆成多个小 skill每个只做一件事稳定性大幅提升。再分享几个实用技巧。技巧一用examples/目录做“少样本学习”。在 skill 目录下放几个输入输出示例AI 会参考这些示例来理解你的意图。这个技巧对格式要求高的 skill 特别有效比如报告生成、代码重构。技巧二在 SKILL.md 里加一个“常见错误”段落列出这个 skill 容易犯的错误和避免方法。AI 读到这些会主动规避效果比事后纠正要好。技巧三定期清理不再使用的 skills。我每个月会 review 一次 skills 目录把三个月没用过的删掉或者归档。保持 skills 库的精简对性能和可维护性都有好处。最后说一个我个人的体会skills 的价值不在于数量而在于质量。一个精心设计的 skill能顶十个随便写的。我见过有人收集了几百个 skills但真正用的就那几个。与其追求“技能库”的规模不如把常用的几个场景做深做透。我现在项目里只保留了六个 skills但每一个都经过多次迭代触发精准、执行稳定、输出可靠。这比什么都强。 Agent Skills 实战指南：用 Markdown 为 AI 编程助手定制可复用技能
1. 从“skills”这个热词说起它到底是什么为什么突然火了如果你最近在开发者社区、AI 工具圈或者技术群聊里频繁看到“skills”这个词不用怀疑它已经从一个普通英文单词变成了一个具有特定技术含义的专有概念。简单来说Agent Skills智能体技能是一套让 AI 编程助手具备可复用、可组合、可版本管理的能力模块的机制。你可以把它理解成给 AI 助手装的“插件包”或者“技能卡”——每一张卡定义了一类特定任务的执行逻辑、工具调用方式和上下文约束。这个概念的爆发和 Claude Code 的普及有直接关系。Claude Code 是 Anthropic 推出的命令行 AI 编程工具它本身已经能读写文件、执行命令、搜索代码但面对复杂项目时光靠通用能力是不够的。于是 Skills 机制应运而生你可以在项目里放一个SKILL.md文件告诉 Claude Code 在特定场景下该怎么做、该调用什么工具、该遵循什么规范。这就像给一个新入职的工程师发了一本《项目操作手册》他不用每次从头摸索。那为什么 skills 会突然成为热搜词我观察下来有几个原因。第一AI 编程工具从“能写代码”进入到了“能按规范写代码”的阶段通用能力已经不够用了大家需要定制化。第二Skills 的门槛足够低本质上就是写 Markdown 文件不需要学新语言、不需要编译打包前端开发者、数据科学家、甚至非技术背景的产品经理都能上手。第三社区效应GitHub 上出现了大量开源的 skills 仓库从数学建模到前端开发、从 STM32 嵌入式到 AI 漫剧生成各种场景的 skills 层出不穷形成了一种“技能库”生态。这篇文章面向的读者很明确如果你已经在用 Claude Code、Codex、OpenCode 这类 AI 编程工具但总觉得“它不够懂我的项目”那 skills 就是你要找的答案。如果你还没开始用这些工具也没关系我会从最基础的概念讲起把 skills 的设计思路、编写方法、安装配置、常见坑点全部拆开讲清楚。全文基于我自己的实操经验和社区常见实践不堆砌官方文档的套话只讲能直接抄作业的东西。2. Skills 的核心设计思路为什么是 Markdown而不是代码2.1 用自然语言定义能力降低编写门槛传统上要给 AI 助手扩展能力你得写代码、定义函数签名、注册工具调用接口。这套流程对工程师来说不算难但把大量非核心开发者挡在了门外。Skills 的设计哲学完全不同它用自然语言描述能力用 Markdown 组织内容用文件系统做版本管理。你不需要写一行 Python 或 TypeScript只需要在SKILL.md里用清晰的结构化文字告诉 AI“当用户要求做 X 的时候你应该按 Y 步骤执行注意 Z 事项。”这个选择背后有很实际的考量。AI 模型本身已经具备了强大的自然语言理解能力你用自然语言给它下指令它完全能听懂。与其费劲定义一套形式化的工具接口不如直接把领域知识写成文档让模型自己去理解和执行。这就像你给一个新员工写操作手册你不会用伪代码写而是用他能看懂的语言写清楚步骤和注意事项。当然这并不意味着 skills 就是随便写写。好的 skills 需要精确的触发条件、清晰的步骤拆解、明确的边界约束和可验证的输出标准。我见过太多人写 skills 时犯的一个错误写得太泛比如“帮我优化代码”这种 skill 等于没写因为 AI 不知道什么时候该触发、优化到什么程度算完成。正确的做法是写具体场景比如“当检测到 React 组件中存在未处理的异步状态更新时按以下步骤重构为 useReducer 模式”。2.2 文件系统即技能库天然支持组合与继承Skills 的另一个巧妙设计是用目录结构来组织技能。一个典型的 skills 目录长这样.claude/skills/ frontend-review/ SKILL.md examples/ bad-example.tsx good-example.tsx math-modeling/ SKILL.md templates/ paper-template.md stm32-debug/ SKILL.md reference/ register-map.md这种结构的好处是显而易见的。首先技能可以带附件比如示例代码、模板文件、参考文档AI 在执行 skill 时可以读取这些附件作为上下文。其次技能可以嵌套和组合一个高层 skill 可以引用底层 skill形成技能树。第三版本管理天然友好你把 skills 目录提交到 Git团队成员拉下来就能用更新技能就是提交一个 commit。我自己的项目里就用了这种结构。比如我有一个code-review技能它下面又引用了security-check和performance-check两个子技能。当 Claude Code 执行代码审查时它会先跑安全检查和性能检查再汇总成完整的审查报告。这种组合能力是纯代码方案很难做到的因为代码方案的组合需要显式调用和参数传递而 skills 的组合就是文件引用和自然语言描述灵活得多。2.3 触发机制让 AI 知道“什么时候该用这个技能”Skills 最核心也最容易出问题的地方是触发机制。你写了一个技能但 AI 怎么知道什么时候该用它目前主流的做法是在SKILL.md的头部用 YAML frontmatter 定义触发条件类似这样--- name: react-async-refactor description: 当 React 组件中存在未处理的异步状态更新、竞态条件或内存泄漏风险时触发 triggers: - 异步状态 - race condition - useEffect 清理 - 组件卸载后 setState ---这里的description和triggers就是给 AI 看的“触发信号”。当用户的请求或代码上下文匹配到这些信号时AI 就会加载对应的 skill。实测下来触发条件写得越具体误触发和漏触发的概率越低。我建议 triggers 里至少包含三类信息问题特征如“竞态条件”、代码模式如“useEffect 中没有 cleanup”、用户可能的表述如“这个组件好像有内存泄漏”。还有一个经验不要在一个 skill 里塞太多触发条件。我见过有人写了一个“万能前端技能”triggers 列了二十几条结果 AI 每次都在纠结要不要触发反而降低了效率。正确的做法是按场景拆分一个 skill 只解决一类问题触发条件控制在 3 到 5 条。3. 手把手写一个可用的 SKILL.md从零到能跑3.1 最小可用结构五段式模板写SKILL.md不需要复杂的格式但有几个关键段落是必须的。我总结了一个五段式模板经过多个项目验证基本能覆盖大部分场景--- name: skill-name description: 一句话说明这个技能解决什么问题 triggers: - 触发词1 - 触发词2 --- ## 适用场景 描述什么情况下应该使用这个技能什么情况下不应该使用。 ## 执行步骤 1. 第一步做什么 2. 第二步做什么 3. 第三步做什么 ## 注意事项 - 注意点1 - 注意点2 ## 输出要求 描述执行完成后应该输出什么格式的结果。这个模板看起来简单但每一段都有讲究。“适用场景”决定了 AI 的触发边界“执行步骤”是核心逻辑“注意事项”是避坑指南“输出要求”保证结果可验证。我建议新手先从这五段开始写写熟了再根据具体需求扩展。3.2 触发条件怎么写才精准三个实操技巧触发条件是 skills 的“开关”写不好就会出现两种情况要么 AI 该用的时候不用要么不该用的时候乱用。我踩过的坑包括触发词太泛比如只写“优化”导致 AI 在任何优化场景都触发触发词太窄比如写了一个特定函数名换个项目就失效。第一个技巧是用“问题特征 代码模式”组合触发。比如不要只写“性能问题”而是写“检测到列表渲染超过 100 项且没有虚拟化”加上“用户提到卡顿”。这样 AI 需要同时满足两个条件才触发精准度大幅提升。第二个技巧是在 description 里写清楚“不适用场景”。比如“这个技能不适用于服务端渲染场景”这样 AI 在判断时会主动排除。很多人只写适用场景不写排除场景结果 AI 在边缘情况下乱触发。第三个技巧是用 examples 目录做负样本。在 skill 目录下放一个examples/not-applicable/文件夹里面放一些不应该触发这个技能的代码示例。AI 在判断时会参考这些负样本效果比纯文字描述好得多。这个技巧是我从社区里学来的实测下来误触发率降低了大概一半。3.3 执行步骤的颗粒度太粗没用太细累赘执行步骤是 skill 的主体但颗粒度很难把握。写得太粗比如“重构代码使其更健壮”等于没说写得太细比如“在第 3 行和第 4 行之间插入一个空行”又太死板换个项目就废了。我的经验是按“决策点”来拆分步骤。每个步骤应该是一个需要 AI 做判断的节点而不是一个机械操作。比如## 执行步骤 1. 扫描目标文件中所有的 useEffect 调用识别出没有 cleanup 函数的那些。 2. 对每个有问题的 useEffect判断它是否涉及异步操作。如果是进入步骤 3如果不是进入步骤 4。 3. 对于涉及异步操作的 useEffect检查是否存在竞态条件风险。如果存在添加 AbortController 或取消标志。 4. 对于不涉及异步操作的 useEffect检查是否有事件监听器或定时器需要清理。如果有添加对应的 cleanup 函数。 5. 运行类型检查和 lint确认修改没有引入新错误。这种写法既给了 AI 明确的执行路径又保留了判断空间。AI 不需要你告诉它每一行代码怎么改它只需要知道“在什么情况下做什么决策”。这才是 skills 的正确用法。4. 安装与配置Claude Code、VS Code 和常见环境问题4.1 Claude Code 的安装与 skills 目录配置Claude Code 目前主要通过 npm 安装命令是npm install -g anthropic-ai/claude-code。安装完成后在项目根目录运行claude就能启动。Skills 的默认加载路径是项目根目录下的.claude/skills/你也可以通过环境变量CLAUDE_SKILLS_PATH指定其他路径。这里有一个很多人会踩的坑Windows 环境下需要启用虚拟机平台。如果你在 Windows 上运行 Claude Code 时看到“requires the virtual machine platform”的提示需要去“启用或关闭 Windows 功能”里勾选“虚拟机平台”和“适用于 Linux 的 Windows 子系统”然后重启。这个提示和 skills 本身没关系是 Claude Code 的运行时依赖但很多新手会卡在这里。另一个常见问题是PowerShell 里提示“无法将‘claude’项识别为 cmdlet”。这通常是 npm 全局安装路径没有加到 PATH 里。你可以用npm config get prefix查看全局安装路径然后把这个路径加到系统环境变量里。如果用的是 nvm 管理 Node 版本每次切换版本后可能需要重新确认 PATH。4.2 VS Code 集成让 skills 在编辑器里生效VS Code 里用 Claude Code 有两种方式。一种是直接用集成终端运行claude这种方式最简单skills 的加载和命令行完全一致。另一种是安装 Claude Code 的 VS Code 扩展在编辑器内直接调用。扩展方式的好处是可以在编辑器里直接看到 AI 的修改建议不用来回切换窗口。配置扩展时需要注意skills 目录必须在工作区根目录下。如果你用的是多根工作区multi-root workspace每个根目录下的.claude/skills/会被分别加载。这个设计有利有弊好处是不同项目的技能互不干扰坏处是如果你想共享一套通用技能需要在每个项目里都放一份。我的做法是把通用技能放在一个单独的仓库里然后用符号链接symlink链接到各个项目这样更新一处就能全局生效。4.3 从 GitHub 手动安装社区 skills社区里有很多高质量的 skills 仓库比如typesafe-ai/skills、superpower-skills等。手动安装的步骤一般是# 克隆仓库到临时目录 git clone https://github.com/example/skills-repo.git /tmp/skills-repo # 复制需要的技能到项目目录 cp -r /tmp/skills-repo/skills/frontend-review .claude/skills/ # 清理临时目录 rm -rf /tmp/skills-repo这里有个细节复制之前先看一下 skill 的依赖。有些 skill 依赖特定的工具或环境变量比如需要安装eslint或者设置OPENAI_API_KEY。直接复制过来但不配置依赖运行时就会报错。我建议在复制之前先读一遍SKILL.md的“前置条件”部分如果有的话确认环境满足再安装。还有一个经验不要一次性安装太多 skills。我刚开始用的时候从社区里一口气装了二十多个 skills结果 AI 每次启动都要加载所有技能描述响应速度明显变慢而且触发冲突的概率大增。后来我精简到只保留项目真正需要的五六个体验好了很多。建议按需安装用完就删。5. 实战场景skills 在不同领域的落地案例5.1 前端开发组件审查与性能优化前端是 skills 应用最成熟的领域之一。我自己的 React 项目里有一个component-review技能专门用来审查组件代码。它的触发条件是“用户要求审查组件”或者“检测到组件文件被修改”。执行步骤包括检查 props 类型定义、检查 useEffect 依赖数组、检查是否有不必要的重渲染、检查事件处理函数是否用了 useCallback。这个技能最实用的地方是它带了一套示例代码。在examples/目录下我放了bad-patterns.tsx和good-patterns.tsx两个文件里面覆盖了十几种常见的前端反模式。AI 在审查时会参考这些示例判断当前代码是否匹配反模式。实测下来这种“示例驱动”的方式比纯文字描述准确得多尤其是对于“什么样的代码算坏味道”这种主观判断。另一个前端场景是样式规范检查。我写了一个style-guard技能规定项目里必须用 CSS Modules 而不是全局样式必须用设计系统的颜色变量而不是硬编码色值。这个技能会在 AI 生成新组件时自动触发确保新代码符合规范。这比人工 review 效率高多了而且不会漏。5.2 数学建模从选题到论文的流程化技能数学建模比赛是 skills 的一个意外热门场景。我帮几个参加华为杯的朋友搭过一套建模 skills效果出乎意料地好。核心思路是把建模流程拆成几个阶段每个阶段一个 skillproblem-analysis读题、提取关键信息、判断题型优化、预测、评价等model-selection根据题型推荐模型库比如优化问题推荐线性规划、遗传算法、模拟退火code-implementation按选定模型生成 Python 代码包含数据预处理、模型训练、结果可视化paper-writing按竞赛论文格式生成摘要、问题重述、模型假设、符号说明、模型建立与求解这套 skills 的关键在于阶段之间的衔接。每个 skill 的输出格式都定义得很清楚下一个 skill 能直接读取上一个的输出。比如problem-analysis的输出是一个结构化的 JSON包含题型、约束条件、目标函数model-selection读取这个 JSON 后推荐模型。这种流水线式的设计让整个建模过程变得可管理不会出现“写到一半不知道下一步干什么”的情况。5.3 嵌入式开发STM32 调试与寄存器配置嵌入式场景对 skills 的要求更高因为涉及硬件寄存器和时序。我做过一个stm32-gpio-config技能用来生成 GPIO 初始化代码。它的核心是一张寄存器映射表放在reference/register-map.md里。AI 在生成代码时会查这张表确保寄存器地址和位定义正确。这个技能的一个关键设计是强制检查时钟使能。STM32 的 GPIO 配置必须先使能对应端口的时钟否则配置不生效。很多新手会忘记这一步导致调试半天找不到问题。我在 skill 里加了一条硬性规则“生成任何 GPIO 配置代码前必须先输出时钟使能代码并确认 RCC 寄存器地址正确。”这条规则帮我省了很多调试时间。另一个嵌入式场景是中断优先级配置。我写了一个nvic-priority技能根据 Cortex-M 的优先级分组规则自动计算 NVIC 优先级值。这个技能里包含了一个优先级分组表AI 会根据用户选择的分组模式如 Group 2自动计算抢占优先级和子优先级的位分配。这种计算如果手动做很容易出错交给 skill 处理就稳多了。5.4 AI 漫剧与内容生成创意类 skills 的写法AI 漫剧是最近兴起的一个方向用 AI 生成漫画风格的连续剧集。这个场景的 skills 和编程类完全不同它更侧重风格一致性和叙事连贯性。我试过写一个comic-panel技能用来生成分镜描述。它的触发条件是“用户要求生成漫剧分镜”执行步骤包括读取角色设定文件、读取上一集剧情摘要、生成当前分镜的文本描述和画面提示词。这个技能的核心是角色一致性检查。在reference/characters.md里定义每个角色的外貌特征、服装、性格关键词。AI 在生成分镜时会检查每个角色的描述是否和设定一致如果发现偏差就自动修正。这个检查步骤是必须的因为 AI 生成内容时很容易“忘记”之前的设定导致角色形象前后不一致。创意类 skills 的另一个经验是用“情绪曲线”控制叙事节奏。我在 skill 里定义了一个简单的情绪值范围1 到 10要求 AI 在生成每一集时标注情绪值并确保整季的情绪曲线有起伏。这个技巧是从编剧理论里借来的用在 AI 内容生成上效果很好能避免剧情平淡。6. 常见问题与排查技巧实录6.1 技能不触发或误触发排查清单技能不触发是最常见的问题。我整理了一个排查清单按优先级排序问题现象可能原因排查方法完全不触发skills 目录路径不对确认.claude/skills/在项目根目录下完全不触发SKILL.md 格式错误检查 YAML frontmatter 是否有语法错误偶尔触发触发词太泛或太窄调整 triggers增加问题特征描述误触发缺少排除条件在 description 里补充“不适用场景”触发冲突多个 skill 触发条件重叠精简 skills合并相似技能还有一个隐蔽的问题文件编码。我有一次在 Windows 上写 SKILL.md保存成了 GBK 编码结果 Claude Code 读取时乱码技能完全不触发。后来统一用 UTF-8 编码就好了。这个坑很隐蔽因为文件在编辑器里看起来是正常的只有 AI 读取时才出问题。6.2 技能执行结果不符合预期三个调整方向技能触发了但执行结果不对通常有三个调整方向。第一是步骤不够具体AI 不知道具体怎么做。比如“优化代码”改成“将嵌套的 if-else 重构为早返回模式”。第二是缺少示例AI 对“好”的标准理解不一致。在 examples 目录里放正反示例效果立竿见影。第三是输出格式没定义AI 输出的结果没法用。在 SKILL.md 里明确输出格式比如“输出一个 JSON包含 filename、line、issue、suggestion 四个字段”。我自己的经验是大部分执行问题都可以通过加示例解决。文字描述有歧义但示例代码没有歧义。如果一个 skill 执行结果不稳定第一件事就是去加示例通常加两三个正例和两三个反例问题就解决了。6.3 性能问题skills 太多导致响应变慢Skills 太多会拖慢 AI 的响应速度因为每次请求都要加载和匹配所有技能描述。我的实测数据是5 个 skills 以内基本无感10 个以上开始有可感知的延迟20 个以上延迟明显。所以控制 skills 数量是性能优化的第一要务。具体做法是按项目阶段拆分 skills比如开发阶段只加载开发相关的部署阶段只加载部署相关的。Claude Code 支持通过命令行参数指定 skills 路径你可以为不同阶段准备不同的 skills 目录。另一个做法是合并相似技能把三个小的代码审查技能合并成一个大的用内部条件分支来处理不同情况。还有一个技巧是用description字段做懒加载。Claude Code 会先读取所有 skill 的 description只有当 description 匹配当前上下文时才加载完整的 SKILL.md。所以 description 要写得精准但简短既能被匹配到又不会占用太多上下文窗口。6.4 跨平台兼容性Windows、macOS 和 Linux 的差异Skills 本身是纯文本文件跨平台没问题但执行环境有差异。Windows 上路径分隔符是反斜杠macOS 和 Linux 是正斜杠。如果你的 skill 里包含路径操作建议用相对路径或者让 AI 自己处理路径分隔符。我在 skill 里写路径时统一用正斜杠Claude Code 在 Windows 上也能正确识别。另一个差异是命令行工具。有些 skill 依赖grep、sed、awk这些 Unix 工具在 Windows 上默认没有。如果你的团队有 Windows 用户要么在 skill 里注明依赖要么改用跨平台的工具比如用 Node.js 脚本代替 shell 命令。我自己的做法是尽量不依赖外部命令能用 AI 自身能力完成的就不调工具。7. 进阶技巧让 skills 真正成为团队资产7.1 版本管理与团队协作Skills 最大的价值在于可复用和可传承。一个人写好的 skill全团队都能用而且随着使用不断迭代优化。我建议把 skills 目录纳入 Git 管理和代码一起提交。每次修改 skill 都走正常的 code review 流程确保质量。团队协作时有一个经验给每个 skill 指定一个 owner。Owner 负责维护这个 skill 的准确性和时效性其他人发现问题时找 owner 反馈。没有 owner 的 skill 很容易腐烂因为没人对它的质量负责。我们团队的做法是在 SKILL.md 的 frontmatter 里加一个owner字段写明负责人。另一个做法是建立 skill 的测试用例。在 skill 目录下放一个tests/文件夹里面放一些输入输出对。每次修改 skill 后手动跑一遍测试用例确认行为没有退化。这个做法看起来麻烦但对于核心 skill 来说非常值得能避免“改了一个地方坏了另一个地方”的问题。7.2 技能组合与流水线设计单个 skill 的能力有限真正的威力在于组合。我设计过一条完整的代码审查流水线security-check→performance-check→style-check→summary-report。每个 skill 负责一个维度最后一个 skill 汇总所有发现生成统一的审查报告。组合的关键是定义清楚 skill 之间的接口。每个 skill 的输出格式要统一下一个 skill 才能正确读取。我通常用 JSON 作为中间格式因为结构清晰、易于解析。比如security-check输出一个 JSON 数组每个元素包含file、line、severity、descriptionsummary-report读取这个数组按严重程度分组生成 Markdown 报告。流水线设计还有一个好处是可以并行执行。security-check和performance-check互不依赖可以同时跑最后汇总。Claude Code 目前不支持真正的并行执行但你可以通过分步调用来模拟先跑安全检查再跑性能检查最后汇总。虽然串行执行慢一点但结果是一样的。7.3 从社区 skills 中学习设计模式社区里的开源 skills 是很好的学习材料。我分析过几十个热门 skills总结出几个常见的设计模式。模板模式skill 里包含一个输出模板AI 按模板填充内容适合报告生成类场景。检查清单模式skill 里列出一系列检查项AI 逐项检查并标记通过或失败适合代码审查类场景。决策树模式skill 里定义一系列判断条件AI 根据条件走不同分支适合问题诊断类场景。学习这些模式的最好方式是读别人的 SKILL.md然后自己改写一遍。不要直接复制因为每个项目的需求不同。我通常会把社区 skill 下载下来读一遍理解它的设计思路然后根据自己的项目特点重写。这个过程本身就是很好的学习写几个之后就能形成自己的风格。8. 我踩过的坑和最后分享的几个技巧先说几个我踩过的坑。第一个是在 skill 里写死具体路径比如/Users/xxx/project/src/结果换台机器就失效了。后来改成相对路径或者用环境变量问题解决。第二个是skill 的触发条件写得太“聪明”用了一些复杂的正则表达式结果 AI 理解不了反而不触发。后来改成简单的关键词匹配效果好多了。第三个是一次性改太多一个 skill 里塞了十几个步骤AI 执行到一半就乱了。后来拆成多个小 skill每个只做一件事稳定性大幅提升。再分享几个实用技巧。技巧一用examples/目录做“少样本学习”。在 skill 目录下放几个输入输出示例AI 会参考这些示例来理解你的意图。这个技巧对格式要求高的 skill 特别有效比如报告生成、代码重构。技巧二在 SKILL.md 里加一个“常见错误”段落列出这个 skill 容易犯的错误和避免方法。AI 读到这些会主动规避效果比事后纠正要好。技巧三定期清理不再使用的 skills。我每个月会 review 一次 skills 目录把三个月没用过的删掉或者归档。保持 skills 库的精简对性能和可维护性都有好处。最后说一个我个人的体会skills 的价值不在于数量而在于质量。一个精心设计的 skill能顶十个随便写的。我见过有人收集了几百个 skills但真正用的就那几个。与其追求“技能库”的规模不如把常用的几个场景做深做透。我现在项目里只保留了六个 skills但每一个都经过多次迭代触发精准、执行稳定、输出可靠。这比什么都强。