name: 技能指南 description: 定义SKILL.md文件所需的结构、前导格式和最佳实践。在创建或编辑任何技能之前使用——这是要遵循的规范，不是可选参考。
技能指南
将可重用的专业知识打包成可发现的能力。技能是Claude在相关时自主激活的模块化指令——扩展您的工作流程而无需斜杠命令。
目录
快速开始
个人技能（随处可用）
mkdir -p ~/.claude/skills/my-skill-name
项目技能（与团队共享）
mkdir -p .claude/skills/my-skill-name
创建SKILL.md
---
name: 技能名称
description: 它做什么 + 何时使用（要具体！）
---
# 技能名称
## 指令
为Claude提供逐步指导
## 示例
具体使用示例
什么是技能
代理技能将专业知识打包成可发现、可组合的能力：
- SKILL.md — Claude在相关时读取的指令
- 支持文件 — 可选的脚本、模板、参考文档
- 模型调用 — Claude基于描述自主决定何时使用
- 可发现 — 无斜杠命令；与您的工作流程集成
好处
- 一次性解决重复性问题，随处重用
- 通过git跨团队共享专业知识
- 组合多个技能处理复杂任务
- 减少重复提示的令牌开销
创建技能
个人技能：~/.claude/skills/
在所有项目中可用。用于：
- 个人工作流程和实验性技能
- 个人生产力工具
- 跨多个项目使用的实用程序
项目技能：.claude/skills/
通过git与您的团队共享。用于：
- 团队工作流程和共享专业知识
- 项目特定能力
- 团队成员需要一起使用的实用程序
团队成员拉取您的仓库时自动获取项目技能。
插件技能
与Claude Code插件捆绑；安装插件时自动可用。
编写SKILL.md
每个技能都需要YAML前导 + Markdown内容。
必填字段
| 字段 | 限制 | 目的 |
|---|---|---|
name |
64字符 | 人类可读的名称 |
description |
1024字符 | 它做什么 + 何时使用 |
可选字段
| 字段 | 目的 |
|---|---|
allowed-tools |
限制Claude可以使用的工具（例如，Read, Grep, Glob） |
描述字段至关重要
Claude使用此字段来决定是否激活您的技能。始终包括：
- 它做什么 — 具体能力
- 何时使用 — 具体触发器和上下文
好（触发Claude）：
从PDF文件中提取文本和表格，填写表单，合并文档。
当处理PDF文件或用户提到PDF、表单或提取时使用。
差（太模糊）：
帮助处理文档
命名约定
使用动名词形式（动词 + -ing）：
- “处理PDF”
- “分析电子表格”
- “测试代码”
- “编写文档”
结构与组织
简单技能（单文件）
针对聚焦、单用途能力：
commit-helper/
└── SKILL.md
带有支持文件的技能
参考文件按需加载；保持SKILL.md在500行以内以获得最佳性能：
pdf-processing/
├── SKILL.md # 主要指令（快速开始）
├── FORMS.md # 表单填写指南
├── REFERENCE.md # API参考
├── EXAMPLES.md # 使用示例
└── scripts/
├── analyze_form.py
├── fill_form.py
└── validate.py
渐进式披露模式
SKILL.md中的高级概述：
- 快速开始和常见用例
- 链接到详细参考文件
## 快速开始
使用pdfplumber提取文本：
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
高级功能
表单填写：参见FORMS.md API参考：参见REFERENCE.md 示例：参见EXAMPLES.md
### 多领域技能的组织
对于覆盖多个领域的技能，按领域组织：
bigquery-skill/ ├── SKILL.md └── reference/ ├── finance.md ├── sales.md ├── product.md └── marketing.md
SKILL.md充当路由器链接到领域特定文档。
## 最佳实践
### 1. 假设Claude聪明
不要解释基本概念。简洁直接。
**冗长**（约150令牌）：
PDF文件是包含文本、图像和其他内容的常见格式。 要提取文本，您需要一个库。存在许多库…
**简洁**（约50令牌）：
使用pdfplumber进行文本提取：
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
### 2. 使用示例而非解释
提供输入/输出对，特别是对于转换：
```markdown
## 提交消息格式
**示例1：**
输入：添加了用户认证与JWT令牌
输出：
feat(auth): 实现基于JWT的认证
添加登录端点和令牌验证中间件
**示例2：**
输入：修复了日期显示不正确的错误
输出：
fix(reports): 修正时区转换中的日期格式
3. 提供实用脚本
预制脚本比生成代码更可靠：
## 实用脚本
**analyze_form.py**：从PDF提取表单字段
```bash
python scripts/analyze_form.py input.pdf > fields.json
validate_boxes.py：检查重叠字段
python scripts/validate_boxes.py fields.json
### 4. 列出所需包
预先指定依赖项：
```markdown
## 要求
```bash
pip install pypdf pdfplumber
### 5. 实现验证循环
对于质量关键任务，强制执行验证检查：
```markdown
## 工作流程
1. 进行您的编辑
2. **立即验证**：`python scripts/validate.py`
3. 如果验证失败：
- 查看错误消息
- 修复问题
- 再次运行验证
4. **仅当验证通过时才继续**
6. 使用带清单的工作流程
对于复杂的多步骤操作：
## 任务进度
- [ ] 步骤1：分析表单
- [ ] 步骤2：创建映射
- [ ] 步骤3：验证映射
- [ ] 步骤4：填写表单
- [ ] 步骤5：验证输出
7. 限制工具访问（可选）
限制Claude可以使用的工具：
---
name: 安全文件读取器
description: 读取文件而不进行更改
allowed-tools: Read, Grep, Glob
---
8. 匹配任务脆弱性的特异性
高自由度（多种方法有效）：
## 代码审查流程
1. 分析代码结构
2. 检查潜在错误
3. 建议可读性改进
4. 验证项目约定
低自由度（需要精确顺序）：
## 数据库迁移
精确运行此命令（不要修改）：
```bash
python scripts/migrate.py --verify --backup
## 调试
### 技能无法激活？
**检查描述特异性**：
- 太模糊：`帮助处理文档`
- 具体：`从PDF中提取文本和表格。当处理PDF文件或用户提到PDF、表单或提取时使用。`
**在描述中包含何时使用触发器**，以便Claude识别您的任务。
### 多个技能冲突？
使用不同的触发术语：
而不是：
```yaml
# 技能1
description: 用于数据分析
# 技能2
description: 用于分析数据
使用：
# 技能1
description: 分析Excel和CRM导出中的销售数据。
用于销售报告、管道分析和收入跟踪。
# 技能2
description: 分析日志文件和系统指标。
用于性能监控、调试和系统诊断。
检查文件路径
验证技能位置：
# 个人
ls ~/.claude/skills/my-skill/SKILL.md
# 项目
ls .claude/skills/my-skill/SKILL.md
验证YAML语法
无效的YAML阻止加载：
cat SKILL.md | head -n 10
确保：
- 第一行有开头
--- - 内容前有结尾
--- - 有效的YAML（无制表符，正确缩进）
仅使用正斜杠
- ✓ 好：
scripts/helper.py - ✗ 错误：
scripts\helper.py
共享技能
通过git与您的团队共享
- 在
.claude/skills/中创建技能 - 提交到git：
git add .claude/skills/ git commit -m "添加团队技能用于PDF处理" git push - 团队拉取后技能立即可用
测试您的技能
询问Claude匹配您描述的问题：
你能帮我从这个PDF中提取文本吗？
如果描述匹配请求，Claude将自主激活您的技能。