title: Skill 技能系统完全指南二自定义 Skill 开发——从 0 到 1date: 2026-07-10category: AI 开发工具tags: [Claude Code, Skill, 自定义, 开发, 扩展]Skill 技能系统完全指南二自定义 Skill 开发——从 0 到 1内置的 Skill 再强大也不如自己写的顺手。本篇带你深入 Skill 的内部构造从零开始编写一个完全贴合你项目需求的自定义 Skill。你会看到定义一个 Skill 只需要一个 Markdown 文件。前言在第 1 篇中我们认识了 Claude Code 的 Skill 系统——它是 Claude 的专业插件。但内置 Skill 是通用的你的项目有独特的代码规范命名约定、目录结构业务流程审批流、数据流转工具链特定的构建命令、部署脚本团队习惯Review 流程、Commit 规范这些只有你自己最清楚。所以我们需要自定义 Skill——一个 Markdown 文件告诉 Claude 在你这个项目里该怎么做事。一、Skill 文件的结构一个 Skill 就是一个.md文件放在.claude/skills/目录下。它的结构分为三部分1.1 前元数据Frontmatter文件开头的 YAML 块定义 Skill 的身份信息---name:my-skill-namedescription:简短描述这个 Skill 做什么trigger:触发关键词或场景tools:[Bash,Grep,Read,Write]# 该 Skill 使用的工具清单---字段必填说明name是Skill 的唯一标识使用 kebab-casedescription是一句话描述用于 Skill 匹配和发现trigger否触发关键词匹配时自动激活tools否该 Skill 需要用到的工具列表1.2 系统提示词System Prompt这是 Skill 的核心——相当于给 Claude 的人设和行为规范你是一个资深的 XXX 专家。 你的职责是 1. 做什么 2. 怎么做 3. 做到什么标准 工作原则 - 原则 1 - 原则 21.3 操作步骤Step-by-Step Guide可选的详细执行流程告诉 Claude 每一步该干什么## 执行步骤 ### 步骤 1准备工作 ... ### 步骤 2核心操作 ... ### 步骤 3验证结果 ...二、实战编写第一个自定义 Skill让我们从头到尾写一个完整的 Skill——数据库变更检查 Skill。2.1 场景描述你们团队有个规矩每次改数据库表结构必须先检查是否有对应的 MyBatis-Plus Mapper XML 文件需要同步更新。漏掉这个检查会导致线上查询报错。把这个规矩变成一个 Skill以后每次改完数据库让 Claude 自动检查。2.2 创建 Skill 文件在项目根目录创建.claude/skills/db-change-check.md--- name: db-change-check description: 检查数据库变更是否需要同步更新 Mapper XML 文件 trigger: 数据库变更, 表结构修改, mapper检查 tools: [Grep, Read, Bash] --- # 数据库变更检查 Skill ## 角色定义 你是一个资深 Java 后端开发工程师专注于 MyBatis-Plus 数据层的规范性检查。 ## 职责 当用户提到数据库变更建表、改表、加字段、删字段时 你必须执行以下检查 1. **定位变更的表**——从用户的描述或代码 diff 中提取涉及的表名 2. **查找对应的 Entity 类**——在 src/main/java/com/zkhz/asset/server/ 下搜索实体类 3. **检查 Mapper XML**——确认对应的 Mapper XML 文件是否存在 4. **检查 SQL 语句**——遍历 XML 中的所有 select, update, delete 标签 确认 WHERE 条件和 JOIN 引用的字段是否与变更后的表结构一致 5. **输出检查报告**——列出所有需要人工确认的地方 ## 工作原则 - 宁可多报不可漏报 - 如果无法确定某个查询是否受影响标记为需人工确认而非忽略 - 检查完成后给出明确的结论✅ 无需变更 / ⚠️ 需要关注 / ❌ 存在风险 ## 执行步骤 ### 步骤 1提取变更表名 从用户的描述或 git diff 中提取受影响的表名。 bash # 示例从 diff 中提取 CREATE TABLE / ALTER TABLE 语句 grep -rn CREATE TABLE\|ALTER TABLE src/main/resources/db/步骤 2查找 Entity 和 Mapper# 查找对应的 Entity 类grep-rlTableName.*表名src/main/java/# 查找对应的 Mapper XMLlssrc/main/resources/mapper/*表名*Mapper.xml步骤 3逐文件审查读取每个相关的 Mapper XML检查是否有硬编码的字段名WHERE 条件是否引用了被删除/修改类型的字段JOIN 是否关联了变更后的表步骤 4生成报告按以下格式输出 数据库变更检查报告 ━━━━━━━━━━━━━━━━━━━━━ 变更表jt_gas_production (新增字段: daily_target_m3) ✅ Entity 层无需变更 - GasProduction.java 使用 TableField 注解MyBatis-Plus 自动映射新字段 ⚠️ Mapper XML需关注 - GasProductionMapper.xml:45 — SELECT 语句中未包含 daily_target_m3 影响前端列表页不显示新字段非致命 - GasProductionMapper.xml:128 — INSERT 语句使用 include refidBase_Column_List/ 影响自动包含所有字段无需修改 ✅ ❌ Mapper XML存在风险 如无风险则此项省略 结论⚠️ 需要关注 — 建议补充 Base_Column_List 中的字段### 2.3 使用这个 Skill 创建完成后你就可以这样用了我刚刚给 jt_gas_production 表加了 daily_target_m3 字段帮我检查一下有没有需要改的 Mapper XML。/db-change-check或者直接自然语言触发数据库变更检查Claude 会自动加载 db-change-check Skill按照你定义的流程执行检查。 ## 三、Skill 编写技巧 ### 3.1 提示词要具体不要模糊 **差的写法** markdown 检查数据库相关的代码。太模糊了——数据库相关可以是 ORM 配置、连接池、SQL 性能……Claude 不知道该查什么。好的写法检查 MyBatis-Plus Mapper XML 文件中是否有因表结构变更而失效的 SQL 语句。 重点关注 WHERE 条件和 JOIN 引用的字段。明确指出了检查范围Mapper XML检查原因表结构变更检查重点WHERE 条件和 JOIN3.2 给 Claude 明确的输出格式告诉 Claude 结果长什么样方便你快速阅读## 输出格式 请按以下格式输出检查结果 ### 受影响文件 | 文件 | 行号 | 问题描述 | 风险等级 | |------|------|---------|---------| | XxxMapper.xml | 45 | WHERE 引用了已删除字段 | 高 | ### 总结 - 高风险问题X 个 - 中风险问题Y 个 - 低风险建议Z 个 ### 建议操作 1. ... 2. ...3.3 用原则约束行为除了告诉 Claude 做什么还要告诉它不做什么## 工作原则 - 如果某个文件不存在跳过而非报错 - 如果 SQL 使用了参数化查询#{xxx}认为它是安全的 - 如果 SQL 使用了字符串拼接${xxx}标记为高风险 - 宁可多报不可漏报3.4 提供示例给 Claude 一个输入输出的示例能大幅提高准确率## 示例 ### 输入 sql ALTER TABLE jt_device ADD COLUMN maintenance_cycle INT DEFAULT 30;输出 数据库变更检查报告 ━━━━━━━━━━━━━━━━━━━━━ 变更表jt_device (新增字段: maintenance_cycle) ✅ Entity 层无需变更 Device.java 使用 TableField 注解自动映射 ⚠️ Mapper XML需关注 DeviceMapper.xml:23 — SELECT 未包含 maintenance_cycle 影响前端列表不显示新字段非致命 结论⚠️ 需要关注## 四、Skill 的触发机制详解 ### 4.1 触发优先级 Claude Code 按以下优先级匹配 Skill显式调用/skill-name——最高优先级100% 命中自然语言匹配 description 字段——高优先级上下文推断——中优先级Claude 根据对话内容猜测### 4.2 如何优化自然语言触发 Skill 的 description 字段决定了自然语言触发的命中率。一个好的 description 应该 - **包含关键词**——让用户容易说出来的词 - **描述场景而非名称**——不说数据库检查 Skill说检查数据库变更的影响 - **列出常见触发词**——用逗号分隔多个关键词 yaml # 好的 description description: 检查数据库表结构变更对 Entity 和 Mapper XML 的影响 包括字段映射、SQL 语句兼容性、数据迁移脚本 # 不好的 description description: 数据库检查4.3 多 Skill 冲突处理如果多个 Skill 的 description 都匹配了你的输入Claude 会按匹配度排序选择最相关的一个如果匹配度相近询问你选择哪个你可以通过/skill-name显式调用指定 Skill 来消除歧义。五、进阶带条件判断的 Skill有些 Skill 需要根据条件执行不同的流程。Claude Code 支持在 Skill 中使用条件逻辑。5.1 条件分支示例## 执行逻辑 根据变更类型执行不同的检查 IF 变更类型 新增表 → 检查 Entity 类是否创建 → 检查 Mapper XML 是否创建 → 检查 Controller/Service 是否对接 ELSE IF 变更类型 新增字段 → 检查 Entity TableField 注解 → 检查 Mapper XML 的 SELECT/INSERT 语句 → 检查前端页面是否需要展示新字段 ELSE IF 变更类型 删除字段 → 检查 Entity 是否需要移除字段 → 检查 Mapper XML 中是否有引用该字段的 SQL → 检查前端页面是否有使用该字段的代码 → 检查是否有数据迁移脚本需要回滚 ELSE → 提示用户手动指定变更类型5.2 多步骤验证## 验证流程 1. 首先执行静态检查grep / 读取文件 2. 如果有问题执行动态验证运行测试 / 构建 3. 如果构建失败尝试自动修复 4. 修复后重新验证 5. 最多重试 2 次仍失败则报告详细错误六、Skill 调试技巧6.1 逐步验证编写 Skill 后用一个小场景测试我刚给 jt_user 表加了 nickname 字段 帮我跑一下 db-change-check。观察 Claude 的行为是否符合预期。如果不符合检查description是否包含触发关键词检查提示词是否有歧义检查步骤是否过于复杂6.2 查看 Skill 是否生效在对话中问当前有哪些 Skill 可用Claude 会列出所有已注册的 Skill 及其 description。6.3 迭代改进Skill 不是一次写成的。根据你的使用体验持续优化问题Skill 漏掉了 XXMapper.xml 的检查 改进在提示词中补充必须递归扫描 resources/mapper/ 下的所有 XML 问题输出太长了 改进增加只报告有问题的文件无问题的文件省略七、Skill 文件命名规范虽然文件名不影响功能但良好的命名习惯很重要命名方式示例适用场景action-description.mdcode-review.md动词开头的动作型 Skilldomain-type.mddb-change-check.md领域类型的描述型 Skillprefix-action.mdjt-deploy.md带项目前缀的 Skillmodule-skill.mdsecurity-audit.md通用功能型 Skill推荐使用 kebab-case短横线连接的小写字母不超过 40 个字符。八、这一章的核心心得Skill Markdown 文件——不需要编译不需要打包写即用核心是三要素——前元数据身份、系统提示词人设、操作步骤流程提示词要具体——越具体的指令Claude 执行得越准确给输出格式——结构化的输出让结果一目了然用原则约束——告诉 Claude 什么该做、什么不该做持续迭代——Skill 不是一次写成的根据使用反馈不断优化九、下一步学会了编写单个 Skill但真实的开发场景中往往需要多个 Skill 配合工作。比如一个完整的部署流程可能需要安全检查 Skill → 构建 Skill → 部署 Skill → 验证 Skill。下一篇我们将学习Skill 编排与组合让多个 Skill 像齿轮一样精密咬合形成自动化的工作流。系列目录初识 Skill 系统——什么是 Skill为什么需要 Skill自定义 Skill 开发——从 0 到 1 编写自己的 Skill← 本篇Skill 编排与组合——多个 Skill 串联工作打造自动化流程待写实战 SkillDevOps 部署——编写 Docker/Nginx/CI-CD 相关的部署 Skill待写实战 Skill代码质量——编写 Code Review / Lint / 测试覆盖率 Skill待写实战 Skill文档生成——编写 API 文档 / 技术手册 / Changelog 生成 Skill待写Skill 分享与复用——团队共享 Skill 库、开源 Skill 生态、版本管理待写Skill 进阶技巧——条件触发、多语言支持、与 Agent/Workflow 的配合待写