创建、管理和分享 Skills，扩展 Claude 在 Claude Code 中的能力。
创建你的第一个 Skill
1. 检查可用的 Skills
What Skills are available?
2. 创建 Skill 目录
对于项目级 Skills：
.claude/skills/
对于用户级 Skills：
mkdir -p ~/.claude/skills/explaining-code
3. 编写 SKILL.md
---
name: explaining-code
description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
---
When explaining code, always include:
1. **Start with an analogy**: Compare the code to something from everyday life
2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships
3. **Walk through the code**: Explain step-by-step what happens
4. **Highlight a gotcha**: What's a common mistake or misconception?
Keep explanations conversational. For complex concepts, use multiple analogies.
4. 加载并验证 Skill
What Skills are available?
你应该能看到 explaining-code 出现在列表中。
5. 测试 Skill
How does this code work?
Claude 会自动加载 explaining-code Skill 并按照指令进行代码解释。
Skills 的工作原理
Skills 的工作分为三个阶段：
- 发现（Discovery）：Claude 扫描 Skills 目录，读取每个 SKILL.md 的元数据
- 激活（Activation）：根据描述判断是否与当前对话相关，加载匹配的 Skill
- 执行（Execution）：按照 Skill 中的指令执行任务
Skills 存放位置
| 位置 | 路径 | 说明 |
|---|---|---|
| 用户级 | ~/.claude/skills/ |
个人使用，跨项目生效 |
| 项目级 | .claude/skills/ |
随项目版本控制，团队共享 |
| 插件 | 通过 plugins 安装 | 跨多个仓库分发 |
Skills vs 其他选项
| 功能 | 适用场景 |
|---|---|
| 斜杠命令 | 触发固定操作，如 /deploy staging |
| CLAUDE.md | 项目级上下文和规则 |
| 子代理（Subagents） | 委托复杂任务给专门的代理 |
| Hooks | 工具调用前后的自动化操作 |
| MCP 服务器 | 连接外部工具和数据源 |
| Skills | 可复用的指令集，教 Claude 新行为 |
配置 Skills
SKILL.md 元数据字段
---
name: your-skill-name # 必填：Skill 名称
description: Brief description... # 必填：触发条件描述
allowed-tools: Read, Grep, Glob # 可选：限制可用工具
model: claude-sonnet-4-20250514 # 可选：指定模型
context: fork # 可选：在分叉上下文中运行
agent: Explore # 可选：指定子代理类型
hooks: # 可选：定义 Hooks
PreToolUse: ...
user-invocable: true # 可选：是否可通过 /skill-name 调用
---
渐进式披露（Progressive Disclosure）
对于复杂的 Skills，可以将内容分散到多个文件中：
my-skill/
├── SKILL.md # 必需 - 概述和导航
├── reference.md # 详细 API 文档 - 按需加载
├── examples.md # 使用示例 - 按需加载
└── scripts/
└── helper.py # 工具脚本 - 执行而非加载
在 SKILL.md 中引用其他文件：
## Overview
[Essential instructions here]
## Additional resources
- For complete API details, see [reference.md](reference.md)
- For usage examples, see [examples.md](examples.md)
## Utility scripts
To validate input files, run the helper script:
```bash
python scripts/helper.py input.txt
### 限制工具访问
使用 `allowed-tools` 限制 Skill 可以使用的工具：
```yaml
---
name: reading-files-safely
description: Read files without making changes.
allowed-tools:
- Read
- Grep
- Glob
---
适用场景：
- 只读 Skill，不应修改文件
- 范围受限的 Skill，如只做数据分析
- 安全敏感的工作流
在分叉上下文中运行
使用 context: fork 让 Skill 在独立上下文中运行：
---
name: code-analysis
description: Analyze code quality and generate detailed reports
context: fork
---
定义 Hooks
在 Skill 中定义工具调用前后的 Hooks：
---
name: secure-operations
description: Perform operations with additional security checks
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/security-check.sh $TOOL_INPUT"
once: true
---
控制 Skill 可见性
Skills 可以通过三种方式被调用：
- 手动调用：输入
/skill-name - 程序调用：Claude 通过 Skill 工具调用
- 自动发现：Claude 根据描述自动加载
使用 user-invocable: false 禁用手动调用：
---
name: internal-review-standards
description: Apply internal code review standards when reviewing pull requests
user-invocable: false
---
Skills 与子代理
为子代理分配 Skills
在子代理定义中使用 skills 字段：
# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Review code for quality and best practices
skills: pr-review, security-check
---
分发 Skills
| 方式 | 说明 |
|---|---|
| 项目 Skills | 提交 .claude/skills/ 到版本控制，克隆即可获取 |
| 插件 | 在插件的 skills/ 目录中创建 Skill，通过插件市场分发 |
| 管理配置 | 管理员通过 managed settings 部署到整个组织 |
示例
简单 Skill（单文件）
commit-helper/
└── SKILL.md
---
name: generating-commit-messages
description: Generates clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes.
---
# Generating Commit Messages
## Instructions
1. Run `git diff --staged` to see changes
2. I'll suggest a commit message with:
- Summary under 50 characters
- Detailed description
- Affected components
## Best practices
- Use present tense
- Explain what and why, not how
多文件 Skill
pdf-processing/
├── SKILL.md # 概述和快速入门
├── FORMS.md # 表单字段映射和填写说明
├── REFERENCE.md # pypdf 和 pdfplumber API 详情
└── scripts/
├── fill_form.py # 填写表单字段的工具
└── validate.py # 检查 PDF 必需字段
---
name: pdf-processing
description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction.
allowed-tools: Read, Bash(python:*)
---
# PDF Processing
## Quick start
Extract text:
```python
import pdfplumber
with pdfplumber.open("doc.pdf") as pdf:
text = pdf.pages[0].extract_text()
For form filling, see FORMS.md. For detailed API reference, see REFERENCE.md.
Requirements
pip install pypdf pdfplumber
## 故障排查
### Skill 未触发
确保描述包含：
1. 这个 Skill 做什么？列出具体功能
2. Claude 什么时候应该使用它？包含用户可能提到的触发词
```yaml
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
Skill 未加载
- 确认
SKILL.md文件存在于正确路径 - 检查 YAML 前置信息格式（以
---开头和结尾） - 使用
claude --debug查看调试信息
Skill 有错误
- 确保脚本有执行权限：
chmod +x scripts/*.py - 使用正确的路径分隔符（Unix 用
/，Windows 用\）
多个 Skills 冲突
如果多个 Skills 描述相似，让描述更具体，明确区分使用场景。
插件 Skills 未出现
- 清除缓存：
rm -rf ~/.claude/plugins/cache - 重新安装插件：
/plugin install plugin-name@marketplace-name - 确认插件结构正确：
my-plugin/
├── .claude-plugin/
│ └── plugin.json
└── skills/
└── my-skill/
└── SKILL.md
关于
📬 关注我获取更多资讯
📢 公众号
💬 个人号