Claude Code 技能

Claude Code Skills 使用与创建指南：SKILL.md 结构、frontmatter 字段、存放位置、调用方式与内置 Skills（2026）。

更新于 2026-10-20

需要 API Key？ 前往注册 →端点与 Base URL →

本页目录

最后核实：2026-10-20 · 📄 依据官方文档（Claude Code Skills）

Skill 就是一个 SKILL.md 文件：--- 之间的 YAML frontmatter 告诉 Claude 何时使用，后面的 Markdown 是 Claude 执行时遵循的指令。Claude 会在相关时自动使用 Skill，也可以用 /skill-name 直接调用。

Skills 是 Claude Code 的知识层组件，为 Claude 提供特定领域的专业知识和指导。Claude 会在相关时自动加载，也可以用 /skill-name 直接调用。

什么是 Skills？

Skills 是存储在 SKILL.md 文件中的专业知识模块：

  • 自动激活：Claude 根据任务上下文自动使用相关 Skill

  • 领域知识：提供特定领域的最佳实践和指导

  • 可扩展：可以创建自定义 Skills 满足特定需求

  • 上下文感知：只在相关场景中被调用

Skills vs Commands vs Agents

组件 触发方式 用途
Commands 用户手动调用（/command） 执行特定任务
Skills 自动激活或 /skill-name 提供领域知识
Agents 委托调用 处理复杂工作流

Skills、命令与 CLAUDE.md（2026-10-20 核对）

Claude Code 的 Skills 遵循 Agent Skills 开放标准，可跨多个 AI 工具使用。自定义命令已并入 Skills：.claude/commands/deploy.md 与 .claude/skills/deploy/SKILL.md 都会生成 /deploy，行为相同。与 CLAUDE.md 的内容不同，Skill 正文只在被使用时加载，因此长篇参考资料在用到之前几乎不占成本。

使用内置 Skills

Claude Code 插件通常包含多个内置 Skills。当你的任务匹配 Skill 的描述时，Claude 会自动使用它。

Claude Code 另外随附一组 bundled skills，例如 /doctor、/code-review、/batch、/debug、/loop 和 /claude-api（2026-10-20 核对）。调用方式与其它 Skill 相同：输入 / 加上 Skill 名称。

示例：代码审查

当你说"帮我审查这段代码的安全性"时，如果安装了包含安全审查 Skill 的插件，Claude 会自动应用该 Skill 的知识来进行审查。

查看可用 Skills

Skills 通常随插件一起安装：

# 安装插件（插件可能包含多个 Skills）
/plugin install plugin-name@marketplace

创建自定义 Skills

基本结构

最简单的 Skill 只需要一个 SKILL.md 文件：

my-skill/
└── SKILL.md

SKILL.md 格式

---
name: 代码风格指南
description: 当用户询问"代码风格"、"命名规范"、"代码格式化"或讨论代码规范时使用此 Skill
---

# 代码风格指南

## 命名规范

- 变量使用 camelCase
- 常量使用 UPPER_SNAKE_CASE
- 类使用 PascalCase
- 私有成员使用下划线前缀

## 格式化规则

- 缩进使用 2 个空格
- 行宽不超过 80 字符
- 使用尾随逗号

## 最佳实践

- 函数应该单一职责
- 避免深层嵌套
- 使用有意义的变量名

Frontmatter 字段

所有字段都是可选的：官方只推荐写 description，让 Claude 知道何时使用该 Skill；name 可以省略，默认取目录名。字段名必须与官方 frontmatter 参考完全一致（连字符也算；下表只列常用字段，官方另有 model、effort、hooks、user-invocable 等）：Claude Code 会忽略不认识的字段，并且不报错（2026-10-20 核对）。

字段 必需 说明
name 否 / 菜单中显示的命令名；默认取目录名
description 推荐 Skill 做什么、何时使用；Claude 据此决定何时应用该 Skill
when_to_use 否 补充 Claude 应在何时调用该 Skill，例如触发短语或示例请求；在 Skill 列表中追加到 description 之后
argument-hint 否 自动补全时提示期望的参数，例如 [issue-number] 或 [filename] [format]
disable-model-invocation 否 设为 true 可阻止 Claude 自动加载该 Skill；适合用 /name 手动触发的工作流
allowed-tools 否 调用该 Skill 的那一轮里，Claude 无需询问即可使用的工具
paths 否 限定该 Skill 何时生效的 glob 模式；只有处理匹配文件时 Claude 才会自动加载
context 否 设为 fork 时在派生的子代理上下文中运行

version 不属于该表：Claude Code 会忽略不认识的字段且不报错（2026-10-20 核对）。

编写有效的 Description

description 字段决定了 Skill 何时被激活，应该包含具体的触发短语：

好的示例：

description: 当用户询问"创建 hook"、"添加 PreToolUse hook"、"验证工具使用"或提到 hook 事件时使用此 Skill

差的示例：

description: 关于 hooks 的指南  # 太模糊

完整的 Skill 结构

对于复杂的 Skills，可以包含更多资源：

my-skill/
├── SKILL.md           # 主要知识文档
├── references/        # 详细参考资料
│   ├── patterns.md    # 设计模式
│   └── advanced.md    # 高级技巧
├── examples/          # 示例代码
│   ├── basic.ts       # 基础示例
│   └── advanced.ts    # 高级示例
└── scripts/           # 辅助脚本
    └── validate.sh    # 验证脚本

引用资源

在 SKILL.md 中引用其他资源：

---
name: API 开发指南
description: 当用户询问"API 设计"、"REST 接口"、"API 最佳实践"时使用
---

# API 开发指南

详细的 API 设计模式请参考 @references/patterns.md

## 快速示例

参见 @examples/basic.ts 了解基本用法

动态上下文注入

像 !`git diff HEAD` 这样的行会用到动态上下文注入：Claude Code 先执行命令，并用输出替换该行，再把 Skill 内容交给 Claude，因此指令到达时已经内联了当前的 diff（2026-10-20 核对）。

Skills 的存放位置

  • 个人 Skill 放在 ~/.claude/skills/<skill-name>/SKILL.md。
  • 项目 Skill 放在仓库内的 .claude/skills/<skill-name>/SKILL.md。
  • 插件 Skill 放在插件内的 <plugin>/skills/<skill-name>/SKILL.md。

在插件中使用 Skills

目录结构

Skills 放在插件的 skills/ 目录下：

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/          # 命令层
├── agents/            # 代理层
└── skills/            # 知识层
    ├── code-style/
    │   └── SKILL.md
    └── api-docs/
        ├── SKILL.md
        └── references/

在命令中引用 Skill

命令可以显式引用 Skill 的知识：

---
description: 生成符合规范的 API 文档
argument-hint: [api-file]
---

为 @$1 生成 API 文档。

使用 api-docs Skill 确保文档包含：

- 完整的端点描述
- 参数规格说明
- 响应格式
- 错误码
- 使用示例

实用示例

示例 1：项目规范 Skill

---
name: 项目规范
description: 当用户询问"项目结构"、"文件组织"、"目录规范"时使用
---

# 项目规范

## 目录结构

\`\`\`
src/
├── components/    # React 组件
├── hooks/         # 自定义 Hooks
├── services/      # API 服务
├── utils/         # 工具函数
└── types/         # TypeScript 类型
\`\`\`

## 文件命名

- 组件：PascalCase（如 `UserProfile.tsx`）
- 工具函数：camelCase（如 `formatDate.ts`）
- 常量：UPPER_SNAKE_CASE（如 `API_ENDPOINTS.ts`）

## 导入顺序

1. React 相关
2. 第三方库
3. 内部模块
4. 类型定义
5. 样式文件

示例 2：Git 工作流 Skill

---
name: Git 工作流
description: 当用户询问"分支策略"、"提交规范"、"Git 流程"时使用
---

# Git 工作流规范

## 分支命名

- 功能：`feature/描述`
- 修复：`fix/描述`
- 热修复：`hotfix/描述`

## 提交信息格式

\`\`\`
<type>(<scope>): <subject>

<body>

<footer>
\`\`\`

### Type 类型

- `feat`: 新功能
- `fix`: 修复 bug
- `docs`: 文档更新
- `style`: 代码格式
- `refactor`: 重构
- `test`: 测试
- `chore`: 构建/工具

示例 3：安全审查 Skill

---
name: 安全审查
description: 当用户询问"安全检查"、"漏洞扫描"、"安全最佳实践"或审查代码安全性时使用
---

# 安全审查指南

## 常见漏洞检查

### SQL 注入

- 检查是否使用参数化查询
- 避免字符串拼接 SQL

### XSS 攻击

- 检查用户输入是否转义
- 使用 CSP 头

### 敏感数据

- 确保密码不明文存储
- API 密钥不要硬编码
- 检查日志是否泄露敏感信息

## 审查清单

- [ ] 输入验证
- [ ] 输出编码
- [ ] 认证机制
- [ ] 授权检查
- [ ] 加密使用
- [ ] 错误处理

最佳实践

1. 明确的触发描述

使用具体的触发短语，而不是模糊的描述：

# 好
description: 当用户询问"创建组件"、"React 组件模板"、"组件最佳实践"时使用

# 差
description: React 组件相关

2. 结构化的知识

将知识组织成清晰的层次结构：

  • 使用标题分级

  • 提供代码示例

  • 包含检查清单

3. 保持更新

  • 定期更新 Skill 内容

  • 版本号反映变更

  • 记录重要更新

4. 模块化设计

  • 每个 Skill 专注一个领域

  • 使用 references 目录存放详细资料

  • 通过 examples 提供实际示例

调试 Skills

如果 Skill 没有按预期激活：

  1. 检查 description：确保触发短语与用户输入匹配

  2. 验证格式：确保 YAML frontmatter 格式正确

  3. 测试触发：尝试使用 description 中的确切短语

下一步

← 上一篇
在云服务器上跑 Agent
下一篇 →
Plan 模式深度指南
Claude Agent SDK 入门
用 Claude Agent SDK 构建 Python / TypeScript Agent：包名、query() 入口与 QCode 接入（2026）。
Hooks 系统
完整掌握 Claude Code Hooks — 17 种生命周期事件、3 种处理器类型、10+ 实战 Recipe 与企业级配置
Plan 模式深度指南
2026 年 Claude Code Plan 模式怎么用：Shift+Tab 切换、只读分析并生成执行计划、审核后执行，含实战示例与最佳实践。
MCP 服务器
使用 Model Context Protocol 扩展 Claude Code 的能力，连接外部工具和服务

开始使用 QCode

一把 API Key 同时用于 Claude Code、Codex 等工具；按 token 计费，各模型单价见 qcode.cc/models

注册账号 查看套餐定价 →

企业团队版 →