Claude Code 自定义 Skills 开发教程：打造你的专属斜杠命令
Claude Code 的 Skills 系统允许开发者创建自定义的斜杠命令（Slash Commands），将常用的复杂操作封装成一条简单的/command。本文将从零开始，带你掌握 Skills 的开发、注册与实战应用。
一、什么是 Skills
Skills 是 Claude Code 中的可复用指令模板。当你在对话中输入/skill-name时，Claude Code 会加载对应的 Skill 定义文件，将其中的 prompt 注入上下文，从而让 AI 按照预设的专业流程执行任务。
简单理解：Skills = 预定义的专家角色 + 标准化工作流程 + 可传参的模板
Skills 的核心优势：
- 一致性：团队成员使用同一套 Skill，输出质量统一
- 效率：复杂操作一条命令搞定，省去重复描述
- 可分享：Skill 文件可以通过 Git 在团队间共享
- 可组合：一个 Skill 可以调用其他 Skills
二、Skill 文件结构
Skill 定义文件存放在.claude/skills/目录下，使用 Markdown 格式，包含 YAML frontmatter 和 prompt body 两部分。
2.1 基本结构
--- name: deploy description: "一键部署应用到生产环境" trigger: "deploy" args: - name: target description: "部署目标: all | backend | frontend" required: false default: "all" --- # 部署流程 你是一个 DevOps 专家。请按照以下步骤部署项目： 1. 运行 lint 和类型检查 2. 执行单元测试 3. 构建项目 4. 通过 SSH 部署到服务器 5. 验证部署结果 部署目标: {{target}} ## 注意事项 - 部署前必须确认所有测试通过 - 如果是 backend 部署，需要运行数据库迁移 - 部署后检查 PM2 进程状态2.2 Frontmatter 字段详解
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | string | 是 | Skill 的唯一标识名称 |
description | string | 是 | 简短描述，显示在帮助列表中 |
trigger | string | 是 | 触发命令，用户输入 /trigger 激活 |
args | array | 否 | 参数列表定义 |
tools | array | 否 | 该 Skill 需要使用的工具列表 |
context | array | 否 | 自动加载的上下文文件 |
三、创建你的第一个 Skill
3.1 目录准备
# 在项目根目录创建 skills 目录 mkdir -p .claude/skills # 创建第一个 skill 文件 touch .claude/skills/changelog.md3.2 编写 Changelog 生成 Skill
--- name: changelog description: "根据 Git 提交记录自动生成 CHANGELOG" trigger: "changelog" args: - name: since description: "起始版本标签，如 v1.2.0" required: false default: "" - name: format description: "输出格式: standard | keepachangelog" required: false default: "keepachangelog" --- # Changelog 生成专家 你是一个专业的 Changelog 生成器。请按以下步骤操作： ## 步骤 1. **获取提交记录**： - 如果指定了 since 标签 ({{since}})，获取该标签之后的所有提交 - 否则获取最近 50 条提交 2. **分类整理**： 按照 Conventional Commits 规范分类： - feat: 新功能 - fix: Bug 修复 - perf: 性能优化 - refactor: 重构 - docs: 文档变更 - chore: 构建/工具变更 3. **生成 Changelog**： 使用 {{format}} 格式输出 4. **写入文件**： 追加到 CHANGELOG.md 文件顶部（保留旧内容） ## 输出格式要求 - 版本号自动从 package.json 读取 - 日期使用 YYYY-MM-DD 格式 - 每条记录包含 commit hash 的前 7 位3.3 使用 Skill
# 基本使用 /changelog # 指定起始版本 /changelog v1.2.0 # 指定格式 /changelog v1.0.0 standard四、实战：5 个高频 Skills
4.1 数据库迁移 Skill
--- name: db-migrate description: "安全地创建和执行数据库迁移" trigger: "db-migrate" args: - name: action description: "操作类型: create | run | revert" required: true - name: name description: "迁移名称（仅 create 时需要）" required: false --- # 数据库迁移专家 你是 TypeORM 数据库迁移专家，严格遵循以下规则： ## create 操作 1. 分析当前 entity 定义与数据库 schema 差异 2. 生成迁移文件到 src/migrations/ 3. 文件名格式: {timestamp}-{{name}}.ts 4. 必须同时包含 up() 和 down() 方法 5. 生成前先 review 变更内容 ## run 操作 1. 先在 dry-run 模式预览 SQL 2. 确认无误后执行迁移 3. 验证迁移结果 ## revert 操作 1. 显示最近 5 次迁移记录 2. 执行 revert 并验证 ## 安全规则 - 禁止在迁移中 DROP COLUMN（改为 RENAME + 标记废弃） - 大表 ALTER 必须提醒用户注意锁表风险 - 生产环境迁移前必须备份4.2 代码审查 Skill
--- name: review description: "对当前分支的变更进行专业代码审查" trigger: "review" args: - name: focus description: "审查重点: security | performance | all" required: false default: "all" --- # 高级代码审查员 审查当前分支相对于 main 的所有变更，重点关注 {{focus}}。 ## 审查维度 ### 安全性 (security) - SQL 注入风险 - XSS 漏洞 - 敏感信息泄露 - 权限校验缺失 ### 性能 (performance) - N+1 查询 - 内存泄漏风险 - 不必要的重渲染 - 缺少索引 ### 代码质量 (all) - 命名规范 - 错误处理完整性 - 类型安全 - 单元测试覆盖 ## 输出格式 按严重程度分级：CRITICAL / WARNING / SUGGESTION 每条包含：文件路径、行号、问题描述、修复建议4.3 API 接口生成 Skill
--- name: gen-api description: "根据描述生成完整的 RESTful API" trigger: "gen-api" args: - name: resource description: "资源名称，如 article, user, order" required: true - name: fields description: "字段定义，如 title:string,price:number" required: true --- # API 生成器 根据资源名 {{resource}} 和字段 {{fields}} 生成完整的 CRUD API。 ## 生成内容 1. Entity 定义 (TypeORM) 2. DTO (CreateDto, UpdateDto, QueryDto) 3. Service (含分页、过滤、排序) 4. Controller (RESTful 路由) 5. Module 注册 6. 单元测试骨架 ## 规范 - 使用 class-validator 做参数校验 - 统一返回格式 {success, data, message} - 分页接口返回 {list, total, page, pageSize} - 软删除使用 deletedAt 字段4.4 自动部署 Skill
--- name: ship description: "构建、测试并部署到生产环境" trigger: "ship" args: - name: target description: "部署目标: all | backend | frontend" required: false default: "all" --- # 部署工程师 执行完整的 CI/CD 流程，部署目标: {{target}} ## 流程 1. 运行 TypeScript 类型检查 2. 运行 ESLint 3. 执行单元测试（失败则中止） 4. 构建项目 5. 通过 deploy.sh 部署 6. 等待 30 秒后健康检查 7. 输出部署摘要 ## 回滚策略 如果健康检查失败： - 记录错误日志 - 提示用户是否回滚到上一版本4.5 文档同步 Skill
--- name: sync-docs description: "根据代码变更自动更新 API 文档" trigger: "sync-docs" --- # 文档同步专家 扫描所有 Controller 文件，提取路由、参数、返回值信息， 自动更新 docs/api.md 文档。 ## 提取规则 - 从 @ApiOperation 或注释中提取接口描述 - 从 DTO 中提取请求参数 - 从 Controller 返回类型推断响应结构 - 标注需要认证的接口 ## 输出格式 按模块分组，每个接口包含： - 方法 + 路径 - 描述 - 请求参数表格 - 响应示例 - 错误码说明五、高级技巧
5.1 Skill 中引用上下文文件
--- name: fix-bug description: "智能 Bug 修复" trigger: "fix" context: - "CLAUDE.md" - "src/common/errors.ts" - "tsconfig.json" --- 修复用户描述的 Bug。修复前先阅读项目约定（CLAUDE.md）， 确保修复方案符合项目规范。5.2 Skill 组合调用
一个 Skill 的 prompt 中可以引导 Claude Code 调用其他 Skills：
--- name: release description: "完整的版本发布流程" trigger: "release" --- 执行以下完整发布流程： 1. 先执行 /review 确保代码质量 2. 执行 /changelog 生成变更日志 3. 更新 package.json 版本号 4. 创建 Git tag 5. 执行 /ship 部署到生产环境5.3 条件分支逻辑
--- name: init description: "初始化新模块" trigger: "init" args: - name: type description: "模块类型: api | page | lib" required: true --- 根据模块类型 {{type}} 执行不同的初始化流程： 如果 type 是 api： - 创建 module, controller, service, entity, dto - 注册到 AppModule 如果 type 是 page： - 创建 Vue 组件、路由配置、Store 模块 - 添加菜单项 如果 type 是 lib： - 创建独立的 npm 包结构 - 配置 tsconfig paths 别名六、团队协作最佳实践
- 将
.claude/skills/目录纳入 Git 版本管理 - 为每个 Skill 写清晰的
description，方便团队成员发现 - 遵循命名约定：动词开头，如
gen-api、fix-bug、sync-docs - 复杂 Skill 拆分为多个小 Skill，通过组合调用实现
- 在
CLAUDE.md中列出团队常用 Skills 及使用场景
七、调试与排错
Skill 加载失败时，常见原因：
- YAML 语法错误：frontmatter 中的冒号后必须有空格
- 文件路径错误：确认文件在
.claude/skills/目录下 - 参数未传递：
required: true的参数未提供时会报错 - 模板变量未替换：确保使用
{{argName}}双花括号语法
# 查看已注册的 Skills 列表 # 在 Claude Code 中输入 / 后按 Tab 可以看到所有可用命令 # 查看某个 Skill 的详细信息 cat .claude/skills/deploy.md总结
自定义 Skills 是 Claude Code 最强大的扩展机制之一。通过合理设计 Skills，你可以将团队的最佳实践固化为可复用的命令，大幅提升开发效率。建议从最常重复的操作开始，逐步构建自己的 Skills 库。
接口配置参考：https://9m8m.com/docs/