Claude Code Skills 深度解析：从原理到工程实践

引言

如果你用过 Claude Code 一段时间，一定遇到过这个问题：每次开启新对话，都要把同一套上下文——“用 TypeScript，遵循我们的 API 规范，错误处理用 Result 类型……”——重新粘贴一遍。

这正是 Skills（技能） 要解决的问题。

Skills 是 Claude Code 的可插拔指令包：把重复的提示词、工作流程、代码规范封装成一个目录，下次只需输入 /my-skill，Claude 就自动获取完整的上下文并按规范执行。

本文从机制原理到工程实践，逐层拆解 Skills 的每个细节。

一、Skills 与 Slash Commands 的关系

在理解 Skills 之前，有必要先厘清它与内置命令的区别。

Claude Code 内置了一批固定功能的 / 命令：

命令作用
/clear清空对话历史
/compact压缩上下文，节省 token
/cost查看当前会话 token 用量
/help列出所有可用命令
/diff查看 Claude 做出的所有文件变更
/init初始化项目，生成 CLAUDE.md

这些是硬编码进 CLI 的逻辑，用户无法修改。

Skills 则是用户定义的扩展层。早期版本里，Claude Code 有两个存放路径：

  • .claude/commands/*.md —— 命令文件
  • .claude/skills/*/SKILL.md —— 技能目录

两者现已合并为统一机制，推荐使用 .claude/skills/ 路径，因为它支持更多功能：支持文件（模板、脚本、参考文档）、完整的 frontmatter 控制，以及 Agent 子进程模式。

个人级技能放在 ~/.claude/skills/（对所有项目生效），项目级技能放在项目根目录的 .claude/skills/（可纳入 git 版本管理，团队共享）。

二、SKILL.md：技能的基本单元

每个技能本质上是一个目录，目录里必须包含一个 SKILL.md 文件：

.claude/
└── skills/
    └── api-design/          ← 技能目录名（对应 /api-design 命令）
        ├── SKILL.md         ← 必须：主指令文件
        ├── template.ts      ← 可选：模板文件
        ├── examples/        ← 可选：示例目录
        └── docs/            ← 可选：参考文档

SKILL.md 由两部分组成：

---
name: api-design
description: 按照项目 RESTful 规范设计 API 接口，包括路由、请求/响应结构和错误处理
---

## API 设计规范

设计接口时遵循以下原则：

1. 路由使用复数名词：`/users`、`/orders`
2. 错误响应统一使用 `{ code, message, data }` 结构
3. 分页参数：`page`（从 1 开始）+ `pageSize`（默认 20，最大 100）

## 参考模板

见同目录的 `template.ts`，包含标准的 Controller 和 Service 结构。

用户请求：$ARGUMENTS

YAML frontmatter（--- 之间的部分）控制技能行为，markdown 正文是 Claude 执行时读取的指令。

三、Frontmatter 字段全解

这是 Skills 与普通 .md 文件的核心差异所在。官方文档和社区实践共识的字段如下：

name

name: api-design

技能的唯一标识符，对应用户输入的 /api-design。只允许小写字母、数字和连字符，最长 64 个字符。若省略，使用目录名。

description

description: 按照项目 RESTful 规范设计 API 接口

这个字段有两个作用：

  1. 在 /help 列表中展示给用户
  2. 帮助 Claude 自动判断是否应该调用这个技能

关键限制：每条 description 最多显示 250 个字符，且所有技能描述共用一个上下文预算（默认为上下文窗口的 1%，约 8000 个字符）。建议把最关键的使用场景放在前 50 个字里。

allowed-tools

allowed-tools: [Read, Grep, Glob]

限制技能执行期间 Claude 可以使用的工具集合。这是一个安全边界机制，常见模式：

  • 只读分析技能：[Read, Grep, Glob]
  • 代码执行技能：[Bash, Read, Write]
  • 纯文档技能：[Read]

未列出的工具在技能执行期间不可用，即使 Claude 尝试调用也会被拦截。

disable-model-invocation

disable-model-invocation: true

设为 true 时，该技能不会出现在 Claude 可自动调用的工具列表中，只能由用户显式输入 /skill-name 触发。

适用场景：

  • 危险操作：生产环境部署、数据库迁移
  • 交互式工作流：需要用户逐步确认的操作
  • 一次性配置命令：不希望 Claude 在对话中自动触发

副作用：减少无关的上下文消耗，提升其他技能的可用预算。

user-invocable

user-invocable: false

设为 false 时，技能不出现在用户可见的命令列表中，但 Claude 可以自动调用它。

这是与 disable-model-invocation 相对的设计：适合作为”背景知识”存在的技能——比如项目的编码规范、架构决策记录，Claude 可以在任何时候参考，但用户不需要手动触发。

argument-hint

argument-hint: "[issue-number] [分配给谁]"

在命令补全时显示的参数提示，纯 UX 用途，不影响逻辑。

context

context: fork

设置技能在独立子进程中执行。技能内容成为子进程的任务 prompt，不继承当前对话历史。

适合长时间、消耗大量上下文的分析任务，执行结果会被汇总后返回主对话。

agent

agent: Explore

配合 context: fork 使用，指定子进程使用的 Agent 类型。可用选项：

Agent特点
Explore只读工具，专为代码库探索优化
Plan设计实现方案的架构师 Agent
general-purpose默认，拥有全部工具
自定义 Agent 名称来自 .claude/agents/ 的配置

$ARGUMENTS

不是 frontmatter 字段，而是正文中的占位符。用户输入 /my-skill some text 时，some text 会替换 $ARGUMENTS：

---
name: translate
description: 翻译文本到指定语言
argument-hint: "[目标语言] [文本]"
---

请将以下内容翻译为 $ARGUMENTS

四、三种典型技能模式

理解了字段含义，来看三种实际工程场景的设计模式。

模式一：标准提示词封装

最简单的用法，把重复的 prompt 固化下来：

---
name: commit
description: 生成符合项目规范的 git commit 信息
---

分析当前 staged changes，生成一条符合 Conventional Commits 规范的提交信息：

- 格式：`type(scope): description`
- type 范围：feat / fix / docs / refactor / test / chore
- description 用中文，动词开头，不超过 50 字
- 如果变更涉及 breaking change，在正文中注明

先用 Bash 运行 `git diff --staged` 查看变更内容，再生成提交信息。

模式二：只读分析技能

适合代码审查、安全扫描等场景，配合 allowed-tools 防止意外修改：

---
name: security-review
description: 对当前代码库进行 OWASP Top 10 安全审查
allowed-tools: [Read, Grep, Glob]
disable-model-invocation: true
---

对 $ARGUMENTS 路径下的代码进行安全审查，重点检查：

1. SQL 注入风险（拼接查询字符串）
2. XSS 漏洞（未转义的用户输入输出到 HTML）
3. 不安全的反序列化
4. 硬编码的密钥或敏感信息
5. 目录遍历漏洞

输出格式：
- 风险等级（High / Medium / Low）
- 文件位置（文件名:行号）
- 漏洞描述
- 修复建议

模式三：Fork Agent 深度探索

适合需要大量读取和分析、但不希望污染主对话上下文的任务：

---
name: deep-audit
description: 在独立 Agent 中对代码库进行深度架构分析
context: fork
agent: Explore
---

对当前项目进行全面架构分析：

1. 找出所有模块的依赖关系
2. 识别潜在的循环依赖
3. 统计各模块的代码行数和复杂度
4. 找出没有测试覆盖的关键路径

生成一份结构化的架构报告，包含可量化的指标和具体的改进建议。

五、支持文件：让技能更强大

技能目录中除了 SKILL.md，还可以放置支持文件。在 SKILL.md 正文中引用它们，Claude 就会在执行时加载：

.claude/skills/generate-component/
├── SKILL.md
├── component.template.tsx   ← 组件模板
├── stories.template.ts      ← Storybook 故事模板
└── test.template.spec.ts    ← 测试文件模板
---
name: generate-component
description: 生成符合项目规范的 React 组件，含 Storybook 故事和单元测试
---

生成 React 组件 `$ARGUMENTS`，参考以下模板：

- 组件代码：见 `component.template.tsx`
- Storybook：见 `stories.template.ts`
- 测试：见 `test.template.spec.ts`

组件应支持 dark mode，使用 Tailwind CSS，Props 类型定义完整。

六、从 GitHub 安装社区技能

技能社区已经相当活跃，截至 2026 年 4 月，仅一个社区目录就收录了超过 9000 个技能。

官方技能库

Anthropic 官方维护了一个技能仓库 github.com/anthropics/skills，包含文档处理（docx、xlsx、pdf）、创意应用（算法艺术、UI 设计）等官方出品的技能。

安装方法

方法一：手动克隆（推荐，可审查代码）

# 克隆到个人技能目录
git clone https://github.com/author/skill-name.git \
  ~/.claude/skills/skill-name

# 或者只下载单个 SKILL.md
mkdir -p ~/.claude/skills/my-skill
curl -o ~/.claude/skills/my-skill/SKILL.md \
  https://raw.githubusercontent.com/author/repo/main/SKILL.md

方法二：使用 clawhub CLI

npx clawhub@latest install <skill-name>

安装后重启 Claude Code 即可生效。

方法三：项目级技能（团队共享）

把 .claude/skills/ 目录纳入 git 版本管理：

# 将技能目录加入版本控制
git add .claude/skills/
git commit -m "chore: add team skills"

团队成员克隆仓库后，技能自动可用。

知名社区资源

仓库内容
hesreallyhim/awesome-claude-code技能、Hook、Agent 策划列表，含自治开发框架
travisvn/awesome-claude-skills社区技能合集，含 TDD、调试、协作等模式
ComposioHQ/awesome-claude-skills面向生产力的技能，含 MCP 构建器、子 Agent 开发
rohitg00/awesome-claude-code-toolkit综合工具箱，含 135 个 Agent、35 个技能
VoltAgent/awesome-agent-skills跨工具技能，同时兼容 Codex CLI、Gemini CLI

安全提示：技能可以执行任意代码。安装前务必阅读 SKILL.md 内容，像对待开源依赖一样审查来源。优先选择有一定 star 数、有 CI 验证、有活跃维护者的仓库。

七、上下文预算与技能命名的工程考量

技能数量越多，上下文预算的管理就越重要。

技能描述预算

所有技能名称始终加载，但 description 受到字符预算限制：

  • 默认预算 = 上下文窗口的 1%（GPT-4 级别约 1280 字符，Claude 3.5 约 2000 字符）
  • 单条 description 最多 250 个字符
  • 超出预算时，Claude 会截断描述

提升预算：

export SLASH_COMMAND_TOOL_CHAR_BUDGET=16000

更根本的解法是精简 description：把最关键的触发场景放在前 30 个字，其余细节放到 SKILL.md 正文里。

技能命名策略

技能名即命令名，命名应该清晰表达”做什么”而不是”怎么做”：

# 好的命名
/commit          # 生成提交信息
/security-review # 安全审查
/generate-api    # 生成 API 接口

# 不好的命名
/helper          # 模糊
/do-stuff        # 无意义
/gpt-style-thing # 实现细节暴露

八、最佳实践总结

经过社区实践沉淀，以下是值得遵循的工程原则：

1. 一技能一工作流

不要把”代码审查 + 生成测试 + 写文档”塞进一个技能。拆成三个独立技能，可组合性更好，描述也更精准。

2. 控制技能正文长度

技能内容会占用上下文窗口。超过 500 词的技能，执行时会明显压缩可用的对话空间。把详细规范放到支持文件里，SKILL.md 只保留核心指令。

3. 用 disable-model-invocation 保护高风险操作

部署、数据库操作、发送消息等不可逆操作，一律设置 disable-model-invocation: true，要求用户显式触发。

4. 项目技能纳入版本控制

.claude/skills/ 目录跟代码一起提交，技能的变更走 PR 流程审查，团队规范就不会因为”只改了提示词”而绕过代码评审。

5. 用 user-invocable: false 构建隐式规范层

把项目的编码规范、架构约束写成 user-invocable: false 的技能，Claude 会在任何相关操作时自动参考，无需用户记住命令名。

结语

Skills 本质上是把提示词工程的成果固化为工程资产。它把”每次告诉 Claude 怎么做”变成”一次定义，反复复用”。

从单人开发者的个人效率工具，到团队共享的工程规范载体，Skills 的价值会随着使用深度指数级增长。

如果你发现自己在某个场景下反复输入同样的 prompt——那就是该写一个技能的信号。

参考资料