第 5 章：自定义 Skill——把重复操作封装成一键命令

第 5 章自定义 Skill——把重复操作封装成一键命令前四章我们搭建了安全网Git 回退、管理了上下文/compact、配置了记忆CLAUDE.md。这一章解决「效率」问题Vibe Coding 中有很多重复操作提交代码、启动环境、代码审查每次手动输入不仅繁琐还容易遗漏。自定义 Skill 可以把多步骤的固定工作流封装成一个斜杠命令一键执行。本章将讲解两种 Skill 创建方式、项目级与跨项目级的区别、Skill 生效与重载、三个实战示例以及 Skill 设计的核心原则。5.1 为什么需要自定义 Skill5.1.1 痛点场景在 Vibe Coding 中有些操作是每天重复执行的场景一每次提交代码手动操作流程 1. git status 查看变更了哪些文件 2. git diff 预览变更内容 3. 想一个合适的 commit message 4. git add . 5. git commit -m xxx 6. git push 7. 确认推送成功每次都要手动走这 7 步不仅繁琐还可能在第 3 步卡住想 commit message 想半天或者忘记第 6 步 push。场景二每次启动开发环境手动操作流程 1. 启动 PostgreSQL 数据库docker-compose up -d postgres 2. 启动 Redis 缓存docker-compose up -d redis 3. 等待服务就绪 4. 启动后端服务pnpm dev:server 5. 启动前端服务pnpm dev:client 6. 确认所有服务正常运行如果项目有 5 个依赖服务每次启动都要一条条敲命令非常耗时。场景三每次代码审查手动操作流程 1. /code-review 执行代码审查 2. 查看审查报告 3. 根据报告修复问题 4. 再次审查确认 5. 运行测试确认无回归这些步骤每次都一样但你可能会忘记第 5 步跑测试导致审查通过了但测试挂了。5.1.2 Skill 的核心价值自定义 Skill技能是 Agent 的扩展机制可以把固定的操作或经常用到的工作流封装成一个斜杠命令如/git-save、/start-dev、/code-review。调用时只需输入斜杠命令AI 就会按照预定义的流程执行一系列操作。三大核心价值价值说明一致性每次执行都遵循相同的步骤不会因为忘记某一步而出错高效性一键执行多步骤工作流不需要每次手动输入可共享项目级 Skill 纳入 Git 后团队所有人都能用相同的工作流一句话总结Skill 把「你每次都要告诉 AI 的操作流程」变成「AI 自动记住并执行的流程」你只需要触发一次。5.2 技能系统概述5.2.1 内置技能 vs 自定义技能Claude Code 的技能分为两类类型说明示例内置技能Claude Code 自带的技能不需要配置/compact、/memory、/code-review、/init自定义技能用户自己创建的技能封装特定工作流/git-save、/start-dev、/deploy-staging内置技能是通用的自定义技能是针对你的项目或个人习惯定制的。两者配合使用覆盖通用和个性化需求。5.2.2 技能的调用方式技能通过斜杠命令调用/git-save # 调用名为 git-save 的技能 /start-dev # 调用名为 start-dev 的技能 /deploy-staging # 调用名为 deploy-staging 的技能输入斜杠后Claude Code 会显示可用技能的自动补全列表方便你快速选择。5.2.3 两种创建方式Claude Code 支持两种创建自定义技能的方式适用于不同复杂度的需求方式配置位置适合场景复杂度方式一settings.json 注册settings.json的skills字段简单的指令模板一两句话能说清的操作低方式二插件目录创建~/.claude/plugins/skill-name/skill.md复杂的多步骤工作流需要详细的触发条件、执行步骤、注意事项中下面分别讲解这两种方式。5.3 创建方式一settings.json 注册简单技能5.3.1 基本格式最简单的技能就是一个指令模板在settings.json的skills字段中配置{skills:{test:Run the project tests. Use: pnpm test,deploy-staging:Deploy to staging environment. Steps: 1) pnpm run build 2) pnpm run deploy:staging 3) Verify at https://staging.example.com,git-save:Save current changes: 1) git status 2) git diff 3) Generate Conventional Commits message 4) git add . 5) git commit 6) git push}}每个技能是一个键值对键技能名称即斜杠命令如test对应/test值技能的指令描述AI 看到这个描述后按照描述执行操作5.3.2 配置位置settings.json 技能可以配置在两个位置位置作用域文件路径项目级当前项目project/.claude/settings.local.json或.claude/settings.json用户级所有项目~/.claude/settings.json选择建议项目特有的技能如该项目的部署流程、测试命令→ 项目级所有项目通用的技能如 Git 提交、代码格式化→ 用户级5.3.3 适用场景settings.json 方式适合简单的、一两句话能说清的操作不需要复杂的条件判断或错误处理快速创建不需要单独维护文件不适合多步骤、有条件分支的复杂工作流需要详细的触发条件说明需要团队协作维护的技能单独文件更方便 review5.4 创建方式二插件目录创建完整技能5.4.1 目录结构对于复杂的技能推荐在插件目录中创建单独的技能文件~/.claude/plugins/ └── my-skill/ └── skill.md # 技能定义文件项目级技能放在project/.claude/plugins/目录下用户级技能放在~/.claude/plugins/目录下。5.4.2 skill.md 的结构一个完整的skill.md文件包含 frontmatter 元数据和正文--- name: my-skill description: 运行自定义的 lint 检查并自动修复可修复的问题 --- # my-skill ## 触发条件 当用户输入 /my-skill或提到 运行 lint 检查、代码格式化 时触发。 ## 执行步骤 1. 运行 pnpm run lint 获取所有 lint 错误 2. 按错误类型分组格式问题、语法问题、最佳实践问题 3. 对于可自动修复的错误如 Prettier 格式、import 排序运行 pnpm run lint:fix 自动修复 4. 对于需要手动判断的错误如未使用变量、any 类型逐一向用户确认是否修复 5. 修复后再次运行 pnpm run lint 确认无错误 6. 输出修复报告自动修复了多少个、手动确认了多少个、剩余多少个 ## 注意事项 - 如果 lint 命令执行失败如配置错误停止执行并告知用户错误信息 - 自动修复前不需要确认但手动修复必须逐一确认 - 修复完成后建议用户运行测试确认无回归5.4.3 frontmatter 字段说明字段必填说明name是技能名称即斜杠命令如git-save对应/git-savedescription是技能的简短描述用于自动补全列表中显示5.4.4 正文的推荐结构一个结构良好的技能正文应该包含触发条件什么时候触发这个技能斜杠命令、关键词匹配执行步骤按顺序列出每一步操作清晰明确注意事项错误处理、边界情况、需要用户确认的环节可选输出格式执行完成后输出什么内容如报告、摘要可选验收标准执行完成后进行测试是否能够达成目标5.4.5 适用场景插件目录方式适合多步骤、有条件分支的复杂工作流需要详细的触发条件和错误处理需要团队协作维护单独文件方便 review 和版本控制技能逻辑可能频繁更新5.5 项目级 vs 跨项目级 Skill5.5.1 对比维度项目级 Skill跨项目级用户级Skill存放位置project/.claude/plugins/或.claude/settings.json~/.claude/plugins/或~/.claude/settings.json作用范围仅当前项目可用所有项目都可用适用场景项目特有的工作流部署流程、测试命令、构建脚本通用的工作流Git 提交、代码格式化、通用代码审查版本控制可以纳入 Git团队共享个人配置不纳入项目版本控制迁移成本换项目需要重新创建一次配置所有项目生效5.5.2 选择建议判断一个 Skill 应该放哪一级问自己两个问题这个 Skill 只对当前项目有意义吗是 → 项目级如项目特有的部署流程、数据库迁移命令否 → 跨项目级如 Git 提交、代码格式化团队其他人需要用这个 Skill 吗是 → 项目级纳入 Git团队共享否 → 跨项目级个人偏好常见的分类示例Skill级别原因/git-save提交推送跨项目级所有项目都用 Git/start-dev启动开发环境项目级每个项目的启动命令不同/deploy-staging部署到测试环境项目级每个项目的部署流程不同/lint-fix代码检查并修复跨项目级通用操作但命令可能因项目而异/code-review-deep深度代码审查跨项目级通用审查流程5.5.3 从项目级迁移到跨项目级如果你发现某个项目级 Skill 在多个项目中都需要可以把它迁移到跨项目级把技能文件从project/.claude/plugins/复制到~/.claude/plugins/或者把 settings.json 中的技能配置从项目级复制到用户级删除项目级的重复配置避免冲突在其他项目中测试是否正常工作5.6 Skill 生效与重载5.6.1 自动扫描Claude Code 会自动扫描以下目录中的技能文件project/.claude/plugins/~/.claude/plugins/通常情况下创建或修改技能文件后Claude Code 会自动识别。但有时候可能需要手动重载。5.6.2 手动重载如果创建了技能但输入斜杠命令时不显示尝试以下方法方法一/reload-skills 命令/reload-skills这个命令会重新扫描所有技能目录加载新创建或修改的技能。方法二重启 VS Code如果/reload-skills不生效尝试重启 VS Code。重启后 Claude Code 会重新加载所有配置和技能。方法三检查文件位置和格式如果重载后仍然不生效检查技能文件是否放在正确的目录.claude/plugins/或~/.claude/plugins/frontmatter 格式是否正确name和description字段是否存在文件名是否为skill.md注意大小写settings.json 中的 JSON 格式是否正确有没有语法错误5.6.3 常见不生效原因排查问题原因解决方案输入斜杠不显示技能技能未被扫描到/reload-skills或重启 VS Code技能显示但执行不对指令描述不清晰优化 skill.md 中的执行步骤更具体明确项目级技能不生效文件放错位置确认放在project/.claude/plugins/而非~/.claude/plugins/settings.json 技能不生效JSON 语法错误用 JSON 校验工具检查格式技能名冲突项目级和用户级有同名技能重命名其中一个或删除重复的5.7 实战示例三个实用 Skill5.7.1 示例一/git-save——一键提交并推送技能文件~/.claude/plugins/git-save/skill.md跨项目级--- name: git-save description: 一键完成代码提交和推送包含变更预览和 Conventional Commits 格式的提交信息 --- # git-save ## 触发条件 用户输入 /git-save或说提交代码、保存并推送时触发。 ## 执行步骤 1. 运行 git status查看变更文件列表 2. 运行 git diff预览变更内容 3. 根据变更内容生成符合 Conventional Commits 规范的提交信息 - 格式type(scope): description - type 可选feat / fix / refactor / docs / style / test / chore - 向用户确认提交信息是否合适不合适则调整 4. 运行 git add . 5. 运行 git commit -m {提交信息} 6. 运行 git push 7. 确认推送成功告知用户提交完成 ## 注意事项 - 如果 git status 显示没有变更告知用户没有需要提交的改动并终止 - 如果 git push 失败如网络问题、冲突告知用户失败原因不要自动重试超过 2 次 - 提交信息用英文遵循 Conventional Commits 规范 - 如果变更涉及多个不相关的功能建议用户分多次提交使用效果输入/git-saveAI 自动执行 7 步流程你只需要确认 commit message。5.7.2 示例二/start-dev——一键启动开发环境技能文件project/.claude/plugins/start-dev/skill.md项目级--- name: start-dev description: 一键启动项目开发环境包括数据库、缓存、后端和前端服务 --- # start-dev ## 触发条件 用户输入 /start-dev或说启动开发环境、启动服务时触发。 ## 执行步骤 1. 检查 Docker 是否运行 - 运行 docker info如果失败则告知用户请先启动 Docker Desktop并终止 2. 启动 PostgreSQL 和 Redis - 运行 docker-compose up -d postgres redis - 等待 5 秒运行 docker-compose ps 确认服务状态为 healthy - 如果服务未启动成功告知用户并终止 3. 启动后端服务 - 在新终端运行 pnpm dev:server - 等待输出 Server running on port 3000 - 如果启动失败查看错误日志并告知用户 4. 启动前端服务 - 在新终端运行 pnpm dev:client - 等待输出 Vite ready in - 如果启动失败查看错误日志并告知用户 5. 汇总状态 - 告知用户所有服务已启动 - 列出访问地址 - 前端页面http://localhost:5173 - 后端 APIhttp://localhost:3000 - API 文档http://localhost:3000/api-docs ## 注意事项 - 如果某一步失败停止后续步骤并告知用户失败原因 - 启动前可以先运行 /stop-dev 清理旧进程如果有该技能 - 不要在同一个终端中启动多个服务每个服务用独立终端使用效果输入/start-devAI 自动按顺序启动 4 个服务全部就绪后告诉你访问地址。5.7.3 示例三/lint-fix——代码检查并自动修复技能文件~/.claude/plugins/lint-fix/skill.md跨项目级--- name: lint-fix description: 运行 lint 检查自动修复可修复的问题手动确认需要判断的问题 --- # lint-fix ## 触发条件 用户输入 /lint-fix或说代码检查、lint 修复时触发。 ## 执行步骤 1. 检测项目使用的 lint 工具 - 检查 package.json 中是否有 eslint、prettier、stylelint 等 - 确定 lint 命令通常是 npm run lint 或 pnpm lint 2. 运行 lint 检查获取所有错误 3. 按错误类型分组 - 可自动修复格式问题、import 排序、未使用的 import - 需手动确认未使用的变量、any 类型、命名规范问题 - 需人工修复逻辑错误、复杂的类型错误 4. 自动修复可自动修复的问题 - 运行 lint --fix 或 prettier --write 5. 逐一展示需手动确认的问题询问用户是否修复 - 每个问题显示文件位置、问题描述、修复建议 - 用户确认后执行修复 6. 需人工修复的问题列出清单告知用户不自动修改 7. 再次运行 lint 确认无错误或仅剩人工修复项 8. 输出修复报告 - 自动修复X 个 - 手动确认修复Y 个 - 需人工修复Z 个列出清单 ## 注意事项 - 自动修复前不需要确认但修改后要展示修改了什么 - 手动确认的问题必须逐一询问不要批量修改 - 人工修复项只列出不自动修改 - 修复完成后建议运行测试确认无回归使用效果输入/lint-fixAI 自动检测工具、运行检查、分组处理、输出报告。5.8 Skill 设计三原则原则一单一职责一个 Skill 只做一件事。不要把「启动环境 写代码 测试 提交 部署」全部塞到一个 Skill 里。❌ 不好/do-everything启动→编码→测试→提交→部署一个技能全干 ✅ 好/start-dev启动环境 /run-tests跑测试 /git-save提交 /deploy部署四个技能各司其职原因单一职责的 Skill 更容易维护和调试可以灵活组合使用有时候只想启动环境不想提交出错时容易定位是哪个环节的问题原则二粒度适中Skill 的步骤数量要适中。太少1-2 步不值得封装成 Skill直接告诉 AI 就行太多15 步难以维护和调试。❌ 太少/echo就运行 echo hello完全没必要 ❌ 太多/full-pipeline20 步包含构建测试审查部署通知监控太复杂 ✅ 适中/git-save7 步、/start-dev5 步、/lint-fix8 步建议每个 Skill 3-10 步比较合适。超过 10 步考虑拆分成多个 Skill或用 Subagent 多代理来协调第 7 章讲解。原则三错误处理Skill 中要考虑每一步可能失败的情况并定义失败后的行为。❌ 不好只写运行 git push不考虑 push 失败怎么办 ✅ 好写运行 git push如果失败网络问题/冲突告知用户原因不要自动重试超过 2 次错误处理的三个层次检测失败每一步执行后检查是否成功退出码、输出内容处理失败定义失败后的行为终止、重试、告知用户、降级恢复失败如果 Skill 执行到一半失败确保不会留下不一致的状态如 commit 了但没 push5.9 本章小结本章系统讲解了自定义 Skill 的创建和使用核心知识点为什么需要 Skill把重复的多步骤工作流封装成一键命令保证一致性、提升效率、支持团队共享。两种创建方式settings.json 注册简单指令模板适合 1-2 步操作和插件目录创建完整 skill.md适合多步骤复杂工作流。skill.md 结构frontmattername description 正文触发条件 执行步骤 注意事项。项目级 vs 跨项目级项目特有工作流放项目级纳入 Git 团队共享通用工作流放用户级所有项目生效。生效与重载创建后通常自动扫描不生效时用/reload-skills或重启 VS Code检查文件位置和格式。三个实战示例/git-save一键提交推送、/start-dev一键启动环境、/lint-fix代码检查修复。设计三原则单一职责一个 Skill 只做一件事、粒度适中3-10 步、错误处理检测处理恢复。下一章我们将学习代码审查体系了解 Claude Code 的四道审查命令以及如何构建分级审查流程。完整抄写题目之后给出参考答案课后思考基础题自定义 Skill 的两种创建方式分别是什么各自适合什么场景提示从「配置位置」「复杂度」「适合场景」三个维度对比。参考答案两种创建方式内联Skill写在 CLAUDE.md、独立文件Skill.claude/plugins/*.md独立插件文件对比维度内联SkillCLAUDE.md内编写独立文件Skill.claude/plugins/xxx.md配置位置直接写在项目根目录CLAUDE.md里面存放在.claude/plugins/独立Markdown文件复杂度适合简短、步骤少的流程不宜过长支持长流程、多步骤、大量说明、示例模板加载特点每次会话完整跟随CLAUDE.md一起加载按需加载不会增加CLAUDE.md体积适合场景简单小脚本、2‑5步以内高频小操作例如/git‑save简易版本、简单代码检查项目少量简短指令复杂多步骤工作流、完整流程Skill需要大量示例、错误处理、详细说明多个Skill需要管理团队共享复杂Skill内联Skill简单轻量快速写一个小命令缺点会增加CLAUDE.md行数不能写过于庞大流程。独立文件Skill复杂大工作流把内容移出CLAUDE.md避免主文件膨胀方便维护多个Skill。基础题项目级 Skill 和跨项目级 Skill 有什么区别如何判断一个 Skill 应该放哪一级提示问自己两个问题——「只对当前项目有意义吗」「团队其他人需要用吗」参考答案区别项目级Skill存放位置项目目录内.claude/plugins/或者写进项目CLAUDE.md纳入Git版本管理团队成员克隆项目自动获得。作用域仅当前这一个项目生效。内容一般是和本项目强绑定本项目特定脚本、项目目录约定、项目专属部署命令。跨项目全局Skill存放位置用户全局目录~/.claude/plugins/不进入当前项目Git本机所有项目都可以使用属于个人本机偏好。作用域本机全部项目通用。内容是通用软件工程操作和具体业务无关。判断规则两个判断问题① 是否只针对当前项目才有意义、团队其他成员也需要这套流程 → 放项目级Skill提交到Git团队共享。② 属于你个人通用工作习惯和具体项目无关别的项目也想用不需要分享给团队其他人 → 放全局跨项目Skill不纳入项目Git。判断口诀项目特有、团队要共用 → 项目级个人通用、所有项目都复用、不需要给别人 → 全局跨项目级。进阶题Skill 设计三原则是什么请分析以下 Skill 设计是否合理并说明原因一个名为/full‑workflow的 Skill包含「启动环境→编写代码→运行测试→代码审查→提交→部署→通知团队」共 12 步。提示用单一职责和粒度适中两个原则来分析。参考答案Skill设计三原则单一职责原则一个Skill只做一件明确的事职责清晰不要把多个完全独立业务目标揉进同一个Skill。粒度适中原则粒度不能过小也不能过大粒度太大中间一旦失败整体很难恢复粒度过碎调用繁琐。具备错误处理原则要考虑中途失败有状态检测、报错提示、可恢复/可回退逻辑避免半完成不一致状态。案例分析/full‑workflow12步大而全流程不合理。原因违反单一职责把开发、测试、审查、git提交、部署、通知等多个完全独立的目标全部打包到一个Skill。很多场景我只需要做代码审查并不需要部署和通知团队但是这个Skill无法单独调用其中某一部分。粒度过大一共12个步骤链条很长。任意一步例如部署、通知失败前面步骤写代码、commit已经执行完成系统会停留在中间半完成的不一致状态很难局部重试、回退。灵活性差不同场景需要跳过部分环节大单体Skill很难适配。改进方案拆分成多个小粒度Skill/code‑write、/code‑review、/git‑save、/deploy、/notify‑team每个Skill职责单一。由人或者上层Workflow按需组合调用各个小Skill而不是全部硬编码到一个巨型Skill。进阶题如果你的 Skill 执行到一半失败了比如/git‑save在 commit 成功后 push 失败可能会留下什么不一致的状态你会如何在 Skill 设计中避免或处理这种情况提示考虑「commit 了但没 push」的状态以及 Skill 错误处理的三个层次检测处理恢复。参考答案会留下的不一致状态例子场景commit执行成功但是网络问题导致push失败。本地已经生成新commit远程仓库没有这条commit本地与远程不同步再次重复执行/git‑save容易产生重复commit。工作区、暂存区状态不确定部分操作已经执行部分没有执行处于半完成中间态。Skill内部认为执行失败但是本地已经产生修改直接重新运行会带来副作用。Skill错误处理三层策略检测 → 处理 → 恢复执行前前置检测预防执行Skill之前先检测当前状态检查是否存在未提交改动检查远程网络连通性对比本地分支与远程分支状态。条件不满足直接提前终止不往下执行。中途失败状态检测执行中每一个重要步骤完成之后增加状态校验。例如commit之后检测commit是否真实生成push之后检测本地与远程分支是否对齐。一旦某一步返回失败立刻终止后续步骤不要继续往下跑并且把当前不一致状态清晰输出告诉用户。失败之后提供恢复手段事后告诉用户当前准确状态例如提示“commit已经生成本地但push推送远程失败请检查网络”给出可选恢复方案①修复网络后单独执行push②不需要本次commit提供回退命令git reset --mixed HEAD~1撤销本次本地commit不要自动强行回退用户代码把选择权交给人避免误删用户有效提交。不建议在Skill内部遇到push失败就自动硬回退commit有可能commit是用户重要改动。优先报告状态给出手动恢复选项。开放题回顾你自己的 Vibe Coding 日常工作流列出 3 个你觉得最适合封装成 Skill 的重复操作。为其中一个设计 Skill 的执行步骤参考本章的实战示例格式。提示从「每天都要做」「步骤固定」「容易遗漏」三个角度找候选。参考示例答案开放题言之有理即可适合封装Skill的3个重复操作示例/git‑safe‑save代码修改后add、commit、push同时检查有没有密钥/密码意外提交每天高频步骤固定容易漏安全检查/quick‑review对改动文件做快速轻量代码审查检查语法错误、异常处理、硬编码密钥适合每次修改完快速质检。/milestone‑check到达里程碑节点执行冒烟测试 完整code review 更新文档 输出milestone报告。选取其中一个/git‑safe‑saveSkill执行步骤示例Skill名称/git‑safe‑save作用安全保存改动执行git提交推送同时防止密钥、密码被误提交。执行步骤收集本次改动文件列表扫描文件内容检测是否存在密钥、access‑key、密码等敏感信息如果发现敏感信息直接终止Skill输出风险文件列表提示用户处理敏感内容禁止继续提交。确认有真实代码改动若无改动直接提示“没有需要提交的改动”结束。要求生成简洁规范commit messageConventional Commits 规范。执行git add添加改动文件。执行git commit使用上面生成的commit message。尝试执行git push推送远程。✅push成功输出成功提示展示本次commit简短信息Skill结束。❌push失败立刻终止后续步骤输出提示本地commit已生成但推送远程失败请检查网络/远程仓库状态同时提供两个可选操作提示方案1修复网络后手动执行git push方案2不需要本次提交执行git reset HEAD~1撤销本地commit。补充Skill不自动执行回退只把状态、命令提示给用户由人做决策。