Claude Skills 实践指南 🎯

"将专业知识封装为可复用的模块化能力 — 让 AI 真正理解你的工作流程。"

1. Claude Skills 概述

1.1 什么是 Agent Skills

Agent Skills 是 Anthropic 于 2025 年 10 月 16 日 正式推出的功能，用于扩展 Claude 的能力。Skills 是模块化的能力包，每个 Skill 由一个 SKILL.md 文件（包含指令）以及可选的支持文件（脚本、模板、资源）组成。

深入了解 Skills 的架构和实际应用，请阅读 Anthropic 工程博客：Equipping agents for the real world with Agent Skills

传统方式:
  每次对话都要重复描述需求 → 结果不一致 → 知识无法复用

Agent Skills:
  SKILL.md 定义一次 → Claude 自动识别并调用 → 一致的高质量输出

1.2 Skills vs Slash Commands

理解 Skills 的关键在于它们是 model-invoked（模型调用） 的：

特性	Agent Skills	Slash Commands
触发方式	Model-invoked - Claude 自主决定何时使用	User-invoked - 用户显式输入 `/command`
匹配机制	基于请求内容和 Skill 描述自动匹配	精确命令匹配
使用场景	复杂工作流、专业领域知识	简单、明确的操作

1.3 核心优势

扩展能力: 为特定工作流定制 Claude 的能力
团队共享: 通过 git 在团队间共享专业知识
减少重复: 避免反复输入相同的提示词
可组合性: 多个 Skills 可以组合处理复杂任务

2. Skills 存储位置

2.1 三种 Skill 类型

┌─────────────────────────────────────────────────────────────────┐
│                    Skill Storage Locations                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  1. Personal Skills (个人技能)                                   │
│     位置: ~/.claude/skills/                                      │
│     适用: 个人工作流、实验性技能、个人生产力工具                 │
│     可见范围: 仅当前用户的所有项目                               │
│                                                                  │
│  2. Project Skills (项目技能)                                    │
│     位置: .claude/skills/ (项目根目录)                           │
│     适用: 团队工作流、项目规范、共享工具                         │
│     可见范围: 该项目的所有协作者                                 │
│     特点: 通过 git 自动同步给团队成员                            │
│                                                                  │
│  3. Plugin Skills (插件技能)                                     │
│     位置: 随 Claude Code 插件安装                                │
│     适用: 第三方扩展能力                                         │
│     可见范围: 安装该插件的用户                                   │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

2.2 创建 Skill 目录

bash

# 创建个人 Skill
mkdir -p ~/.claude/skills/my-skill-name

# 创建项目 Skill
mkdir -p .claude/skills/my-skill-name

3. 编写 SKILL.md

3.1 基本结构

每个 Skill 必须包含一个 SKILL.md 文件，使用 YAML frontmatter + Markdown 内容：

markdown

---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
---

# Your Skill Name

## Instructions
Provide clear, step-by-step guidance for Claude.

## Examples
Show concrete examples of using this Skill.

3.2 字段说明

字段	必需	规则
`name`	✅	小写字母、数字、连字符，最多 64 字符
`description`	✅	描述功能和使用时机，最多 1024 字符
`allowed-tools`	❌	限制 Claude 可使用的工具列表

⚠️ 关键: description 字段决定了 Claude 何时发现并使用你的 Skill。必须包含：

做什么 - Skill 的功能
何时用 - 触发使用的场景和关键词

3.3 description 最佳实践

yaml

# ❌ 太模糊 - Claude 不知道何时使用
description: Helps with documents

# ❌ 仍然不够具体
description: For data analysis

# ✅ 清晰具体 - 包含功能描述和触发场景
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.

# ✅ 另一个好例子
description: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or analyzing tabular data in .xlsx format.

3.4 使用 allowed-tools 限制工具

当你需要限制 Skill 的能力范围时，使用 allowed-tools：

markdown

---
name: safe-file-reader
description: Read files without making changes. Use when you need read-only file access.
allowed-tools: Read, Grep, Glob
---

# Safe File Reader

This Skill provides read-only file access.

## Instructions
1. Use Read to view file contents
2. Use Grep to search within files  
3. Use Glob to find files by pattern

当此 Skill 激活时，Claude 只能使用指定的工具（Read, Grep, Glob），无需额外请求权限。

适用场景:

只读 Skill，不应修改文件
有限范围的 Skill，如仅数据分析
安全敏感的工作流

4. 添加支持文件

4.1 目录结构

my-skill/
├── SKILL.md           # 必需 - 主指令文件
├── reference.md       # 可选 - 详细参考文档
├── examples.md        # 可选 - 使用示例
├── scripts/           # 可选 - 辅助脚本
│   └── helper.py
└── templates/         # 可选 - 模板文件
    └── template.txt

4.2 在 SKILL.md 中引用文件

markdown

---
name: pdf-processing
description: Extract text, fill forms, merge PDFs. Use when working with PDF files.
---

# 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

bash

pip install pypdf pdfplumber

4.3 渐进式披露 (Progressive Disclosure)

Claude 采用渐进式披露策略 — 只在需要时才读取额外文件：

┌─────────────────────────────────────────────────────────────────┐
│              Progressive Disclosure Architecture                 │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  第一层: 始终加载                                                │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │ name: "pdf-processing"                                  │    │
│  │ description: "Extract text, fill forms, merge PDFs..."  │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                  │
│                      用户请求匹配?                               │
│                         ↓ Yes                                    │
│                                                                  │
│  第二层: 按需加载                                                │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │ SKILL.md 主体内容                                       │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                  │
│                    需要更多细节?                                 │
│                         ↓ Yes                                    │
│                                                                  │
│  第三层: 深度加载                                                │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │ reference.md, examples.md, scripts/                     │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                  │
│  优势: 高效管理上下文窗口，避免不必要的 token 消耗              │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

5. 实战示例

5.1 简单 Skill（单文件）

commit-helper/
└── SKILL.md

markdown

---
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 ("Add feature" not "Added feature")
- Explain what and why, not how
- Reference issue numbers when applicable

5.2 带工具限制的 Skill

code-reviewer/
└── SKILL.md

markdown

---
name: code-reviewer
description: Review code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.
allowed-tools: Read, Grep, Glob
---

# Code Reviewer

## Review checklist

1. Code organization and structure
2. Error handling
3. Performance considerations
4. Security concerns
5. Test coverage

## Instructions

1. Read the target files using Read tool
2. Search for patterns using Grep
3. Find related files using Glob
4. Provide detailed feedback on code quality

5.3 多文件 Skill

pdf-processing/
├── SKILL.md
├── FORMS.md
├── REFERENCE.md
└── scripts/
    ├── fill_form.py
    └── validate.py

SKILL.md:

markdown

---
name: pdf-processing
description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction. Requires pypdf and pdfplumber packages.
---

# 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

Packages must be installed in your environment:

bash

pip install pypdf pdfplumber


**FORMS.md**:

```markdown
# PDF Form Filling

## Fill a form programmatically

```python
from scripts.fill_form import fill_pdf_form

data = {
    "name": "John Doe",
    "date": "2025-10-16",
    "signature": True
}

fill_pdf_form("input.pdf", "output.pdf", data)

Supported field types

Text fields
Checkboxes
Radio buttons
Dropdown selections


---

## 6. 查看和测试 Skills

### 6.1 查看可用 Skills

Skills 会从三个位置自动发现：

```bash
# 方式 1: 直接询问 Claude
What Skills are available?
# 或
List all available Skills

# 方式 2: 检查文件系统
# 查看个人 Skills
ls ~/.claude/skills/

# 查看项目 Skills
ls .claude/skills/

# 查看特定 Skill 内容
cat ~/.claude/skills/my-skill/SKILL.md

6.2 测试 Skill

创建 Skill 后，通过提问来测试是否能被正确触发：

# 如果你的 description 提到 "PDF files"
Can you help me extract text from this PDF?

# 如果你的 description 提到 "Excel spreadsheets"  
I need to analyze this Excel file and create a pivot table.

# 如果你的 description 提到 "commit messages"
Help me write a commit message for these staged changes.

记住: 你不需要显式调用 Skill — Claude 会根据请求内容自动匹配和使用。

7. 调试 Skills

7.1 Skill 未被使用

症状: 你提出了相关问题，但 Claude 没有使用你的 Skill。

检查 1: description 是否足够具体

yaml

# ❌ 太泛泛
description: Helps with data

# ✅ 具体明确
description: Analyze Excel spreadsheets, generate pivot tables, create charts. Use when working with Excel files, spreadsheets, or .xlsx files.

检查 2: 文件路径是否正确

bash

# 个人 Skills
ls ~/.claude/skills/my-skill/SKILL.md

# 项目 Skills  
ls .claude/skills/my-skill/SKILL.md

检查 3: YAML 语法是否有效

bash

# 查看 frontmatter
cat SKILL.md | head -n 10

# 确保:
# - 第 1 行是 ---
# - Markdown 内容前有闭合的 ---
# - 使用空格缩进（不是 Tab）
# - 含特殊字符的字符串加引号

检查 4: 使用调试模式

bash

claude --debug

7.2 多个 Skills 冲突

症状: Claude 使用了错误的 Skill 或在相似 Skills 间混淆。

解决方案: 使用明确不同的触发词

yaml

# ❌ 描述太相似
# Skill 1
description: For data analysis
# Skill 2  
description: For analyzing data

# ✅ 使用不同的触发词
# Skill 1
description: Analyze sales data in Excel files and CRM exports. Use for sales reports, pipeline analysis, and revenue tracking.
# Skill 2
description: Analyze log files and system metrics data. Use for performance monitoring, debugging, and system diagnostics.

7.3 Skill 有错误

检查脚本执行权限:

bash

chmod +x .claude/skills/my-skill/scripts/*.py

检查文件路径格式 - 始终使用正斜杠:

✅ scripts/helper.py    # Unix 风格
❌ scripts\helper.py    # Windows 风格（错误）

8. 团队共享 Skills

8.1 推荐方式: 通过插件分发

创建包含 Skills 的插件（skills/ 目录）
将插件发布到 marketplace
团队成员安装插件即可使用

详见官方文档: Add Skills to your plugin

8.2 通过 Git 共享项目 Skills

Step 1: 添加 Skill 到项目

bash

mkdir -p .claude/skills/team-skill
# 创建 SKILL.md

Step 2: 提交到 git

bash

git add .claude/skills/
git commit -m "Add team Skill for PDF processing"
git push

Step 3: 团队成员自动获取

bash

git pull
claude  # Skills 立即可用

8.3 更新 Skill

直接编辑 SKILL.md，更改在下次启动 Claude Code 时生效：

bash

# 个人 Skill
code ~/.claude/skills/my-skill/SKILL.md

# 项目 Skill
code .claude/skills/my-skill/SKILL.md

8.4 移除 Skill

bash

# 个人
rm -rf ~/.claude/skills/my-skill

# 项目
rm -rf .claude/skills/my-skill
git commit -m "Remove unused Skill"

9. 最佳实践

9.1 保持 Skills 专注

一个 Skill 应该只解决一个能力：

✅ 专注的 Skills:
• "PDF form filling"
• "Excel data analysis"  
• "Git commit messages"

❌ 太宽泛的 Skills:
• "Document processing" → 应拆分为多个
• "Data tools" → 应按数据类型或操作拆分

9.2 编写清晰的描述

在 description 中包含具体的触发词：

yaml

# ✅ 清晰 - 包含功能和触发场景
description: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or analyzing tabular data in .xlsx format.

# ❌ 模糊
description: For files

9.3 记录版本变更

在 SKILL.md 中添加版本历史：

markdown

# My Skill

## Version History
- v2.0.0 (2025-10-01): Breaking changes to API
- v1.1.0 (2025-09-15): Added new features
- v1.0.0 (2025-09-01): Initial release

9.4 与团队测试

Skill 是否在预期场景下被触发？
指令是否清晰？
是否覆盖了边界情况？

10. 安全注意事项

10.1 只使用可信来源的 Skills

⚠️ 警告: 恶意 Skill 可能指导 Claude 执行与声明目的不符的操作。

┌─────────────────────────────────────────────────────────────────┐
│                    Skill Trust Levels                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ✅ 可信来源:                                                    │
│  • Anthropic 官方 Skills                                         │
│  • 企业内部审核的 Skills                                         │
│  • 知名开发者的验证 Skills                                       │
│                                                                  │
│  ⚠️ 需谨慎:                                                      │
│  • 公共社区的 Skills                                             │
│  • 未经验证的第三方 Skills                                       │
│                                                                  │
│  ❌ 避免使用:                                                    │
│  • 来源不明的 Skills                                             │
│  • 声明能力与实际代码不符的 Skills                               │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

10.2 使用 allowed-tools 限制权限

对于敏感工作流，明确限制 Skill 可使用的工具：

yaml

---
name: read-only-analyzer
description: Analyze code without making changes
allowed-tools: Read, Grep, Glob
---

10.3 审核 Skill 内容

在使用第三方 Skill 前，检查：

SKILL.md 的指令内容
脚本文件中是否有可疑代码
声明的能力是否与实际匹配

11. 企业应用场景

11.1 品牌合规 Skill

markdown

---
name: brand-compliance
description: Ensure documents follow company brand guidelines. Use when creating presentations, reports, or marketing materials.
---

# Brand Compliance

## Color Palette
- Primary: #1a365d (Navy Blue)
- Secondary: #2d3748 (Dark Gray)
- Accent: #3182ce (Blue)

## Typography
- Headings: Inter, 600 weight
- Body: Inter, 400 weight
- Code: JetBrains Mono

## Logo Usage
- Minimum clear space: 20px
- Never stretch or distort
- Use white version on dark backgrounds

## Templates
See [templates/](templates/) for approved document templates.

11.2 代码规范 Skill

markdown

---
name: code-standards
description: Enforce team coding standards and conventions. Use when reviewing code or creating new files.
allowed-tools: Read, Grep, Glob
---

# Code Standards

## Naming Conventions
- Components: PascalCase (UserProfile.tsx)
- Hooks: camelCase with 'use' prefix (useAuth.ts)
- Utils: camelCase (formatDate.ts)
- Constants: SCREAMING_SNAKE_CASE

## File Structure

src/ ├── components/ # React components ├── hooks/ # Custom hooks ├── utils/ # Utility functions ├── types/ # TypeScript types └── constants/ # Constants and configs


## Import Order
1. React/Next.js
2. Third-party libraries
3. Internal modules
4. Types
5. Styles

11.3 API 文档生成 Skill

markdown

---
name: api-doc-generator
description: Generate API documentation from code. Use when documenting APIs, creating OpenAPI specs, or updating API references.
---

# API Documentation Generator

## Output Format

For each endpoint, document:
1. HTTP method and path
2. Description
3. Request parameters
4. Request body schema
5. Response schema
6. Example request/response
7. Error codes

## Template

```markdown
### `POST /api/users`

Create a new user account.

**Request Body**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| email | string | Yes | User email |
| name | string | Yes | Display name |

**Response** `201 Created`
```json
{
  "id": "user_123",
  "email": "user@example.com",
  "name": "John Doe"
}

12. 关键要点总结

12.1 Skills 核心概念

概念	说明
存储位置	`~/.claude/skills/` (个人) 或 `.claude/skills/` (项目)
必需文件	`SKILL.md`
触发方式	Model-invoked (Claude 自动识别)
分发方式	Git 或插件

12.2 SKILL.md 清单

markdown

---
name: lowercase-with-hyphens    # 必需，≤64字符
description: 功能 + 使用时机      # 必需，≤1024字符
allowed-tools: Tool1, Tool2      # 可选，限制工具
---

# Skill 名称

## Instructions
具体操作指南

## Examples  
使用示例

12.3 快速检查列表

[ ] name 只使用小写字母、数字、连字符
[ ] description 包含功能描述和触发场景
[ ] YAML frontmatter 语法正确（使用空格，不用 Tab）
[ ] 文件路径正确（~/.claude/skills/ 或 .claude/skills/）
[ ] 脚本有执行权限
[ ] 已测试 Skill 能被正确触发

Claude Skills 实践指南 🎯 ​

1. Claude Skills 概述 ​

1.1 什么是 Agent Skills ​

1.2 Skills vs Slash Commands ​

1.3 核心优势 ​

2. Skills 存储位置 ​

2.1 三种 Skill 类型 ​

2.2 创建 Skill 目录 ​

3. 编写 SKILL.md ​

3.1 基本结构 ​

3.2 字段说明 ​

3.3 description 最佳实践 ​

3.4 使用 allowed-tools 限制工具 ​

4. 添加支持文件 ​

4.1 目录结构 ​

4.2 在 SKILL.md 中引用文件 ​

Requirements ​

4.3 渐进式披露 (Progressive Disclosure) ​

5. 实战示例 ​

5.1 简单 Skill（单文件） ​

5.2 带工具限制的 Skill ​

5.3 多文件 Skill ​

Requirements ​

Supported field types ​

6.2 测试 Skill ​

7. 调试 Skills ​

7.1 Skill 未被使用 ​

7.2 多个 Skills 冲突 ​

7.3 Skill 有错误 ​

8. 团队共享 Skills ​

8.1 推荐方式: 通过插件分发 ​

8.2 通过 Git 共享项目 Skills ​

8.3 更新 Skill ​

8.4 移除 Skill ​

9. 最佳实践 ​

9.1 保持 Skills 专注 ​

9.2 编写清晰的描述 ​

9.3 记录版本变更 ​

9.4 与团队测试 ​

10. 安全注意事项 ​

10.1 只使用可信来源的 Skills ​

10.2 使用 allowed-tools 限制权限 ​

10.3 审核 Skill 内容 ​

11. 企业应用场景 ​

11.1 品牌合规 Skill ​

11.2 代码规范 Skill ​

11.3 API 文档生成 Skill ​

12. 关键要点总结 ​

12.1 Skills 核心概念 ​

12.2 SKILL.md 清单 ​

12.3 快速检查列表 ​

延伸阅读 ​

Claude Skills 实践指南 🎯

1. Claude Skills 概述

1.1 什么是 Agent Skills

1.2 Skills vs Slash Commands

1.3 核心优势

2. Skills 存储位置

2.1 三种 Skill 类型

2.2 创建 Skill 目录

3. 编写 SKILL.md

3.1 基本结构

3.2 字段说明

3.3 description 最佳实践

3.4 使用 allowed-tools 限制工具

4. 添加支持文件

4.1 目录结构

4.2 在 SKILL.md 中引用文件

Requirements

4.3 渐进式披露 (Progressive Disclosure)

5. 实战示例

5.1 简单 Skill（单文件）

5.2 带工具限制的 Skill

5.3 多文件 Skill

Requirements

Supported field types

6.2 测试 Skill

7. 调试 Skills

7.1 Skill 未被使用

7.2 多个 Skills 冲突

7.3 Skill 有错误

8. 团队共享 Skills

8.1 推荐方式: 通过插件分发

8.2 通过 Git 共享项目 Skills

8.3 更新 Skill

8.4 移除 Skill

9. 最佳实践

9.1 保持 Skills 专注

9.2 编写清晰的描述

9.3 记录版本变更

9.4 与团队测试

10. 安全注意事项

10.1 只使用可信来源的 Skills

10.2 使用 allowed-tools 限制权限

10.3 审核 Skill 内容

11. 企业应用场景

11.1 品牌合规 Skill

11.2 代码规范 Skill

11.3 API 文档生成 Skill

12. 关键要点总结

12.1 Skills 核心概念

12.2 SKILL.md 清单

12.3 快速检查列表

延伸阅读