1. 从零理解 Agent Skills它到底是什么为什么突然火了第一次看到 “skills” 这个词挂在 Claude 相关讨论里我其实也愣了一下。毕竟在传统认知里Claude 就是一个对话模型你问它答顶多写写代码、改改文案。但 “Agent Skills” 这个概念出现之后整个玩法变了——它不再只是“你问我答”而是让 Claude 能够按照一套预定义的流程去执行任务像一个真正被培训过的助手知道先做什么、再做什么、遇到什么情况该怎么处理。简单来说Agent Skills 就是一套写给 AI 看的“操作手册”。你把某个任务的完整流程、注意事项、输出格式、常见坑点全部写进一个叫SKILL.md的文件里Claude 在执行相关任务时就会自动加载这个文件按照你定义的规则来干活。这跟传统的 prompt engineering 有本质区别prompt 是一次性的、临时的而 skill 是可复用、可版本管理、可分享的。我拿一个实际场景来类比。假设你是一个数学建模比赛的参赛者每次拿到题目都要经历“读题→选模型→写代码→跑结果→写论文”这一整套流程。如果没有 skill你每次都要重新跟 Claude 解释一遍你的偏好、你的代码风格、你常用的求解器。但如果你写了一个math-modeling/SKILL.md里面规定好了“先用 Python 的 scipy 做数值求解输出必须包含灵敏度分析论文格式用 LaTeX”那 Claude 每次都会按这个标准来省掉大量重复沟通成本。这也是为什么最近 “skills” 的搜索量暴涨。大家发现与其每次费劲写长 prompt不如一次性把经验固化成 skill 文件之后直接调用。对于前端开发、数学建模、AI 漫剧创作、甚至 STM32 嵌入式开发这些有固定工作流的领域skills 的价值尤其明显。注意Agent Skills 目前主要围绕 Claude 的生态展开包括 Claude CodeCLI 工具、Claude Desktop桌面版以及通过 API 接入的各种客户端。不同入口对 skill 的加载方式略有差异后面会详细拆解。2. SKILL.md 文件结构深度拆解写什么、怎么写、写多细2.1 核心字段与最小可用模板一个能跑的SKILL.md其实不需要多复杂。我见过很多人把它写得像论文一样长结果 Claude 加载后反而抓不住重点。根据我自己的反复测试最小可用版本只需要三个部分元信息、触发条件、执行步骤。元信息用 YAML frontmatter 写在文件最顶部格式如下--- name: frontend-component-generator description: 根据设计稿描述生成 React TypeScript 组件包含样式和单元测试 version: 1.2.0 ---这三个字段里name是 skill 的唯一标识建议用英文小写加连字符description最关键它决定了 Claude 在什么场景下会主动加载这个 skill——写得越具体触发越精准version是可选但强烈建议加的方便你后续迭代时追踪变更。触发条件部分我通常用自然语言描述比如## 何时使用 当用户提出以下类型请求时加载本 skill - 要求生成新的 React 组件 - 要求将 Figma 设计稿转换为代码 - 要求为现有组件补充单元测试执行步骤是核心我习惯用有序列表加代码块的方式写。比如前端组件生成 skill 的执行步骤## 执行步骤 1. 确认组件名称和 props 接口若用户未提供则根据描述推断并列出假设 2. 生成组件文件使用函数式组件 hooks样式优先用 CSS Modules 3. 生成对应的 .test.tsx 文件使用 React Testing Library 4. 输出文件树和安装依赖命令2.2 触发精度控制避免 skill 被误加载或漏加载这是实操中最容易踩的坑。我一开始写了一个通用的 “code-helper” skilldescription 写的是“帮助编写代码”结果 Claude 在任何跟代码沾边的场景都会加载它导致输出变得冗长且不聚焦。后来我把 description 改成了“当用户明确要求生成 Python 数据可视化代码且涉及 matplotlib 或 seaborn 时加载”误触发率立刻降下来了。反过来漏加载也很常见。如果你写的触发条件太窄Claude 可能在你需要的时候反而不加载。我的经验是在 description 里同时包含“动作词”和“领域词”。动作词比如“生成”“重构”“审查”“转换”领域词比如“React 组件”“SQL 查询”“LaTeX 表格”。两者组合起来命中率最高。另外Claude Code 在加载 skill 时有一个优先级机制项目根目录下的.claude/skills/优先级最高其次是用户主目录下的~/.claude/skills/。如果你在多个位置放了同名 skill项目级的会覆盖全局的。这个机制可以用来做“项目定制化”——全局放通用 skill项目里放针对该项目的覆盖版本。2.3 内容粒度写到什么程度才算“够用”我见过两种极端一种是只写了两行Claude 加载后跟没加载一样另一种是写了三千字Claude 加载后反而不知道该听哪句。经过多次迭代我总结出一个判断标准假设你是一个刚入职的实习生只看这份 skill 能不能独立完成任务。如果能粒度就够了如果还需要你口头补充那就说明 skill 里缺东西。具体来说以下内容必须写进 skill输入输出的格式要求比如“输出必须是 JSON字段名用 camelCase”工具和库的选型偏好比如“HTTP 请求统一用 httpx不用 requests”边界情况的处理方式比如“如果用户没提供超时时间默认设为 30 秒”禁止事项比如“不要生成任何包含 eval 的代码”而以下内容不建议写进 skill过于通用的编程常识比如“变量名要有意义”与任务无关的个人偏好比如“注释用中文”这种可以放全局配置频繁变动的信息比如具体的 API key应该用环境变量3. 手把手实操从安装到跑通第一个 Skill3.1 环境准备与 Claude Code 安装不管你用的是 Windows、macOS 还是 LinuxClaude Code 的安装方式基本一致。前提是你有一个可用的 Node.js 环境建议 18 以上。安装命令npm install -g anthropic-ai/claude-code安装完成后在终端输入claude应该能看到交互界面。如果提示 “claude 无法将‘claude’项识别为 cmdlet、函数、脚本文件或可运行程序的名称”说明 npm 的全局 bin 目录没在 PATH 里。Windows 下可以用npm config get prefix找到路径然后手动加到系统环境变量里。提示如果你在 Windows 上遇到 “requires the virtual machine platform” 之类的提示那是因为 Claude Code 的某些沙箱功能依赖虚拟化平台。在“启用或关闭 Windows 功能”里勾选“虚拟机平台”和“Windows 子系统 for Linux”即可不需要额外装虚拟机软件。安装完成后第一次运行claude会引导你登录。登录成功后你就可以在终端里跟 Claude 对话了。但这时候还没有 skill 功能——你需要手动创建 skill 目录。3.2 创建你的第一个 Skill 目录Claude Code 默认从两个位置读取 skill全局~/.claude/skills/项目级项目根目录/.claude/skills/我建议新手先在全局目录下建一个测试 skill。以 macOS/Linux 为例mkdir -p ~/.claude/skills/hello-skill然后在里面创建SKILL.md--- name: hello-skill description: 当用户说“打个招呼”或“测试 skill”时加载输出一段带时间戳的问候语 version: 1.0.0 --- ## 执行步骤 1. 获取当前系统时间 2. 输出格式[HH:MM:SS] 你好skill 已生效 3. 不要输出任何额外解释保存后在 Claude Code 里输入“测试 skill”如果它回复了带时间戳的问候语说明 skill 加载成功。如果没有检查两点一是文件路径是否正确二是 description 里的触发词是否跟你输入的内容匹配。3.3 从 GitHub 手动安装第三方 Skill网上有很多人分享自己写的 skill比如 “superpower skills” 和 “typesafe ai skills” 这两个仓库在社区里口碑不错。手动安装的流程其实很简单# 假设你要安装的 skill 在 GitHub 的某个仓库里 git clone https://github.com/xxx/superpower-skills.git cp -r superpower-skills/skills/* ~/.claude/skills/复制完成后每个子目录里的SKILL.md会被自动识别。你可以用claude的/skills命令如果版本支持查看当前已加载的 skill 列表。如果不支持直接看目录结构也能确认。注意从网上 clone 下来的 skill 一定要先读一遍SKILL.md的内容确认没有奇怪的指令比如要求读取敏感文件或执行危险命令。skill 本质上就是给 AI 的指令集安全性完全取决于写它的人。3.4 在 VSCode 里配置 Claude Code如果你习惯在 VSCode 里写代码可以把 Claude Code 集成进去。最简单的方式是打开 VSCode 的集成终端直接运行claude。这样 Claude Code 就能感知到你当前打开的项目路径项目级的 skill 也会自动生效。更进一步的玩法是装一个 “Claude Code” 扩展社区维护的可以在侧边栏直接对话。但根据我的实测终端方式的稳定性最好扩展偶尔会出现 skill 加载不全的问题。如果你遇到 skill 不生效的情况优先用终端方式排查。4. 高频场景实战Skills 在不同领域的落地方式4.1 前端开发组件生成与代码审查前端是我用得最多的场景。我给自己配了两个 skill一个是react-component-gen负责根据描述生成组件另一个是frontend-review负责审查现有代码。react-component-gen的核心逻辑是这样的## 执行步骤 1. 解析用户描述提取组件名、props、交互行为 2. 若描述模糊列出 2-3 个假设并让用户确认 3. 生成组件文件规则 - 函数式组件 TypeScript - 样式用 CSS Modules文件名 [Component].module.css - 状态管理优先用 useState/useReducer除非用户指定 Zustand 4. 生成测试文件覆盖渲染、交互、边界情况 5. 输出文件树和依赖安装命令这个 skill 帮我省掉了大量重复沟通。以前我每次都要说“用 TypeScript”“样式用 CSS Modules”“测试用 RTL”现在一句话“生成一个带搜索功能的表格组件”Claude 就按我的标准全自动完成了。frontend-review则是在我写完代码后调用它会检查是否有未处理的 Promise rejection、是否有内存泄漏风险比如 useEffect 里没清理定时器、是否有可访问性问题比如按钮没有 aria-label。这些检查项都是我踩过坑之后加进去的。4.2 数学建模从读题到论文的全流程 Skill数学建模比赛的时间压力很大通常三天要完成选题、建模、求解、写作。我帮几个参加华为杯的朋友配了一套 skill效果很明显。核心 skill 叫math-modeling-pipeline执行步骤分四个阶段## 阶段一题目解析 - 提取题目中的关键变量和约束条件 - 判断问题类型优化、预测、评价、分类 - 列出可能的模型候选并说明适用理由 ## 阶段二模型建立 - 优先选择经典模型线性规划、灰色预测、TOPSIS、随机森林等 - 必须包含灵敏度分析或鲁棒性检验 - 输出模型假设和符号说明 ## 阶段三代码实现 - 用 Python数值计算用 numpy/scipy可视化用 matplotlib - 代码必须包含注释和随机种子设置 - 输出结果要保存为 CSV方便后续绘图 ## 阶段四论文撰写 - 用 LaTeX 格式结构摘要、问题重述、模型假设、模型建立与求解、灵敏度分析、模型评价 - 摘要控制在 800 字以内必须包含具体数值结果这套 skill 最大的价值是强制流程化。比赛时人容易慌东做一点西做一点有了 skill 之后Claude 会按阶段推进每一步都有明确产出不容易乱。4.3 AI 漫剧创作角色设定与分镜生成AI 漫剧是最近很火的方向核心流程是“故事大纲→角色设定→分镜脚本→画面描述→配音文案”。我配了一个ai-comic-skill重点解决角色一致性问题。## 角色一致性规则 1. 每个角色在首次出现时生成一份“角色卡”包含 - 姓名、年龄、外貌特征发色、瞳色、服装风格 - 性格关键词3-5 个 - 说话风格比如“简短有力”“喜欢用反问句” 2. 后续所有分镜中角色的外貌和说话风格必须与角色卡一致 3. 如果剧情需要角色形象变化比如受伤、换装必须在分镜中明确标注变化点这个 skill 解决了一个很痛的问题AI 生成多幕剧情时角色形象经常漂移。有了角色卡约束之后一致性明显提升。4.4 嵌入式开发STM32 代码生成与寄存器配置嵌入式开发对准确性要求极高一个寄存器配错就可能烧板子。我配的stm32-skill主要做两件事生成初始化代码和检查配置冲突。## 执行步骤 1. 确认芯片型号和使用的片上外设GPIO、UART、SPI、I2C、TIM 等 2. 生成初始化代码使用 HAL 库每个外设单独一个函数 3. 检查项 - 时钟树配置是否与总线频率匹配 - GPIO 复用功能是否与所选外设一致 - 中断优先级是否冲突 4. 输出时附带寄存器级说明方便对照参考手册这个 skill 我建议配合具体的参考手册使用。Claude 对 STM32 的寄存器细节记忆不一定完全准确所以我在 skill 里加了一条“所有寄存器配置必须标注参考手册的章节号方便人工复核”。5. 常见问题与排查技巧实录5.1 Skill 不生效的排查清单现象可能原因解决方法输入触发词后无反应description 里的触发词不匹配把 description 改得更具体包含用户可能说的原话Skill 加载了但输出不对执行步骤写得太模糊补充具体格式、工具、边界条件多个 skill 冲突触发条件重叠缩小 description 范围或调整目录优先级项目级 skill 不生效路径不对确认是项目根/.claude/skills/而不是其他位置修改后不生效缓存问题重启 Claude Code 会话5.2 我踩过的三个坑第一个坑description 写得太泛。我最早写了一个code-helperdescription 是“帮助编写代码”。结果 Claude 在任何代码场景都加载它输出变得又长又泛。后来改成“当用户要求生成 Python 数据处理脚本且涉及 pandas 或 numpy 时加载”精准多了。第二个坑执行步骤里放了太多“建议”而不是“规则”。比如我写过“建议使用 TypeScript”Claude 有时候用有时候不用。后来改成“必须使用 TypeScript不允许生成 .js 文件”就稳定了。skill 里的语言要像规章制度不要像建议。第三个坑忘了写输出格式。有一次我让 Claude 生成一个配置文件它给我输出了一段带解释的 Markdown但我需要的是纯 JSON。后来我在 skill 里加了一条“输出必须是纯 JSON不要包含任何解释文字或 Markdown 代码块标记”问题解决。5.3 性能与维护建议Skill 多了之后加载速度会变慢。我的经验是全局 skill 控制在 10 个以内项目级 skill 按需添加。如果某个 skill 很久没用就把它移到~/.claude/skills-archive/里需要时再移回来。另外建议给每个 skill 加版本号和更新日志。我自己的做法是在SKILL.md末尾加一个## 变更记录段落每次修改都记一笔。这样当输出不符合预期时可以快速定位是哪次改动引入的问题。6. 进阶玩法Skill 组合与自动化流水线6.1 用 Skill 串联多步骤工作流单个 skill 解决单点问题但真实任务往往是多步骤的。比如“从需求文档到可运行的前端项目”这个流程可以拆成三个 skillrequirement-parser解析需求、component-gen生成组件、project-scaffold搭建项目结构。然后在 Claude Code 里按顺序调用。更进一步你可以写一个“元 skill”在它的执行步骤里明确引用其他 skill## 执行步骤 1. 加载 requirement-parser提取功能点和非功能需求 2. 加载 project-scaffold初始化项目结构 3. 对每个功能点加载 component-gen 生成对应组件 4. 最后加载 frontend-review 做整体检查这种组合方式适合固定流程的项目比如每周都要做的周报生成、每月都要跑的报表分析。6.2 把 Skill 接入其他工具链Claude Code 支持通过 MCPModel Context Protocol接入外部工具。你可以写一个 skill在里面调用 MCP 工具来完成更复杂的操作比如查询数据库、调用内部 API、操作文件系统。我自己的一个用法是写了一个db-query-skill里面规定“所有数据库查询必须先用 EXPLAIN 检查执行计划如果扫描行数超过 10000 则拒绝执行并提示优化”。这样即使 Claude 生成了低效查询也会被 skill 规则拦住。6.3 Skill 的分享与协作如果你在团队里用 Claude Code可以把项目级 skill 提交到 Git 仓库这样所有成员共享同一套规则。我建议在仓库里建一个.claude/skills/目录每个 skill 一个子目录然后在 README 里说明每个 skill 的用途和触发方式。对于开源分享GitHub 上已经有不少 skill 集合仓库。你可以参考别人的写法但不要直接复制——因为每个人的工作流不同skill 必须根据自己的实际需求定制。我通常的做法是clone 下来读一遍提取有用的规则然后融合进自己的 skill 里。7. 关于 Skill 设计的一些个人体会写了这么多 skill 之后我最大的感受是skill 的质量取决于你对任务的理解深度而不是你对 AI 的 prompt 技巧。如果你自己都没想清楚一个任务的完整流程和边界情况写出来的 skill 一定是模糊的Claude 执行起来也会飘。另一个体会是skill 要迭代不要一次求完美。我最早的几个 skill 现在回头看简直没法用但正是通过一次次实际使用、发现问题、修改规则才慢慢打磨出可用的版本。建议你每用完一次 skill花两分钟想想“这次哪里不满意”然后立刻改。改个五六次之后skill 就会变得非常顺手。还有一个容易被忽略的点skill 里要写“不要做什么”。比如“不要生成任何包含eval的代码”“不要在输出里包含 API key”“不要自动执行 git push”。这些禁止项往往比正面规则更重要因为它们能防止 AI 在你不注意的时候做出危险操作。最后分享一个小技巧如果你不确定一个 skill 该怎么写可以先在 Claude Code 里手动做一遍任务把每一步的对话记录下来然后让 Claude 帮你把这段对话整理成SKILL.md格式。这个方法我试过很多次整理出来的初稿质量相当不错你只需要再微调一下触发条件和边界规则就行。