如何在 Claude Code 中安装和使用 Agent Skills(SKILL.md 详解)

Claude Code agent skill 分步指南:SKILL.md 的作用、skill 存放在哪里、如何编写,以及如何修复无法加载的 skill。

Flat illustration of a folder holding a SKILL.md document plugging into a terminal window

如果你总是把同一套指令反复粘贴进 Claude Code,不妨交给一个 skill 来保存。本指南将介绍 agent skill 是什么、文件该放在哪里,以及如何编写和测试一个小型 skill。此外还会讲到如何从插件市场安装 skill,以及哪些错误会导致 skill 无法加载。

在 Mindloop Experience 观看:像高手一样配置 Claude Code:Skills、MCP 服务器 & 插件

以下所有内容均已于 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 日。

作者:Mindloop Editorial

The Mindloop Experience editorial team writes clear, carefully sourced explainers and how-tos on tech, science, money and culture, for anyone who likes to know how things actually work.

关于 Mindloop Experience

评论

写评论

更多来自 Mindloop Experience

查看 Mindloop Experience 的全部文章

最多可以鼓掌 50 次。