Claude Code Skills：SKILL.md 的工作方式与加载位置

Claude Code 技能是包含 SKILL.md 文件的文件夹。文件的 YAML frontmatter 指定技能何时适用，Markdown 正文则写明指令。Claude Code 始终能看到各技能的描述，只在使用技能时加载完整正文；你也可以输入 /skill-name 手动运行任意技能。^[1] 自定义斜杠命令现在采用相同机制：.claude/commands/deploy.md 和 .claude/skills/deploy/SKILL.md 都会创建 /deploy，旧命令文件仍可使用。^[1]

Anthropic 对何时编写技能的建议很实用：当你反复把同一份检查清单或流程粘贴到聊天中，或 CLAUDE.md 中的某一节已从事实说明变成操作流程时，就适合创建技能。CLAUDE.md 在每次会话都会加载；技能正文在运行前几乎没有开销。^[1]

一个最简 Claude Code 技能

技能只需要一个目录和一个文件。下面的技能根据最近提交起草发布说明。将其保存为 ~/.claude/skills/release-notes/SKILL.md：

---
description: Drafts release notes from recent git commits. Use when the user asks for release notes, a changelog entry, or what shipped.
disable-model-invocation: true
---

## Recent commits

!`git log --oneline -30`

## Instructions

Group the commits above into Added, Changed and Fixed. Write one line per change in plain language. Skip merge commits.

目录名会成为命令，因此输入 /release-notes 即可运行。!`...` 这一行用于动态注入上下文：Claude Code 会先运行命令，将输出放入技能，再让 Claude 读取，所以发布说明来自真实的提交历史。^[1] disable-model-invocation: true 会阻止 Claude 自行启动技能，适合你希望手动触发的操作。

Claude Code 技能从哪里加载

选择的文件夹决定谁能使用该技能：^[1]

位置	路径	使用范围
个人	`~/.claude/skills/<name>/SKILL.md`	你本人，在本机所有项目中可用
项目	`.claude/skills/<name>/SKILL.md`	提交后，仓库中的所有协作者均可使用
嵌套目录	`<subdir>/.claude/skills/<name>/SKILL.md`	在该文件夹或其下级目录启动的会话
插件	`<plugin>/skills/<name>/SKILL.md`	启用插件的用户，通过 `/plugin-name:skill-name` 使用
企业	受管理的设置目录	组织部署范围内的所有用户
claude.ai 账户	账户中启用的技能	登录该账户的会话

有两个名称被保留。Claude Code 使用 ~/.claude/skills/synced/ 存放从 claude.ai 下载的技能，并跳过你以该文件夹名称创建的技能。在插件之外，名为 anthropic-skills 或以 anthropic-skills: 开头的文件夹不会加载。^[1]

frontmatter 控制什么

所有字段均为可选，Anthropic 仅推荐填写 description。Claude Code 会忽略拼写错误的字段名且不报错，因此请准确复制名称。^[1] 对行为影响最大的字段包括：

description 决定 Claude 如何判断是否使用技能。把主要用途放在最前面：它与 when_to_use 在技能列表中合计最多显示 1,536 个字符，超出部分会被截断。
disable-model-invocation: true 将技能设为仅手动调用。描述也会移出上下文，因此在你输入命令之前没有开销。
user-invocable: false 则相反：只有 Claude 能加载技能，技能会从 / 菜单中消失。Anthropic 建议将其用于旧系统工作原理等背景知识。
allowed-tools 为运行技能的当前轮次预先批准工具。授权在你发送下一条消息时结束。
paths 将自动加载限制为匹配的文件，context: fork 则让技能在子智能体中运行。

model 和 effort 会改变本轮剩余时间使用的模型和推理强度，但不会把变更保存到设置中。^[1]

技能占用多少上下文

Anthropic 将其分为三个层级。每个技能的名称和描述会在启动时加载，每个技能约 100 token。SKILL.md 正文在技能触发时加载；Anthropic 表格将这一层列为少于 5,000 token。附带文件在 Claude 读取前不产生开销，脚本代码也不会进入上下文，只有输出会进入。^[2]

技能运行后，其内容会作为一条消息留在对话中，Claude Code 不会在后续轮次重新读取文件。自动压缩后，Claude Code 会重新附上每个技能最近一次运行的内容，在共享的 25,000-token 预算内，按从新到旧的顺序保留每个技能的前 5,000 token。如果在一次长会话中使用了很多技能，最早的内容可能被移除。^[1] 必须贯穿整个任务的规则，应写成常驻指令并放在文件靠前的位置。

Claude Code 之外的 Claude 技能

相同格式也能在其他 Claude 产品界面中运行，但各自规则不同：^[2]

claude.ai 内置 Anthropic 的 PowerPoint、Excel、Word 和 PDF 技能，无需设置即可启用。启用代码执行的 Pro、Max、Ultra、Team 和 Enterprise 套餐可在 Settings > Features 下以 zip 文件上传自定义技能。每次上传的技能仅对该用户可见。
Claude API 接收 skill_id，将其放在 container 参数中，并配合代码执行工具使用。预置 ID 为 pptx、xlsx、docx 和 pdf；自定义技能通过 /v1/skills 接口管理，在工作区内共享。
Claude Code 支持自定义技能，但不支持预置文档技能。

Anthropic 文档对同步的说明存在矛盾。Agent Skills 概览称，自定义技能不会在不同产品界面之间同步，Claude Code 技能也独立于 claude.ai 和 API。^[2] 更新的 Claude Code 页面则将 claude.ai 账户中启用的技能列为终端会话的加载来源，前提是会话登录该账户；技能会下载至 ~/.claude/skills/synced/。^[1] 如果依赖这项同步，应先确认技能出现在 / 菜单中，再围绕它构建工作流。

将 Claude Code 技能迁移到 claude.ai 或 Skills API 需要注意。这些途径只接受 Agent Skills 开放标准中的六个 frontmatter 字段：name、description、license、compatibility、metadata 和 allowed-tools。其他任何字段，例如 disable-model-invocation 或 argument-hint，都会让上传报“Unexpected key(s)”错误，而不是被忽略；!`command` 注入等 Claude Code 专属功能也不会在那里运行。^[1]^[3] 上面的发布说明示例需要将这两部分都移除。

Anthropic. Extend Claude with skills (Claude Code documentation). 2026 年 11 月 4 日获取自 code.claude.com/docs/en/skills
Anthropic. Agent Skills overview. 2026 年 11 月 4 日获取自 platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
Agent Skills. Agent Skills open standard. 2026 年 11 月 4 日获取自 agentskills.io

Claude Code Skills：SKILL.md 的工作方式与加载位置

一个最简 Claude Code 技能

Claude Code 技能从哪里加载

frontmatter 控制什么

技能占用多少上下文

Claude Code 之外的 Claude 技能

安装他人编写的技能

FAQ

Claude Code 技能与斜杠命令是同一回事吗？

Claude Code 能使用 PowerPoint 和 Excel 技能吗？

为什么 Claude 忽略了我的技能？

使用自己的模型接入方式运行 Claude Code 技能

参考资料