Claude Code Skills 怎么创建？SKILL.md、调用方式与权限配置

Claude Code Skill 是一个以 SKILL.md 为入口的可复用任务流程。它适合把“每次都要重新说明的检查步骤、模板和多步操作”整理成可按需加载的能力。按官方当前文档，Skill 可以由 Claude 在相关时自动使用，也可以由用户输入 /skill-name 手动调用。本文依据 Claude Code 当前 Skills 文档整理，最近核验时间为 2026 年 10 月 27 日；版本、字段和可用功能仍可能变化。

2026 年 Skills 更新：命令已经合并到 Skills

当前官方文档把自定义命令和 Skills 放在同一套机制中管理。.claude/commands/deploy.md 和 .claude/skills/deploy/SKILL.md 都可以创建 /deploy 这样的斜杠命令；后者还能携带参考资料、脚本和更完整的目录结构。已有的 commands 文件不需要立即迁移，但新建项目时建议采用 skills/<name>/SKILL.md，方便把说明、示例和资源放在一起。

Skills 有两种常见调用方式：Claude 在任务相关时自动使用，或者用户直接输入 /skill-name。如果一个 Skill 涉及部署、删除、发消息、支付或其他副作用，不应让 Claude 自行判断调用时机，可以在 frontmatter 中设置 disable-model-invocation: true，只允许人工显式调用；这仍然不能替代每一步的权限确认。

创建或修改 Skill 后，可以用当前版本支持的校验命令检查 frontmatter 和目录结构：

claude plugin validate .claude/skills

官方文档提示该命令需要较新的 Claude Code 版本；如果当前版本不支持，先运行 claude --version，再对照本机版本对应的文档，不要把校验命令当成所有版本都可用。

从零创建一个可校验的 Skill

如果你只是想把一套重复检查流程固定下来，可以按下面的顺序创建一个最小 Skill：

1. 在项目根目录创建 .claude/skills/seo-check/SKILL.md，先只写目标、触发条件和禁止事项。
2. 在 frontmatter 中填写 name、description 和必要的 allowed-tools；描述要写清“检查什么”和“什么时候使用”。
3. 在正文中列出输入、步骤、失败分支和输出格式，要求它报告实际读取的文件，不要只返回“已完成”。
4. 先让 Skill 执行只读检查，再逐项加入脚本、网络请求或文件修改能力。
5. 使用当前版本支持的 claude plugin validate 校验目录；如果命令不存在，先核对 claude --version 与官方文档，不要强行套用旧教程。

例如，完成文件后可以在项目根目录检查结构，再手动输入 /seo-check README.md，确认参数替换、工具限制和输出证据都符合预期。涉及部署、删除、提交或外部消息时，应将 disable-model-invocation: true 写入 frontmatter，并把发布动作留给人工明确调用。需要了解项目长期规则时，可继续阅读 CLAUDE.md 写法；需要检查扩展权限时，可参考 Claude Code MCP 配置与安全。

Skill 不触发或触发过于频繁怎么办

Skill 的 description 会参与自动匹配。描述应明确写出“做什么”和“什么时候使用”，避免只写“提升效率”这类泛化句子。Skills 很多时，客户端会对描述列表设置上下文预算，过长的描述可能被截断；可以运行 /doctor 查看扩展和上下文相关诊断，并把最关键的触发关键词放在描述前部。

如果 Skill 在第一轮生效、后续轮次却不再遵循，先检查规则是否属于必须每次执行的约束。模型不会在每一轮重新读取 Skill 文件；需要在固定事件中强制执行的规则，更适合使用 hook。对话发生压缩后，重要步骤也可能不再完整保留，此时应重新调用 Skill，并把最重要的限制放在 SKILL.md 开头。

如果你还不了解三者分工，可以先看 Claude Code Skills、MCP、Plugin 对比。已有的 Skills 入门文章偏概念与安全，本文补充当前官方格式和创建步骤。

Skill 与 CLAUDE.md 的区别

文件或机制	适合放什么	何时加载
CLAUDE.md	项目事实、目录、命令、长期规则和安全边界	通常作为项目上下文持续提供
.claude/skills/name/SKILL.md	一类任务的步骤、模板、检查和输出格式	相关时加载或手动调用
MCP	外部工具、资源和数据连接	配置的服务器可用时按权限调用

官方文档建议：当 CLAUDE.md 中的一段内容已经从“事实”变成一套重复流程，或者参考资料很长、并非每次都需要时，可以考虑拆成 Skill。Skill 不能替代权限系统、代码审查和测试。

最小目录结构

项目级 Skill 通常放在：

your-project/
└─ .claude/
   └─ skills/
      └─ seo-check/
         └─ SKILL.md

个人级 Skill 可放在 ~/.claude/skills/<skill-name>/SKILL.md，这样同一台机器的多个项目都能使用。项目级 Skill 可以随仓库提交给团队；个人级 Skill 不会自动成为团队规则。嵌套目录和插件还有额外加载范围，采用前应阅读当前官方文档。

一个可用的 SKILL.md 模板

下面是一个低风险、只读 SEO 检查 Skill 的示例：

---
name: seo-check
description: 检查文章的标题、描述、链接和 FAQ。用户询问 SEO 检查、发布前核验或文章元信息时使用。
argument-hint: [文章路径]
allowed-tools: Read Grep
---

## 目标

检查指定文章的 SEO 字段和内部链接，不直接修改文件。

## 步骤

1. 读取 frontmatter 和正文结构。
2. 检查标题、description、route、更新时间、关键词和 FAQ。
3. 检查文章中的站内链接是否指向存在页面。
4. 输出文件、证据、问题和建议。

## 边界

- 不读取 .env、密钥、客户资料或无关目录。
- 不执行网络请求、删除、发布或自动修复。
- 无法确认的信息标记为“待核验”。

这里的 description 很重要：Claude 会根据它判断是否自动加载。allowed-tools 只影响该 Skill 调用期间的工具许可，不代表项目整体永久放开权限。

frontmatter 常用字段

当前 Claude Code 文档支持的字段比早期示例更多，常用的有：

• name：斜杠菜单中显示的名称，默认使用目录名。
• description：说明功能和何时使用，建议始终填写。
• argument-hint：在补全菜单中提示需要哪些参数。
• arguments：为 $name 参数替换声明位置参数。
• disable-model-invocation：设为 true 后禁止 Claude 自动调用。
• user-invocable：设为 false 后只允许 Claude 调用，用户菜单中不作为直接命令。
• allowed-tools / disallowed-tools：限制本次 Skill 可使用或不可使用的工具。
• model 与 effort：为当前 Skill 任务指定模型或推理强度，具体可用值取决于版本和账号。
• paths：按文件路径模式限制自动激活范围。
• context: fork：在分叉的 Agent 上下文中运行，适合需要隔离的流程。

字段名必须按官方拼写使用，未知字段可能被忽略。frontmatter 的开头 --- 必须是 SKILL.md 第一行，否则可能被当作普通正文。

手动调用和自动触发

手动调用的形式通常是：

/seo-check src/content/articles/example.md

Skill 也可以通过 $ARGUMENTS、$0、$1 等占位符接收参数。多词参数要按当前终端和文档要求正确引用，避免路径被拆成多个参数。

自动触发适合只读检查、代码解释和低风险分析；有副作用的流程不要让模型自行判断时机。例如部署 Skill 可以这样写：

---
name: deploy-preview
description: 将已通过检查的站点部署到预览环境。
disable-model-invocation: true
---

这只减少误触发，不会自动替你完成权限审查。涉及生产部署、删除、发信、支付和数据库写入时，仍应每次人工确认。

如何添加参考文件和脚本

Skill 目录可以包含 reference.md、examples.md 和 scripts/ 等文件：

seo-check/
├─ SKILL.md
├─ checklist.md
└─ scripts/
   └─ check-links.js

让 SKILL.md 只保留导航和关键流程，把长参考资料按需读取。官方当前建议不要把 SKILL.md 写成无限增长的说明书；较长的资料应拆到 supporting files。脚本必须逐个审查，不要因为它位于 Skill 目录就默认安全。

权限设计的四条原则

先只读后写入

第一个版本只做分析和报告，确认误报率后再加入自动修复。

工具最小化

只声明需要的工具，不要为了“以后可能用到”开放网络、Shell、删除或外部服务。

写清失败分支

文件不存在、测试失败、版本不符、数据来源不明时要停止并报告，不要继续猜测或覆盖。

输出证据

每次运行报告实际读取的文件、执行的命令、修改的文件和未验证项，让团队可以复查。

测试 Skill 是否真的生效

可以用下面的流程测试：

1. 在无敏感信息的临时项目中安装或创建 Skill。
2. 先用自然语言提问，看是否在合适场景自动触发。
3. 再用 /skill-name 显式调用，验证参数替换。
4. 用不相关的请求测试它是否会过度触发。
5. 用故意缺失文件、错误路径和测试失败模拟异常分支。
6. 检查工具调用、网络请求、文件 diff 和日志。

如果 Skill 没有触发，先检查目录、SKILL.md 首行、YAML 缩进、description 和当前 Claude Code 版本。不要先扩大所有权限。

与 API 和第三方平台的关系

Skill 是 Claude Code 客户端的流程扩展，不等于 API 服务，也不代表使用了 Anthropic 官方 API。若需要把模型接入 Claude Code 或多个开发工具，可以了解 ZeoAPI，但它是独立第三方 API 网关；模型映射、费用、数据处理和可用性要以其文档为准。

官方参考

• Claude Code Skills 官方文档
• Claude Code 模型配置
• Claude Code 安全说明