Claude Code v2.1.157：放入 SKILL.md，开箱即用

Claude Code v2.1.157 无须市场即可从 .claude/skills/ 自动载入 Skills 与 Plugins。本文提供分步配置方法和 SKILL.md 示例。

作者：Jason Zhou（结构化数据中的作者：AI Jason）
发布于：2026-06-02
阅读时间：8 分钟
来源：https://www.aibuilderclub.com/blog/claude-code-auto-load-skills-v2157

准确性说明（检查于 2026-07-22）：v2.1.157 的发布日期及三项主要变更已经核实，但该版本具体引入的是自动载入 .claude/skills 中的 Plugins；原文把它泛化为独立 Skill 发现机制的首次推出。当前文档显示，claude plugin init my-tool 会创建 ~/.claude/skills/my-tool，并未记录原文展示的 --with 参数。实时检测要求顶层 Skills 目录在会话启动时就已存在；/reload-plugins 用于 Plugin 组件，当前参考文档中没有 /reload-skills。约 100/约 5K Token 只是示意数字；原文关于 CLAUDE.md 成本的描述省略了缓存因素；disallowed-tools 会在下一条用户消息后清除。自动调用与团队成员间完全相同的行为仍不具确定性。详见版本发布页、Skills 参考与 Plugins 参考。

Claude Code v2.1.157（发布于 2026 年 5 月 29 日）会在会话启动时，从 .claude/skills/ 目录自动载入 Skills 与 Plugins——无需市场、无需 --plugin-dir 参数，也无需手动安装。只要把一个包含 SKILL.md 的文件夹放进 .claude/skills/，启动新会话，Claude 就会识别它。此次更新还增加了用于创建脚手架的 claude plugin init <name>，以及 /plugin 参数自动补全。

Claude Code 于 5 月 29 日发布 v2.1.157，却把最实用的功能之一藏在了 Changelog 中：现在会自动载入 .claude/skills/ 目录中的 Skills 与 Plugins。不需要市场，不必每次启动都传入 --plugin-dir，也不需要配置。放入文件，就能使用。

大多数开发者会在 Release Notes 中一眼略过，但这是个错误。这是 Claude Code 最接近让持久化、项目专用行为拥有原生体验的一次，而不是像后来硬接上去的功能。

如果每次会话开始时，你都要重新向 Claude 解释文件夹结构、命名约定或部署流程，这次更新将终结这种重复。

Claude Code v2.1.157 改变了什么？

此次发布包含三项改动，显著提升了 Skills 系统的实用性。

1. 从 .claude/skills/ 自动载入。 在 v2.1.157 之前，使用本地 Plugin 必须发布到市场，或在每次启动时传入 --plugin-dir。两种方式都增加了摩擦，因此大多数开发者干脆不用。现在，Claude Code 会在会话启动时扫描 .claude/skills/，载入发现的所有有效 Skills 或 Plugins。无需参数，也无需安装步骤。

它适用于两个层级：

作用域	路径	行为
项目	仓库中的 `.claude/skills/`	只在该项目中载入。提交到 Git 后，每位队友都能获得。
个人	Home 目录中的 `~/.claude/skills/`	在你电脑上的所有项目中载入。

Skills 还会沿父目录向上查找到仓库根目录，因此即使从子目录启动 Claude，也能识别项目根目录定义的 Skills。

2. claude plugin init <name> 脚手架。 运行该命令，即可在 .claude/skills/ 中获得可用的 Plugin 骨架，无须编写样板代码。它支持 --with skills,agents,hooks,mcp 参数，用于创建指定组件。

3. /plugin 参数自动补全。 输入时会自动显示子命令、已安装 Plugin 名称，以及已知市场中的 Plugins。

自动载入 Skills 为什么对开发者很重要？

下面是真实工作中会遇到的问题。

你在后端仓库中打开新 Claude 会话，输入：“嘿，我们的函数使用 snake_case，测试放在 /tests 下并镜像 /src 结构；绝不要直接修改数据库 Schema，始终编写 Migration。”Claude 点头。你完成并交付了一项工作。第二天打开新会话，又输入同一段话。

一个月下来，这意味着每次会话都要花数百 Token 和几分钟重新熟悉环境。更糟的是，对话变长后，Claude 偶尔会在会话中途偏离约定，因为相关指令只存在于对话，而没有扎根于项目。

从 .claude/skills/ 载入 Skills 可以从三个方面解决这个问题：

1、它们扎根于项目。 属于项目，而非聊天；每次会话都会自动重新载入。
2、它们按需载入。 不同于 CLAUDE.md（每轮都会载入），Skills 使用渐进式披露。Claude 会看到 Skill 名称与描述（约 100 Token），只有任务匹配时才载入完整指令（约 5K Token），为真正重要的工作节省上下文。
3、它们受版本控制。 把 .claude/skills/ 提交到仓库。每位团队成员无须进行个人配置，就能获得完全相同的 Claude 行为。新工程师接触的 Claude 从一开始就了解项目。

如何设置自动载入的 Skills？（不到五分钟）

简单方式——只使用一份 SKILL.md：

你不需要完整 Plugin 结构，一个只包含 SKILL.md 的文件夹就能工作：

mkdir -p .claude/skills/project-conventions

创建 .claude/skills/project-conventions/SKILL.md：

---
name: Project Conventions
description: 在本项目中编写或审查代码时使用。涵盖命名、测试与数据库规则。
---

## 代码风格
Python 函数使用 snake_case。始终添加类型提示。
函数不超过 50 行——超过时应拆分。

## 测试
使用 pytest 编写测试。在 /tests 下镜像 /src 结构。
每个新函数至少需要一项测试。

## 数据库
绝不要直接修改 Schema，始终编写 Alembic Migration。
Migration 文件放在 /migrations 中，并采用具有描述性的名称。

Claude Code 101 · 2026 年 6 月重制
理论已经读完，现在通过课程真正交付。
三个引导实验——一个真实网站、一个包含 Stripe 支付的全栈应用，以及一套经测量节省 10 倍 Token 的业务自动化——另附模板库：CLAUDE.md 模板、9 项 Skills、5 份子智能体定义、Hooks 工具包与安全审计提示词。
开始使用 Claude Code 交付

PR 审查

审查 PR 时：检查类型提示、函数长度、测试覆盖率，并确认没有直接修改 Schema。

就这么简单。下一次 Claude Code 会话中，这项 Skill 会自动载入。当任务与 Frontmatter 描述匹配时，Claude 会调用它。

完整 Plugin 方式——使用 claude plugin init：

如果配置较为复杂，需要让 Agents、Hooks 或 MCP 服务器与 Skills 一同存在：

claude plugin init my-project-tools --with skills,hooks

它会创建一套完整 Plugin 结构：

.claude/skills/my-project-tools/
├── .claude-plugin/
│   └── plugin.json          # Plugin 元数据（名称、版本、描述）
├── skills/
│   └── my-project-tools/
│       └── SKILL.md          # Claude 遵循的指令
├── hooks/
│   └── hooks.json            # 事件处理程序
└── README.md

请注意：plugin.json 位于 .claude-plugin/ 内部，而非 Plugin 根目录。其他所有目录（Skills、Hooks、Agents）都位于根层级。

plugin.json 清单其实是可选项。即使省略，Claude Code 也会自动发现默认位置中的组件，并根据目录名推导 Plugin 名称。

**热重载：**会话期间对 Skills 的修改会自动生效。运行 /reload-plugins 可以在不重启的情况下强制刷新。

CLAUDE.md 与 Skills 有什么区别？

这是大多数开发者容易弄错的问题，而且会真正影响 Token 成本。

	CLAUDE.md	Skills（SKILL.md）
载入方式	始终载入：每次会话、每轮对话	按需载入：仅在任务匹配时载入
Token 成本	每条消息均包含完整文件大小	空闲时约 100 Token，激活时约 5K
最适合	项目事实：技术栈、约定、架构规则	流程：代码审查清单、部署工作流、脚手架
作用域	每个项目一份文件	多项 Skills，可跨项目移植
心智模型	“项目大脑”——Claude 需要知道什么	“可复用能力”——Claude 需要做什么

**经验法则：**如果你的想法以“在这个项目中，我们总是……”开头，它就属于 CLAUDE.md。如果描述的是只在部分场景适用的多步骤工作流，那就是 Skill。

如果 CLAUDE.md 已经超过 500 行，其中为十项不同任务写满详细指令，那么每条消息都在为很少相关的流程支付完整 Token 成本。请把它们移到按需载入的 Skills 中。

CLAUDE.md 与 Skills 结合后可以构成完整图景：CLAUDE.md 处理项目级上下文，Skills 处理可复用行为。你可以像对代码进行版本控制一样，对 Claude 在项目中的行为进行版本控制。

可以用 Claude Code Skills 构建什么？

1. 强制执行约定。 就像上面的例子。不必每次会话都重新解释命名规则、文件夹结构与代码风格。把它写进 SKILL.md，提交，完成。

2. 自定义斜杠命令。 把 /deploy、/review 或 /test 定义成由 Skill 支持的 Commands，执行你的特定工作流步骤。Claude 清楚知道项目需求，因此能够保持一致执行。

---
name: deploy
description: 运行本项目的生产环境部署清单。
---

## 部署清单
1. 运行 npm test 并确认所有测试通过
2. 使用 git status 检查未提交改动
3. 通过 npm run build 构建生产 Bundle
4. 运行 ./scripts/deploy-prod.sh
5. 验证 https://api.example.com/health 上的健康检查

3. 通过 disallowed-tools 构建安全审计工作流。 Skills 可以限制激活期间 Claude 有权使用的工具。下面是一项只读代码审查 Skill：

---
name: code-review
description: 审查代码质量问题，但不进行修改。
disallowed-tools: Bash, Write, Edit
---

审查代码并报告问题，不要修改任何文件。
重点检查：类型安全、错误处理、测试覆盖缺口，
以及潜在安全问题。

disallowed-tools Frontmatter（随 v2.1.152 推出）会在 Skill 激活期间，从 Claude 可用工具池中完全移除所列工具。这是在 Skill 层实现最小权限，而不只是一条提示词指令。

4. 共享智能体模式。 如果团队已经形成有效的调试工作流、PR 检查清单或数据迁移流程，只需编码一次。下一位接触该代码路径的人会获得相同的起点。个人 Skills（~/.claude/skills/）会陪你跨越各个项目；项目 Skills（.claude/skills/）则会跟随仓库。

Skills 与 Plugins：什么时候需要完整 Plugin？

这是一个常见的困惑来源。区别如下：

	简单 Skill	完整 Plugin
最少文件	1 个（SKILL.md）	1 个（SKILL.md）+ 可选 `.claude-plugin/plugin.json`
可以包含	只有指令	Skills + Agents + Hooks + MCP 服务器 + 自定义 Commands
命名空间	`/skill-name`	`/plugin-name:skill-name`
最适合	单一用途指令	与团队共享的多组件工具包
创建脚手架	`mkdir` + 创建 SKILL.md	`claude plugin init <name>`

从简单 Skill 开始。 以后随时可以添加 .claude-plugin/plugin.json 清单与其他组件目录，升级成完整 Plugin。

更宏观的图景：行为即代码

这次更新是 Claude Code 整体转变的一部分。智能体行为正在变成可以版本化、在 PR 中审查并回滚的东西：

• .claude/skills/ 中的 Skills：用于可复用能力
• CLAUDE.md：用于项目上下文
• Hooks：用于事件驱动自动化（工具执行前/后）
• Agents（子智能体定义）：用于委派专业任务
• Dynamic Workflows：用于并行任务编排

方向很明确：Claude 在项目中的行为应该像 CI 流水线一样可复现。请提交 .claude/ 目录，并像审查应用逻辑一样审查 Skills 的改动。

此次更新——无需市场摩擦即可从 .claude/skills/ 自动载入——移除了把智能体行为视为一等项目基础设施的最后一道重大障碍。

v2.1.157 中的其他修复

还有一些值得了解的稳定性改进：

• 修复后台智能体在系统睡眠/唤醒后报告错误日期的问题
• 修复 --resume 无法正确恢复后台子智能体的问题
• EnterWorktree 现在可以在会话中途切换 Claude 管理的 Worktree
• 智能体完成后，Worktree 会保持未锁定状态
• 由 claude agents 派发的会话现在会遵守 settings.json 中的 agent 字段
• 修复 VS Code、Cursor 与 Windsurf 集成终端中右键粘贴导致剪贴板内容重复的问题
• WSL：修复 Windows 11 中的图片粘贴与截图粘贴
• /terminal-setup 现在会禁用集成终端中的 GPU 加速，防止文字渲染乱码

完整 Changelog：github.com/anthropics/claude-code/releases/tag/v2.1.157

要点总结

• Claude Code v2.1.157 会从 .claude/skills/ 自动载入 Skills 与 Plugins——无需市场、参数或配置。
• **最简单的配置：**创建一个只含 SKILL.md 的文件夹，它就是有效 Skill。
• CLAUDE.md = 始终开启的项目事实。 Skills = 按需流程。两者都要用，但要知道各自用途。
• disallowed-tools Frontmatter 允许在 Skill 层强制执行最小权限（例如只读代码审查）。
• 把 .claude/skills/ 提交到 Git。 每位团队成员从第一天起都能获得相同的 Claude 行为。
• 从简单方案开始。 先写一份 SKILL.md；需要 Agents、Hooks 或 MCP 服务器时，再通过 claude plugin init 升级成完整 Plugin。

免费课程：掌握 AI Agent Engineering

Skills 解决的是如何向 Claude 提供持久的项目知识，但它们只是更大系统的一部分。上下文变长后，Claude 为什么会偏离约定？为什么向 CLAUDE.md 塞入更多指令有时反而让智能体表现更差？为什么一个包含 50 项工具的系统会失效，而只有 10 项工具时却运行良好？

这些都是上下文工程问题——免费的十天 AI Agent Engineering 课程会深入讲解。

课程覆盖完整技术栈——从智能体循环、工具系统到上下文工程与记忆。每天一节课，通过邮件发送。已有 1,200 多名开发者完成课程。

• **第 1～2 天：**每套生产级智能体（Claude Code、Cursor、Manus）背后的六支柱框架
• **第 3～5 天：**智能体循环、工具系统与上下文工程——包含真实代码
• **第 6～8 天：**记忆、多智能体编排，以及将一切整合起来的运行框架
• **第 9～10 天：**交付一套可用智能体 + 职业发展手册

Skills 会直接融入其中两个支柱：上下文工程（第 4 天——渐进式披露、按需载入与 Token 预算管理）和 Harness Engineering（第 8 天——权限系统、disallowed-tools 与生命周期 Hooks）。理解这些支柱，才是“我放入一份 SKILL.md，然后它就能用”与“我设计了一套能扩展到 15 名工程师的 Skills 架构”之间的差别。

开始免费课程

想更深入了解 Claude Code 工作流、Skills 架构及其背后的上下文工程原则？加入 AI Builder Club，获取完整课程、直播研讨会，并进入一个已有 1,200 多名 AI 产品开发者的社区。

加入 AI Builder Club →

来源：Claude Code v2.1.157 Release Notes，2026 年 5 月 29 日。Claude Code Skills 文档。Claude Code Plugins 文档。

常见问题

Claude Code 的 .claude/skills/ 目录是什么？

.claude/skills/ 是项目（或 Home 文件夹）中的目录，Claude Code 会从中自动发现并载入 Skills 与 Plugins。每个包含 SKILL.md 的子文件夹都会成为一项可用 Skill。项目级 Skills 只在相应项目中载入，位于 ~/.claude/skills/ 的用户级 Skills 则会在所有项目中载入。

创建 Claude Code Skill 需要 plugin.json 吗？

不需要。命名文件夹中的一份 SKILL.md 就是有效 Skill。.claude-plugin/plugin.json 清单是可选项，只有当你希望捆绑额外组件（Agents、Hooks、MCP 服务器）或发布到市场时才需要。

CLAUDE.md 与 SKILL.md 有什么区别？

CLAUDE.md 是每轮都会载入、始终开启的项目上下文，适合存放技术栈与编码约定等事实。SKILL.md 定义只在相关场景中载入的按需流程，适合代码审查、部署或脚手架等重复工作流。CLAUDE.md 每条消息都会付出完整文件的 Token 成本；Skills 被调用前则只占约 100 Token。

Claude Code Skills 能限制智能体使用哪些工具吗？

可以。在 SKILL.md 的 YAML Frontmatter 中添加 disallowed-tools: Bash, Write, Edit。这会在 Skill 激活期间从 Claude 的可用工具池中移除这些工具。该功能随 Claude Code v2.1.152 推出。

添加新 Skill 后需要重启 Claude Code 吗？

不需要。Skills 会在会话启动时被检测，但会话期间的改动也会通过热重载生效。可以运行 /reload-plugins 或 /reload-skills 强制刷新，无须重启。

Claude Code Skills 能自动调用，还是必须手动调用？

两者都可以。如果在 SKILL.md Frontmatter 中包含描述，当任务与描述匹配时，Claude 可以自动调用 Skill。你也可以像斜杠命令一样手动调用 Skills（例如 /deploy）。在 Frontmatter 中设置 disable-model-invocation: true 可阻止自动调用。

.claude/skills/ Plugins 能在 Cursor 与其他编辑器中工作吗？

.claude/skills/ 自动载入是 Claude Code 功能。不过，其他工具已经采用 SKILL.md 格式。Cursor 使用具有自身发现机制的类似 Skills 系统，OpenAI Codex 也已经采用 SKILL.md 规范。Skills 本身是可移植的 Markdown 文件。

项目级与用户级 Skills 如何交互？

.claude/skills/ 中的项目 Skills 只在该项目中载入，并通过 Git 共享。~/.claude/skills/ 中的用户 Skills 会在电脑上的每个项目中载入。两者会同时处于激活状态。Skills 还会沿父目录向上查找到仓库根目录，因此支持各 Package 拥有自己 Skills 的 Monorepo 配置。