什么是 Agent Skills？

上周 Claude 又发布了一个 Agent Skills 功能，这个技能工具主要包含指令、脚本和资源的文件夹，在处理特定专业任务时，Claude 会按需加载这些文件夹内容以获取更专业的领域知识Agent Skills 是扩展 Claude 功能的模块化工具。它们通过包含指令、脚本和资源的文件夹，将专业知识封装成可复用的功能。每个 Skill 包含一个 SKILL.md 文件，其中包含描述、指令和相关资源。

先决条件

• 使用 Claude Code 版本 1.0 或更高版本

Skills 如何调用

Claude 根据您的请求和 Skill 的描述自主选择何时使用它们，而不是用户明确调用。这与斜杠命令不同，斜杠命令是用户显式调用的（例如 /command）。

优势

• 扩展 Claude 的能力，定制您的工作流
• 通过 Git 在团队中共享知识
• 减少重复输入
• 组合多个 Skills 执行复杂任务

创建 Skill

Skills 存储为包含 SKILL.md 文件的目录。

个人 Skills

个人 Skills 存储在 ~/.claude/skills/ 目录中，适合个人工作流或实验性开发。

mkdir -p ~/.claude/skills/my-skill-name

项目 Skills

项目 Skills 存储在 .claude/skills/ 目录中，适合团队协作和共享知识。

mkdir -p .claude/skills/my-skill-name

插件 Skills

Skills 也可以来自已安装的插件。插件 Skills 与其他类型的 Skills 工作方式一样。

编写 SKILL.md

创建一个包含 YAML 前置元数据和 Markdown 内容的 SKILL.md 文件：

---
name: Your Skill Name
description: A brief description of what the skill does and when to use it
---

# Your Skill Name

## Instructions
Provide step-by-step guidance on how to use this skill.

## Examples
Provide concrete examples of how to use the skill.

添加支持文件

您可以在 SKILL.md 文件旁边创建额外的文件（如脚本、模板等）：

my-skill/
├── SKILL.md
├── reference.md
├── examples.md
├── scripts/
│   └── helper.py
└── templates/
    └── template.txt

使用 allowed-tools 限制工具访问

可以通过 allowed-tools 元数据字段来限制 Claude 在 Skill 激活时使用的工具。例如，只允许读取文件：

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

查看可用的 Skills

Claude 会自动发现来自以下三个来源的 Skills：

1. 个人 Skills：~/.claude/skills/
2. 项目 Skills：.claude/skills/
3. 插件 Skills：来自已安装插件

要查看所有可用的 Skills，可以询问 Claude：

What Skills are available?

测试 Skill

创建 Skill 后，通过提出相关问题来测试它。例如，如果描述提到“PDF 文件”：

Can you help me extract text from this PDF?

Claude 会根据您的请求自动激活匹配的 Skill。

调试 Skill

如果 Claude 没有使用您的 Skill，请检查以下问题：

1. 描述是否具体：明确列出何时使用 Skill 及其功能。
2. 文件路径是否正确：确保 SKILL.md 文件在正确的位置。
3. YAML 语法是否有效：确保没有语法错误。

使用调试模式查看详细错误：

claude --debug

与团队共享 Skills

推荐通过插件共享 Skills，也可以将 Skills 直接提交到项目仓库，通过 Git 分享给团队成员。

步骤：

1. 在 skills/ 目录中创建包含 Skills 的插件。
2. 将插件推送到市场。
3. 团队成员安装插件后即可使用。

更新 Skill

直接编辑 SKILL.md 文件，并通过重新启动 Claude 来应用更改。

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

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

删除 Skill

删除 Skill 目录：

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

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

最佳实践

保持 Skills 专注

每个 Skill 应该解决一个特定功能：

• 专注：如“PDF 表单填写”
• 不专注：如“文档处理”（应拆分为多个 Skill）

编写清晰的描述

确保描述清楚列出 Skill 的功能和何时使用它：

description: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or analyzing tabular data in .xlsx format.

与团队一起测试

让团队成员使用 Skills 并提供反馈，确保它们按预期工作。

记录版本历史

可以在 SKILL.md 文件中记录版本历史，协助团队成员了解变化：

## 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

故障排除

Claude 不使用我的 Skill

症状：您询问相关问题，但 Claude 不使用您的 Skill。

解决方案：

1. 确保描述足够具体，能清晰指示何时激活该 Skill。
2. 验证 YAML 语法是否有效。
3. 确保 Skill 存储在正确的目录。

Skill 无法正常工作

症状：Skill 加载但不能执行。

解决方案：

1. 检查是否缺少必要的依赖项。
2. 验证脚本是否有执行权限。

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

多个 Skills 冲突

症状：Claude 激活错误的 Skill。

解决方案：

通过描述中的不同触发术语明确区分不同的 Skills。例如：

# Skill 1
description: Analyze sales data in Excel files and CRM exports.

# Skill 2
description: Analyze log files and system metrics data.

示例

简单 Skill（单文件）

commit-helper/
└── SKILL.md

---
name: Generating Commit Messages
description: Generates commit messages from git diffs.
---

# Generating Commit Messages

## Instructions

1. Run `git diff --staged`
2. I will suggest a commit message with a summary, description, and affected components.

具有工具权限的 Skill

code-reviewer/
└── SKILL.md

---
name: Code Reviewer
description: Review code for best practices.
allowed-tools: Read, Grep, Glob
---

# Code Reviewer

## Instructions

1. Use the Read tool to view files.
2. Use Grep to search for patterns.
3. Provide detailed feedback on code quality.

多文件 Skill

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