如果你总是把同一套指令反复粘贴进 Claude Code,不妨交给一个 skill 来保存。本指南将介绍 agent skill 是什么、文件该放在哪里,以及如何编写和测试一个小型 skill。此外还会讲到如何从插件市场安装 skill,以及哪些错误会导致 skill 无法加载。
以下所有内容均已于 2026 年 11 月对照 Anthropic 官方文档核实。Claude Code 更新频繁,请以文中链接的文档为准。
什么是 agent skill
skill 就是一个文件夹,里面有一个名为 SKILL.md 的文件。这个文件分为两部分:顶部是夹在 --- 标记之间的 YAML frontmatter,包含 name 和 description;下面是普通的 Markdown 指令,Claude 在运行该 skill 时会照着执行。
skill 文件夹里还可以放其他文件,例如参考笔记、模板或脚本。
skill 是分阶段加载的,Anthropic 称之为渐进式披露(progressive disclosure)。启动时,Claude 只加载每个 skill 的名称和描述;skill 被触发时才加载完整指令,而附带的文件只有在 Claude 打开时才会加载。因此,你可以安装很多 skill,而不会占满上下文窗口。
准备工作
- 已安装并登录 Claude Code
- 一个终端和一个文本编辑器
- 一个用于测试的 git 项目(示例 skill 用来撰写 commit 信息)
第 1 步:选择 skill 的存放位置
skill 保存在哪里,决定了哪些会话能看到它。最常用的两个位置是:
- 个人:
~/.claude/skills/<skill-name>/SKILL.md。在这台电脑上的所有项目中都可用。 - 项目:仓库内的
.claude/skills/<skill-name>/SKILL.md。在该仓库的会话中可用。提交到仓库后,团队成员也能使用。
此外还有企业级、嵌套和插件等位置。如果个人 skill 和项目 skill 同名,以个人 skill 为准。
需要注意一点:云端会话和 Cowork 不会读取 ~/.claude/skills/ 中的个人 skill。文档建议,在这些场景下要在 claude.ai 账户中启用该 skill,或者将它提交到仓库。
第 2 步:创建文件夹
我们来创建一个名为 commit-message 的个人 skill。
mkdir -p ~/.claude/skills/commit-message
预期结果:命令没有任何输出,空文件夹已经创建好。
第 3 步:编写 SKILL.md
创建 ~/.claude/skills/commit-message/SKILL.md 并粘贴以下内容。文件名必须严格为 SKILL.md。
---
name: commit-message
description: Writes a clear git commit message from the staged changes. Use when the user asks for a commit message, wants to commit their work, or asks how to describe their changes.
---
# Commit message writer
1. Run `git diff --staged` to see what is staged.
2. If nothing is staged, say so and stop.
3. Write a subject line in the imperative mood, under 72 characters.
4. Leave one blank line, then add a short body that explains why the change was made.
5. Show the message in a code block. Do not run `git commit` unless the user asks.
关于 frontmatter 的几点说明:
name会成为你输入的命令。如果省略,Claude Code 会使用文件夹名称。description是 Claude 判断是否使用该 skill 的依据。先写 skill 做什么,再写什么时候使用。- 开头的
---必须位于文件的第一行,否则 Claude Code 会把整个文件当作普通内容处理。
Claude Code 还支持更多字段,例如 disable-model-invocation 和 allowed-tools。但 claude.ai 上传和 Skills API 只接受六个字段:name、description、license、compatibility、metadata 和 allowed-tools。只使用 name 和 description,可以让你的 skill 更具可移植性。
第 4 步:测试
在任意 git 项目中暂存一个小改动,然后启动 Claude Code。
git add .
claude
触发 skill 有两种方式。第一种是用自然语言提问,让 Claude 根据描述自动选用:
Can you write a commit message for what I've staged?
或者直接按名称调用:
/commit-message
预期结果:Claude 运行 git diff --staged,并在代码块中返回一行标题和简短的正文。
编辑后无需重启。Claude Code 会监视 ~/.claude/skills/ 和项目中的 .claude/skills/,并在当前会话中自动应用更改。
第 5 步:添加辅助文件(可选)
随着 skill 内容增多,可以把细节移出 SKILL.md。文档建议将其控制在 500 行以内。目录结构可以是这样:
commit-message/
├── SKILL.md
├── examples.md
└── scripts/
└── check-length.sh
在 SKILL.md 中链接这些额外文件,让 Claude 知道何时打开它们。脚本会被执行,而不会被加载进上下文。
第 6 步:从插件市场安装 skill
你不必亲手编写每一个 skill。在 Claude Code 中,skill 可以打包在插件里,而插件来自插件市场(marketplace)。Anthropic 的官方市场 claude-plugins-official 会在你首次启动交互式会话时自动添加。
Anthropic 在 GitHub 上的公开 skills 仓库也可以作为市场添加。其 README 给出了以下命令:
/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills
在会话中,/plugin install 会打开插件面板,让你在安装前查看插件并选择作用范围。插件中的 skill 带有命名空间,因此插件 my-plugin 中名为 review 的 skill 要以 /my-plugin:review 的形式运行。
Skills、MCP 服务器与 CLAUDE.md 的区别
CLAUDE.md 存放每次会话都会加载的固定事实和规则,例如“use pnpm”(使用 pnpm)或“tests live in tests/”(测试放在 tests/ 中)。由于它始终在上下文中,请保持简短。
Skills 存放只在部分时候才需要的流程和参考资料。Anthropic 的建议是:当 CLAUDE.md 中某一部分已经发展成一套流程,或者你总是把同一份清单粘贴到聊天中时,就该把它做成 skill。
MCP 服务器把 Claude 连接到外部工具和数据,例如数据库、问题跟踪系统或设计应用。skill 可以告诉 Claude 如何用好这些工具,但它本身并不提供连接。
Claude Code 之外的 skill
同样的格式适用于 Claude 的各个产品。根据 Anthropic 的概述,自定义 skill 可以在 Claude Code 中创建、通过 Claude API 上传,或在 claude.ai 设置中添加。上传到 claude.ai 的 skill 需要另外单独上传到 API。
关于安全的提醒
skill 不只是文本。它可以包含脚本,还能引导 Claude 运行命令、调用工具。Anthropic 的建议是只使用可信来源的 skill,也就是你自己编写的或来自 Anthropic 的。如果要试用其他来源的 skill,请先阅读每一个文件(包括脚本),留意是否有意外的网络请求或文件访问。
常见错误及解决方法
Claude 从不自动使用该 skill
常见原因是描述太模糊。“Helps with git”这样的描述几乎没有可匹配的信息。请写清楚 skill 做什么,以及人们实际会说的用语。你也可以问 Claude “What skills are available?”(有哪些可用的 skill?)来确认它已加载,并用 /skill-name 直接运行。
skill 根本没有出现
检查路径和大小写。路径必须是 ~/.claude/skills/<skill-name>/SKILL.md,文件要放在自己的文件夹里,而不是直接散放在 skills/ 中。文档还列出了名称中不能包含的字符,例如 <、>,以及开头或结尾的空格。
frontmatter 格式有误
如果 YAML 无法解析,Claude Code 仍会加载正文,但元数据为空。/skill-name 仍然可用,但 Claude 无法匹配你的描述。用 claude --debug 启动 Claude Code 可以查看错误,或者运行 claude plugin validate ~/.claude/skills 找出有问题的文件。
名称格式规则
对于 claude.ai 和 API,name 只能使用小写字母、数字和连字符,长度不超过 64 个字符,并且不能包含 anthropic 或 claude 这两个词。description 最多 1,024 个字符。另外,不要把文件夹命名为 synced,Claude Code 将其保留给从 claude.ai 下载的 skill。
更改没有生效
对现有 skill 的修改无需重启即可加载。但如果你新建了一个会话启动时还不存在的顶层 skills 目录,请运行 /reload-skills。对于新插件,请运行 /reload-plugins 或重启 Claude Code。
skill 触发得太频繁
让描述更具体一些。如果你只想手动运行它,可以在 frontmatter 中添加 disable-model-invocation: true。
总结
一个 skill 就是一个文件夹、一个 SKILL.md 文件,再加上一段好的描述。从你每周都要重复的一项任务开始,把步骤写下来,然后分别用自然语言请求和 /skill-name 进行测试。安装任何东西之前,先审查再信任。
更多 Claude 相关内容:查看我们按任务分类的全部 Claude 和 Anthropic 指南。
资料来源与官方文档
链接最后检查于 2026 年 11 月 15 日。





写评论