Skill

Skill 扩展了 Claude 能做的事。创建一个带指令的 SKILL.md 文件，Claude 就会把它加入自己的工具箱。Claude 在相关时会自动使用 Skill，你也可以用 /skill-name 直接调用。

当你总在聊天里粘贴同样的指令、检查清单或多步骤流程，或者 CLAUDE.md 里某一节已经从「事实」长成了「流程」时，就该创建 Skill。和 CLAUDE.md 不同，Skill 的正文只在用到时才加载，所以长篇参考资料在你需要之前几乎不花任何成本。

自定义命令已合并进 Skill。 .claude/commands/deploy.md 里的文件和 .claude/skills/deploy/SKILL.md 的 Skill 都会创建 /deploy 并以同样方式工作；现有的 .claude/commands/ 文件继续有效。Skill 增加了可选功能：放辅助文件的目录、控制由你还是 Claude 调用的前置信息等。

Claude Code 的 Skill 遵循 Agent Skills 开放标准（跨多个 AI 工具通用），并在其上扩展了调用控制、子智能体执行和动态上下文注入等功能。

内置 Skill

Claude Code 附带一组内置 Skill，如 /doctor、/code-review、/batch、/debug、/loop 和 /claude-api。它们是基于提示词的：给 Claude 详细的指令，让它用自己的工具来编排工作；而多数内置命令则是直接执行固定逻辑。调用方式和其他 Skill 一样，输入 / 加名字。多数内置 Skill 在每个会话都可用；用 disableBundledSkills 设置可以全部关闭。

运行并验证你的应用：三个内置 Skill 配合工作，启动应用并对照运行中的应用确认改动，而不只是跑测试：

/run 和 /verify 无需设置，会根据项目类型和 README、package.json、Makefile 推断启动方式。对于需要数据库、env 文件、图形会话等的项目，/run-skill-generator 会记录一份配方，并作为项目 Skill 提交到 .claude/skills/run-<name>/。

Claude API 项目：内置的 /claude-api Skill 为你的项目语言加载 Claude API 和 Managed Agents 的参考资料；当代码导入 anthropic 或 @anthropic-ai/sdk 时 Claude 也会自动激活它。可以在 Skill 名后接子命令，如 /claude-api migrate（把现有 Claude API 代码更新到较新的模型）。

创建你的第一个 Skill

这个例子创建一个总结 git 仓库中未提交改动并标出风险的 Skill。它在 Claude 读取之前就把实时 diff 拉进提示，所以回复基于你真实的工作区。

1. 在个人 Skill 目录里为它建一个目录（个人 Skill 对你所有项目可用）：

   mkdir -p ~/.claude/skills/summarize-changes

2. 每个 Skill 都需要一个 SKILL.md，包含两部分：--- 之间的 YAML 前置信息（告诉 Claude 何时使用）和 Claude 运行时遵循的 markdown 指令。目录名（或设置了的前置信息 name）就是你输入的命令。保存为 ~/.claude/skills/summarize-changes/SKILL.md：

   ---
   description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
   ---
   
   ## Current changes
   
   !`git diff HEAD`
   
   ## Instructions
   
   Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

   !`git diff HEAD` 这一行使用动态上下文注入：Claude Code 运行这条命令，并在 Claude 看到 Skill 内容之前用输出替换这一行。

3. 打开一个 git 项目，随便改一个文件，运行 claude。可以让 Claude 自动调用（问些匹配描述的话，比如「What did I change?」），或直接调用：/summarize-changes。

Skill 放在哪里

Claude Code 从启动目录和每一级父目录直到仓库根加载项目 Skill，所以在 packages/frontend/ 启动仍能拿到根目录定义的 Skill。比启动位置更深的子目录里的 Skill 不会在启动时加载，Claude 第一次读取或编辑那个子目录里的文件时才加载。不要把 Skill 文件夹命名为 synced 或 anthropic-skills（保留名）。

个人、项目、企业位置里的 <skill-name> 可以是指向别处目录的符号链接，Claude Code 从链接目标读取 SKILL.md；多个位置指向同一个目标时只加载一次。

同名时用哪一个

两个 Skill 的目录名或文件名相同时，/name 运行哪一个由来源决定：

所以项目里提交的 Skill 「不生效」时，先看看 ~/.claude/skills/ 里有没有同名的旧版本。

Cowork 和云端会话

Cowork 会话和云端会话（包括 routine）不读取你本机的 ~/.claude/skills/。它们加载为你的 claude.ai 账号启用的 Skill（在桌面端侧边栏的 Customize 或 claude.ai 的 Skill 设置里管理）；云端会话另外会加载克隆下来的仓库里已提交的 .claude/skills/。

只存在于本机 ~/.claude/skills/ 的 Skill，在 routine 里调用会报找不到。要让它在这些会话里可用：

• Cowork 和云端会话：在 claude.ai 账号里启用这个 Skill
• 云端会话：也可以把它提交到仓库的 .claude/skills/

桌面端的本地定时任务在你的机器上运行，所以会加载 ~/.claude/skills/。

从 claude.ai 同步的 Skill

在终端里用 claude.ai 账号登录时，Claude Code 会在会话开始时把账号启用的 Skill（你自己创建或开启的、组织提供的，以及 pdf、xlsx 等 Anthropic 内置 Skill）下载到 ~/.claude/skills/synced/，会话期间大约每 10 分钟检查一次变化，增删改都不用重启。终端同步需要 Claude Code v2.1.273 或更高版本；会话中途用 /login 登录的，要重启才开始同步。

• 同步是单向的：改 ~/.claude/skills/synced/ 里的文件不会保存到 claude.ai，下次同步还可能被覆盖。要改就去 claude.ai 改
• /skills 里同步的 Skill 列在 claude.ai sync 分组下
• 可以用短名 /<name> 或全名 /anthropic-skills:<name> 调用；短名被别的命令占用时只能用全名，/skills 列表下方会说明原因
• 不想在这台机器上同步，在用户设置里把 syncClaudeAiSkills 设为 false

删除 Skill：个人或项目 Skill 直接删除目录；企业 Skill 由管理员从托管设置目录删除；插件 Skill 禁用或卸载提供它的插件；内置 Skill 用 disableBundledSkills 或在 skillOverrides 里设为 "off"；从 claude.ai 同步的 Skill 要在 claude.ai 上关掉（手动删目录，下次同步会再下载回来）。想保留但不让 Claude 自动调用，设 disable-model-invocation: true。

配置 Skill

Skill 内容的两种类型

参考型内容添加 Claude 应用于当前工作的知识：约定、模式、风格指南、领域知识，内联运行：

---
name: api-conventions
description: API design patterns for this codebase
---

When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats
- Include request validation

任务型内容给 Claude 一个具体动作的分步指令，如部署、提交或代码生成。这些通常是你想用 /skill-name 直接调用、而不是让 Claude 自行决定何时运行的，加 disable-model-invocation: true 防止 Claude 自动触发：

---
name: deploy
description: Deploy the application to production
context: fork
disable-model-invocation: true
---

Deploy the application:
1. Run the test suite
2. Build the application
3. Push to the deployment target

正文要简洁：Skill 一旦加载，内容会跨回合留在上下文里，每一行都是持续的 token 成本。说要做什么，而不是叙述怎么做和为什么。

前置信息字段

所有字段都是可选的，只推荐写 description。字段名必须与表中完全一致（连字符也是），无法识别的字段会被忽略且不报错。前置信息只有在开头的 --- 是文件第一行时才被读取。

在 Claude Code 之外使用：claude.ai 上传、Skills API 以及用 package_skill.py 打包时，只允许规范里的字段（name、description、license、compatibility、metadata、allowed-tools）；包含其他字段会导致打包或上传硬性报错。

字符串替换

带多个单词的参数值要用引号包起来作为一个参数：/my-skill "hello world" second 中 $0 是 hello world、$1 是 second。想在正文里写字面的 $1.00，用反斜杠转义：\$1.00。

添加辅助文件

Skill 目录可以包含多个文件，让 SKILL.md 保持聚焦，详细参考资料只在需要时才被 Claude 读取：

my-skill/
├── SKILL.md (必需：概览和导航)
├── reference.md (详细 API 文档，需要时加载)
├── examples.md (用法示例，需要时加载)
└── scripts/
    └── helper.py (工具脚本，被执行而不是加载)

在 SKILL.md 里引用这些辅助文件，让 Claude 知道每个文件包含什么、何时加载。

控制谁来调用

默认你和 Claude 都能调用任何 Skill。两个前置信息字段可以限制：

• disable-model-invocation: true：只有你能调用。用于有副作用或想控制时机的工作流，如 /commit、/deploy、/send-slack-message。你不想让 Claude 因为代码看起来准备好了就决定去部署
• user-invocable: false：只有 Claude 能调用。用于不能作为命令执行的背景知识

Skill 内容的生命周期

你或 Claude 调用 Skill 后，渲染后的 SKILL.md 内容作为一条消息进入对话，并在后续回合里保留。这指的是 Skill 的指令，而不是它的权限：allowed-tools 授权在你发下一条消息时清除。自动压缩会在预算内带上已调用的 Skill：对话被总结后，Claude Code 会在摘要之后重新附上每个 Skill 最近一次的调用，保留每个 Skill 的前 5000 个 token，所以要把最重要的指令放在靠前的位置。

预批准工具

allowed-tools 字段为调用该 Skill 的这一回合授予所列工具的权限：

---
name: commit
description: Stage and commit the current changes
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---

注意：工作区信任不限制这个字段，项目 Skill 的 allowed-tools 会在你或 Claude 调用时生效，所以要审查提交进仓库的 Skill 的 allowed-tools。

在子智能体里运行

加 context: fork 可以让 Skill 隔离运行：Claude Code 启动一个由 agent 字段指定类型的新子智能体，把 Skill 内容作为它的提示。子智能体看不到你的对话历史，所以 Skill 指令必须自成一体。尽管名字叫 fork，它并不是当前对话的 fork。它默认在后台运行；设置 background: false 可以在调用回合里等待结果。context: fork 只适合有明确指令的 Skill，如果 Skill 只有「使用这些 API 约定」这类指导而没有任务，子智能体会收到指导却没有可执行的提示。

两种配合方向：

检查 Skill 是否加载

在 /skills 里切换的可见性写进 .claude/settings.local.json 的 skillOverrides："on"（默认）、"name-only"（只列名字不列描述）、"user-invocable-only"（菜单里显示为 user-only，Claude 看不到但你能用 /name 调用）、"off"（都隐藏）。插件 Skill、设了 disable-model-invocation: true 的 Skill 不能在这里切换。

怀疑是某个自定义配置搞的鬼，可以用 claude --safe-mode 启动：它关闭 CLAUDE.md、Skill、插件、Hook、MCP 等全部自定义内容，问题消失就说明出在这些里面。

改了 Skill 什么时候生效

Claude Code 监视 ~/.claude/skills/、项目的 .claude/skills/ 和 --add-dir 目录里的 .claude/skills/，在这些位置新增、修改、删除 Skill 会在当前会话里生效，不用重启（bare 模式除外）。两个例外：

• 会话开始时还不存在的顶层 Skill 目录（比如第一次创建 ~/.claude/skills/）：运行 /reload-skills 才能加载；这个目录还没被监视，之后每次改动都要再运行一次
• 已经调用过的 Skill：调用时 Skill 内容作为一条消息进入对话，之后不会重新读文件。改了 SKILL.md 想让当前对话用新版，要再调用一次

实时检测只覆盖 SKILL.md 文本。Skill 目录同时是插件时，hooks/、.mcp.json、agents/ 的改动需要 /reload-plugins。

安装别人写的 Skill

安装别人写的 Skill，就是把它的整个目录放到上面的某个位置：

• 只给自己用：放到 ~/.claude/skills/<skill-name>/
• 给仓库里所有人用：放到项目的 .claude/skills/<skill-name>/ 并提交
• 打包了 Skill 的插件：用 /plugin 安装，命令带插件名前缀

目录结构要对：SKILL.md 必须直接在 <skill-name>/ 文件夹里。直接放一个 .claude/skills/name.md 文件不会出现在 /skills 里。要连同 scripts/、参考文件等整个目录一起拷过来，只拷 SKILL.md 会让引用这些文件的指令失效。

装之前先读一遍：Skill 会让 Claude 照着 SKILL.md 做事，可能运行它自带的脚本；allowed-tools 里列的工具在调用时不用再询问，而且工作区信任不限制这个字段。来源不明的 Skill，先看 SKILL.md 正文、allowed-tools 和 scripts/ 里的内容。

本站的 Skills 目录 在每个 Skill 的详情页给出了安装方式，也可以用 npx funcoding-cli install <owner/repo/skill> 把整个 Skill 目录装到 ~/.claude/skills/（加 --project 装到当前项目）。

排障

先按症状找：

Skill 没有触发：

1. 检查描述里是否包含用户自然会说的关键词
2. 确认 Skill 出现在「What skills are available?」的回答里
3. 换个说法让请求更贴近描述
4. 如果 Skill 可由用户调用，用 /skill-name 直接调用

前置信息 YAML 格式错误时，Claude Code 会以空元数据加载正文，/skill-name 仍能用，但 Claude 无法按 description 匹配；用 --debug 运行可以看到解析错误。要批量找出前置信息解析失败的 SKILL.md，运行 claude plugin validate .claude/skills（个人 Skill 用 claude plugin validate ~/.claude/skills），需要 v2.1.233 或更高版本。

Skill 触发太频繁：让描述更具体，或加 disable-model-invocation: true 只允许手动调用。

Claude 不再遵循某个 Skill：如果某条规则必须每次都成立，把它移进 Hook；如果是需要判断的指导，措辞要适用于整个任务（如「每次编辑后运行测试」，而不是「运行测试」）；对话被压缩后，再次调用 Skill 恢复完整内容。

Skill 描述被截断：Claude Code 把 Skill 名字和描述的列表放进上下文，Skill 很多时会为适应字符预算丢掉一些描述。运行 /doctor 估算列表的上下文开销；可以调高 skillListingBudgetFraction 设置或 SLASH_COMMAND_TOOL_CHAR_BUDGET 环境变量；也可以在 /skills 里把不常用的 Skill 设为 name-only，腾出预算。

个人 Skill 不见了：去 ~/.claude/skills/.trash/ 找。从 claude.ai 同步的 Skill 只下载到单独的 synced 子目录，不会移动或删除你自己建的文件夹；但 v2.1.280 之前，~/.claude/skills/ 里名为 manifest.json 的文件会让 Claude Code 把其中列出的 Skill 文件夹移进 .trash/ 下带时间戳的目录。把文件夹移回 ~/.claude/skills/ 即可恢复，回收站的内容默认 30 天后清理。

想看别人写好的 Skill，本站的 Skills 目录 收录了社区常用的 Skill 仓库。