内容来源：Software Engineer's Blog / Jamongx。https://jamongx.com/claude-code-skills-guide-teaching-ai-your-workflow/
原题：Claude Code Skills Guide: How to Automate Your Development Workflow
原发布时间：2026-01-04
Claude Code Skills 能把重复流程封装起来，让 Claude 自动审查代码、落实项目约定，并帮助团队保持一致的质量标准。
Claude Code 是一个在终端中运行的编程智能体。它不只是生成代码，还能自动完成开发工作流中的重复性环节。
本文不讲安装或基础用法，而是写给已经在使用 Claude Code，并希望掌握如何设计真正能为实际项目带来自动化与一致性的 Skills 的开发者。
在 Claude Code 的各种功能中，Skills 是规定 Claude 如何处理重复任务、遵循项目工程约定的主要方式。本文将具体看看，它们如何帮助团队维持一致的代码质量。
2026 年 7 月更新——本指南 1 月发布的版本，把 Skills 描述为
.claude/commands/中的单个.md文件。此后，Skills 已改为目录结构（.claude/skills/<name>/SKILL.md），采用正式的 Frontmatter 规范，并在 agentskills.io 成为开放标准。本次修订已反映当前格式，示例也都来自我在真实项目中实际使用的 Skills。
1. Skills 是什么？
在 Claude Code 中，Skill 是一个包含 SKILL.md 文件的目录。这个文件定义 Claude 调用该 Skill 时需要遵循的指令、资源和执行步骤。对于个人和项目 Skills，目录名就是命令名：.claude/skills/code-review/SKILL.md 会提供 /code-review 命令。（插件 Skills 则会加上插件名称作为命名空间，例如 /my-plugin:review。）
• Rules 是你的“政策文件”
• Skills 是你的“标准作业程序”
需要分清的一点是：Skill 不是独立智能体。 它封装指令、资源与工具权限；除非 Frontmatter 对调用方式作出限制，否则由 Claude 或你来决定何时调用。
如果你还记得“自定义斜杠命令”（
.claude/commands/*.md）：它们已经并入 Skills。.claude/commands/deploy.md文件和.claude/skills/deploy/SKILL.mdSkill 都会创建/deploy，旧命令文件也仍然有效。Skills 是推荐格式，因为它支持辅助文件、调用控制以及更丰富的 Frontmatter。如果两者定义了同名命令，Skill 优先。
2. Skill 的文件结构与位置
Skills 既可以按项目管理，也可以在整台机器上全局管理：
| 作用域 | 位置 | 适用范围 |
|---|---|---|
| 个人 | ~/.claude/skills/<name>/SKILL.md |
你的所有项目 |
| 项目 | .claude/skills/<name>/SKILL.md |
仅当前项目（通过 Git 共享） |
| 插件 | <plugin>/skills/<name>/SKILL.md |
启用了该插件的所有位置 |
文件必须准确命名为 SKILL.md，而且 Skill 是一个目录，不是单个文件。这个目录可以携带辅助材料，只在需要时加载：
code-review/
├── SKILL.md # 必需：Frontmatter + 指令
├── references/ # 详细文档，按需加载
├── scripts/ # 可执行辅助程序（运行，但不载入上下文）
└── assets/ # 模板、静态资源
在我看来，这是相较旧版单文件格式最实用的改进。尽量把 SKILL.md 控制在约 500 行以内，把大段参考资料放进 references/。Skill 正文加载后会在整个会话中留在上下文里，因此每一行都会持续产生 Token 成本。
关键：YAML Frontmatter
---
name: code-review
description: 对照 .claude/rules/ 审查代码，找出违反架构和约定的问题。
argument-hint: "[path] [--staged|--branch] [--fix]"
allowed-tools: Read Glob Grep Bash(git *)
---
☝️ description 字段依然至关重要。Claude 通常能看到可用 Skills 的名称和描述，并通过这些元数据判断哪一个与当前任务有关。如果你说“审查我的代码”，系统会拿这项请求与 Skill 描述进行匹配，所以描述必须包含明确、便于检索的关键词。
在看表格之前，还应了解一个区别：Agent Skills 标准定义了可移植的核心字段（name、description、license、compatibility、metadata、allowed-tools）。下面其余字段——argument-hint、disable-model-invocation、user-invocable、context——则是 Claude Code 扩展。这张表只介绍本文用到的字段，并未穷尽 Claude Code 的全部选项（此外还有 when_to_use、model、paths、hooks 等）：
| 字段 | 作用 |
|---|---|
name |
显示名称（默认使用目录名） |
description |
自动调用的触发依据。为兼容其他工具，请控制在 1,024 个字符以内 |
argument-hint |
输入 /name 后显示的自动补全提示 |
allowed-tools |
Skill 运行期间 Claude 无需申请权限即可使用的工具（标准要求以空格分隔；Claude Code 也接受逗号） |
disable-model-invocation |
true = 只有你能触发；Claude 绝不会自动调用 |
user-invocable |
false = 不显示在 / 菜单中；仅供 Claude 使用的背景知识 |
context: fork |
在隔离的子智能体上下文中运行 Skill |
其中两个字段表达了旧格式无法描述的设计决策：谁有权扣动扳机。 对部署、提交、发送消息等会产生副作用的工作流，应设置 disable-model-invocation: true，避免 Claude 自行认定“现在正适合部署”。对于纯背景知识，则设置 user-invocable: false，让它不出现在命令菜单中。
3. 真实示例：/code-review Skill
这篇文章 1 月版本中的架构审查 Skill，至今仍是我每天都在使用的工具——只是现在已经成熟了许多。下面是我目前生产环境中 /code-review Skill 的 Frontmatter：
---
name: code-review
description: 对照 .claude/rules/ 审查代码，找出违反架构和约定的问题。
支持 --staged、--head、--last、--today、--branch 作用域选项。
添加 --fix 可自动修正。
argument-hint: "[path] [--staged|--head|--last|--today|--branch] [--fix]"
allowed-tools: Read, Glob, Grep, Edit, Bash(git *), Bash(find *)
---
当前版本依赖两项 1 月时还不存在的功能：
1. 参数。 Skill 正文中的 $ARGUMENTS 会替换为你在命令后输入的全部内容，因此一项 Skill 就能覆盖多种范围：
| 调用方式 | 审查范围 |
|---|---|
/code-review |
最近 5 次提交中变更的文件 |
/code-review src/user/ |
指定目录 |
/code-review --staged |
提交前的最终检查 |
/code-review --branch |
创建 PR 之前，对比当前分支与 main |
/code-review --staged --fix |
自动修复发现的问题 |
2. 动态上下文注入。 !`command` 占位符会在 Claude 看到 Skill 之前执行，并由命令输出替换。我的 Skill 用它预先列出规则文件和已变更文件：
- 项目规则：!`find .claude/rules -name "*.md" | sort`
- 已暂存文件：!`git diff --name-only --cached`
Claude Code 客户端会在预处理阶段执行这些命令；模型最终只会收到已展开的结果，作为 Skill 指令的一部分。这样可以消除整整一类“模型忘了先检查 X”的失败。
📎 完整可用示例：code-review SKILL.md（归档副本）——把它保存为项目中的 .claude/skills/code-review/SKILL.md。创建 /code-review 命令的是目录名。
Claude Code 已经内置了一项
/code-reviewSkill。在个人或项目级添加自己的code-reviewSkill 会覆盖内置版本——这正是我想要的结果：让审查由我自己的规则文件驱动，而不是采用通用规则。
这项 Skill 为什么强大
1、规则驱动的检查清单——Skill 会动态加载 .claude/rules/，而不是把政策硬编码进去。因此，同一个 Skill 能用于所有项目，并始终与当前规则文件保持一致。
2、严重程度定义——CRITICAL/WARNING/SUGGESTION 优先级可以避免注意力被琐碎问题淹没。
3、明确的执行流程——五步操作程序让审查过程更加稳定。
4. 输出示例
在终端运行 /code-review，会得到类似下面的结果：
> /code-review src/user/api/user_router.py
🔍 正在审查：src/user/api/user_router.py
## 发现架构违规
### 🚨 严重（2）
**第 45 行**：发现直接导入 Repository
- 发现：`from src.user.repositories.user_repository import UserRepository`
- 修复：删除这个导入，改用 Service 层。
**第 78 行**：API 层中存在业务逻辑
- 发现：`if user.age >= 18 and user.verified:`
- 修复：把这段验证移至 UserService.validate_user_eligibility()
### ⚠️ 警告（1）
**第 23 行**：手动实例化了 Service
- 发现：`service = UserService()`
- 修复：使用 `service: UserService = Depends(get_user_service)`
### 💡 建议（1）
**第 12 行**：建议添加返回类型注解
- 当前：`async def get_user(user_id: int):`
- 建议：`async def get_user(user_id: int) -> StandardResponse[UserResponse]:`
---
汇总：2 个严重问题、1 个警告、1 条建议
运行 `/code-review --fix` 自动修复适用的问题。
一条命令，就能根据项目已经记录的规则完成可重复的第一轮架构审查。它不能取代人工审查，却可以在 Pull Request 到达另一位开发者之前，捕捉常见违规。
安全说明：信任 Skill 之前先审查
让 Skills 变得强大的两项功能，也正是它们值得审计的原因。Skills 是可执行的工作流定义，而不是被动文档：
• allowed-tools 会在 Skill 运行期间预先批准工具使用，不再弹出权限提示。
• !`command` 这样的动态上下文表达式会在预处理期间运行，发生在渲染后的 Skill 内容到达模型之前。
• 对于陌生仓库中签入的 Skill，应当先阅读，再同意信任工作区。（你可以通过 disableSkillShellExecution 设置彻底禁用 Shell 预处理。）
• 权限应尽量收紧：Bash(git *) 优于 Bash(*)，并且只列出流程确实需要的工具。
5. Skills 在哪些地方价值最大
① 保持代码质量一致
人工审查者的状态会随心情和精力变化。一项定义完善的 Skill 每次都会使用同一份检查清单，减少差异，也降低常见遗漏的概率。
② 封装复杂工作流
涉及多个文件的任务（例如添加新 API 端点需要 Router、Service、Schema 和测试文件），可以封装成一项 Skill，从而减少漏掉某个步骤的可能。
③ 把知识变成资产
把你的设计理念写入 Skill 文件，再通过 Git 共享。初级开发者也能生成始终符合已有资深工程师指南的代码。而且，Skills 遵循开放标准，你编码进去的标准作业程序不会被锁在某一种工具里。
6. 实用模式
下面这些都是我当前 ~/.claude/skills/ 和项目 .claude/skills/ 目录中真实存在的 Skills，并非假设示例：
| Skill 命令 | 作用 |
|---|---|
| /code-review | 对照 .claude/rules/ 检查架构违规，按严重程度分类，并支持 --fix |
| /commit-push | 暂存变更、生成 Conventional Commit 消息、确认并推送 |
| /create-post | 按全部内容约定搭建新博客文章骨架（Slug 规则、图片目录、Frontmatter Schema） |
| /feature-image | 裁剪封面并在文件大小预算内转换为 16:9 WebP |
| /review-skill | 元 Skill：对照开放标准审计 SKILL.md 文件，并支持 --fix |
注意最后一行所体现的模式：一旦流程知识写进文件，你就可以创建用于维护其他 Skills 的 Skills。
7. 设计 Skills 的关键建议
1、认真编写描述——这是 Claude 决定何时自动加载 Skill 的主要信号。既要说明 Skill 做什么，也要说明什么时候使用：“审查代码是否符合整洁架构”要优于“代码审查”。
2、链接 Rules——不要在 Skill 内重复政策，而应加载它们：.claude/rules/ 是唯一信息源，Skill 则是应用规则的程序。
3、明确列出检查项——“审查这段代码”会产生不稳定的结果；“检查以下 5 项”才能带来可靠性。
4、定义严重程度——并非所有问题都同等重要，应在 Skill 中写明优先级判断标准。
5、加入验证步骤——最后始终执行“验证修改后的代码能否构建”或“运行 Lint”之类的检查。
6、保持 SKILL.md 精简——控制在约 500 行以内。把深度参考资料移至按需加载的 references/ 文件；Skill 正文会在整个会话中占用上下文。
7、控制触发者——部署、提交、发布等带副作用的工作流应设置 disable-model-invocation: true。护栏应写进 Frontmatter，而不是寄希望于模型自觉。
8、与 MCP 结合——如果你已经连接了 GitHub、数据库等外部工具的 MCP 服务器，就可以加入“编写代码之前先查询数据库 Schema”之类的指令，实现更智能的自动化。
结论
Claude Code Skills 能把反复说明的指令转变为可复用、受版本控制的工作流。
它的质量并不太取决于提示词有多巧妙，更取决于你是否清楚地定义了 Claude 应当遵循的流程。
如果团队在代码审查中反复解释相同约定，那么这些约定就很适合封装为 Skill。先从一项范围明确的工作流开始，用真实任务测试，再随着流程变化不断改进。
