Agent Skills实操心得：Claude Code篇

• 第一部分，对初学者在创建技能时常见的痛点进行分析
• 第二部分，对如何“破解”这些痛点进行经验分享
• 第三部分，通过一个实战案例，手把手教你如何创建行之有效的技能
• 实战案例的完整文件可在我的公众号回复"pdf"进行领取

• 一是目录结构混乱，技能未能生效
• 二是技能描述不会写，导致无法触发技能

准备工作：理解技能的工作机制

首先，我们需要先回答一个问题：Claude推出的技能到底是什么？

简单来讲，技能是Claude为了扩展自身功能而新增的模块化能力。每个技能包含了元数据(技能名称和描述)、指令和可选资源(脚本或模板)。

Claude会在相关时，按需加载这些资源，而不是预先将所有信息加载至上下文。

每个技能可以解决一个特定领域的问题，当你需要处理这个领域的任务时，只需要输入你的请求，Claude会自动将你的请求与所有技能里的description字段进行匹配，如果匹配上，就会触发对应的技能。

第一步：创建正确的目录结构

Claude的技能目录结构就像盖房子一样，地基没打好，房子就不稳。因此，我们首先来看一下标准的目录结构是长什么样的：

~/.claude/skills/        # 个人Skills的主目录├── skill-name/          # 每个Skill必须放在独立的文件夹中    ├── SKILL.md         # 技能的核心文件（首字母必须大写）    ├── scripts/         # 可选：存放可执行脚本    └── references/      # 可选：存放参考文档    └── resources/       # 可选：存放模板或数据

1. 关于技能存放位置

• ～/.claude/skills/是你个人技能的存放位置，适用于你的所有项目。

• 如果仅想在特定项目里使用技能，那么可以通过.claude/skills/来存放你指定的技能。

一句话，想在所有项目中使用个人技能，就通过～/.claude/skills来存放；只想在特定项目里使用技能，则通过.claude/skills/来存放。

2. 关于技能的文件夹命名

作为包含SKILL.md的技能文件夹，确保文件夹名称与技能名称相匹配更有利于后续的组织和识别。

因此，我是建议技能文件夹名称和SKILL.md的技能名称保持一致。

3. 关于SKILL.md的文件名

根据官方要求，SKILL.md的文件名必须大写。

为什么必须大写呢？

这块儿主要是考虑到不同系统(如Linux和macOS)之间对大小写敏感程度的差异而可能导致的兼容问题。

所以为了确保跨平台的兼容性，官方建议始终使用SKILL.md作为文件名。

4. 关于可选资源

技能的脚本、参考文档或其他资源可结合实际需要去有选择性地添加。

若需求较为简单，通过编排提示词就能解决，那只需通过SKILL.md就能满足。

第二步：编写核心文件SKILL.md

SKILL.md作为技能的灵魂，也是最容易出问题的地方。SKILL.md主要包括三部分：名称(name)、描述(description)和指令。

---name: your-skill-namedescription: 简要描述当前技能的功能以及何时使用它---
# 你的技能名称
## 指令[Claude 要遵循的清晰、分步指导]

1. 名称

name字段作为技能的标识，需要使用清晰简洁的描述性名称，并且采用小写字母、数字和连字符。

在对技能名称进行命名时，要确保命名直观且易于理解，避免用冗长的描述来表达。

有效示例

• processing-pdfs [处理PDF文件]

• analyzing-spreadsheets [分析电子表格]

• managing-databases [管理数据库]

需避免的命名示例

• 模糊的名称：helper、tools

• 过于通用：documents、data、files

2. 描述

description字段作为触发技能的关键，必须包含技能的功能以及何时使用技能。

始终用第三人称编写

因为技能名称和技能描述都会在Claude启动时被注入到系统提示里，此时关于技能的元数据(技能名称和描述)就成为了Claude理解自身的一部分。

此时若在描述里使用了第一人称或者第二人称的描述，会造成视角混乱，从而使得Claude不能正确选择合适的技能。示例如下：


# 好的描述description: 处理Excel文件并生成报告# 应避免的描述description: 我可以帮助您处理Excel文件description: 您可以使用此功能处理Excel文件

有效示例

# PDF 处理技能description: 从 PDF 文件中提取文本和表格、填充表单、合并文档。在处理 PDF 文件或用户提及 PDF、表单或文档提取时使用。# Excel 分析技能description: 分析 Excel 电子表格、创建数据透视表、生成图表。在分析 Excel 文件、电子表格、表格数据或 .xlsx 文件时使用。

需避免的模糊描述

description: 帮助处理文档description: 处理数据description: 对文件进行各种操作

3. 指令

SKILL.md的指令部分是当你的请求与技能描述内容相匹配时，加载到对应上下文窗口的内容。

这部分内容包括但不限于概述、功能流程和参考文件：

• 概述：简明扼要说明技能的核心功能。

• 功能流程：详细说明任务执行时的流程。

• 参考文件：附加相关参考文件等。

在实际编写时，可以用结构化、易于理解和可执行性来评估指令的可行性。

具体来说，我们可以通过Markdown格式来对指令进行结构化编排，以此提升指令整体的可读性。在编写过程中，通过标题层级、项目符号和代码块等去合理组织指令内容。

这种结构化处理不仅降低了理解成本，也为后续的版本迭代或团队协作提供了标准化基础。

第三步：测试你的技能

为了验证技能的真实表现，发现技能中存在的问题，当我们编写完SKILL.md后，需要对技能进行测试和验证。

1. 技能未被触发

技能是否被触发直接关系到你的请求能否被相关技能处理。

在技能目录结构没有问题的前提下，当你的请求发出后未能触发对应技能时，你应该首先排查一下技能的描述是否存在我前面提到的相关问题。

2. 技能执行异常

当技能被触发后，你需要进一步观察当前技能是否按照你的预期执行。

若技能未按照预期执行或者技能按照预期在执行，但输出结果不符合预期时，你需要对SKILL.md的指令部分进行排查。

异常1：输出结果不符合预期

这个异常通常表现在技能被触发， 但输出结果与预期不符。关于这块儿的解决方案，可以从“任务流程描述不够详细”、“占位符使用不正确”和“输出格式未明确定义”三个方面去逐一排查。

异常2：技能执行出错

这个异常通常表现在技能被触发，但执行过程中出现错误。导致错误的原因包括但不限于脚本语法错误、缺少依赖项和文件权限问题。

3. 持续迭代和优化

一个好的技能，一定是在持续的测试和打磨中形成的。对于在测试过程中发现的问题，要分析问题出现的原因，并基于分析结果，进一步对技能的相关文件进行迭代和优化。

三、实战案例

我们中国有句俗语叫“光说不练，假把式”。在AI快速迭代和发展的当下，除了要多看和多想之外，更要多动手。

你看100遍，可能都不如实际动手做几遍。哪怕做错了，重做就行，有啥呢？只要你开始动手做，你就走在了大多数人的前面。

接下来，结合前面讲的内容，用一个实际案例演示一下从0到1创建一个技能，我是怎么做的。

1. 需求分析

在AI飞速发展的当下，对于想在AI领域深耕的人来说，对于AI工具的使用，不仅要知道它能做什么，更要知道它不能做什么，即AI工具的边界和局限有哪些。

对于AI的边界和局限，多数人可能是通过一些自媒体文章或视频来学习，但若想对AI的底层工作原理进行学习，那么通过阅读相关技术论文则是最佳路径。

比如在2025年1月，中国AI公司DeepSeek在arXiv上发布了DeepSeek-R1推理模型的技术论文，该论文成为2025年开源推理模型领域的重要突破。

但对于多数非技术背景的人来说，“技术论文”这四个字一出来，可能多数人就已经被劝退了。

因为多数技术论文都是用英文编写，并且论文中还涉及到很多技术概念和计算公式，这些因素都是我们想了解一篇论文内容的关键阻碍。

那么能不能有一个这样的技能：我提供PDF格式的论文给它，它先帮我读一遍论文，再用通俗易懂的语言为我讲解论文的核心内容，最后将讲解内容自动保存到电脑桌面，方便我后续查看。

结合上述需求，这个技能需要具备以下功能：

• 支持读取PDF格式的论文内容

• 支持用通俗易懂的语言来对读取内容进行结构化讲解

• 支持将讲解内容转换为DOCX格式并保存至桌面

现在我们就来搭建这个技能，话不多说，我们正式开始。

2. 创建步骤详解

第一步：创建技能文件夹

创建技能文件夹是创建技能的第一步，按照我们前面讲到的规范，技能文件夹的命名建议与SKILL.md里name字段保持一致。

我们通过命令行来创建一个名为 paper-explainer 的文件夹：

mkdir -p ~/.claude/skills/paper-explainer

第二步：创建SKILL.md

技能文件夹创建完成后，我们需要通过命令行在文件夹内创建SKILL.md文件：

touch ~/.claude/skills/paper-explainer/SKILL.md

若不习惯用命令行创建文件夹和文件，也可以在官方指定位置手动创建。这块儿我在前面的 破局指南->关于技能存在位置 小节里有具体说明。

第三步：编写SKILL.md

创建好SKILL.md后，就要进入到创建技能的核心环节：编写SKILL.md。

编写技能名称

因为我们这个技能的核心功能是对技术论文进行讲解，所以结合这个功能的关键词论文和讲解，该技能的名称我们命名为：paper-explainer。

---name: paper-explainer---

编写技能描述

结合前面讲到的技能描述相关规范，我们先逐一回答下面两个问题。

1 这个技能可以做什么？

我们的这个技能可以读取PDF格式的技术论文，用通俗易懂的语言进行详细讲解，并以.docx格式输出讲解文档到本地桌面。

1 这个技能在什么场景下被使用？

这个技能在用户明确要求讲解、解释或分析PDF论文时使用。

结合两个问题的回答，我们对该技能的描述也就出来了：

---name: paper-explainerdescription: 读取PDF格式的学术论文，用通俗易懂的语言进行详细讲解，并以.docx格式输出讲解文档到本地桌面。当用户明确要求讲解、解释或分析PDF论文时使用。---

编写技能指令

技能的名称和描述完成后，我们开始对SKILL.md的指令部分进行编写。

技能在被触发后会加载技能里的指令内容到上下文窗口。因此，触发技能后，系统应该如何对相关需求进行处理，就是指令部分所要明确的。

在当前的案例里，在指令部分，我们主要对技能的核心功能和工作流程进行了明确定义和说明。

1 明确技能的核心功能

在核心功能方面，我们对读取论文内容后的讲解风格和格式进行细化。

## 核心功能1. 读取PDF论文内容（使用 pypdf 库直接提取，避免云端处理的可靠性问题）2. 用通俗易懂的语言、类比和例子讲解复杂概念3. 采用对话式讲解风格，像在讲解给听众听4. 生成结构化的Markdown讲解内容5. 调用脚本将讲解内容转换为DOCX格式并保存到桌面

1 明确技能的工作流程

结合技能的核心功能，当系统触发技能后，将按照以下工作流程进行处理：

[ 考虑到工作流程涉及内容较长，在此只截取主要部分作展示 ]

## 工作流程
### 1. 读取PDF内容使用 `scripts/extract_pdf.py` 脚本直接提取PDF文本内容。
**调用方式：**内容省略
### 2. 生成通俗易懂的讲解采用**对话式讲解风格**，像面对面讲解给听众听。使用以下结构：
#### 推荐的讲解结构：```markdown内容省略```### 3. 生成DOCX文档使用 `scripts/paper_to_docx.py` 脚本将讲解内容转换为DOCX格式。
**调用方式：**内容省略
**脚本说明：**- 脚本会自动将Markdown内容转换为格式化的DOCX文档- 标题会居中显示为一级标题- 会自动添加生成时间戳- 支持标题、列表、粗体、斜体等格式- 默认保存到桌面，文件名格式：`{论文标题}_论文讲解.docx`

SKILL.md 整体效果展示

---name: paper-explainerdescription: 读取PDF格式的学术论文，用通俗易懂的语言进行详细讲解，并以.docx格式输出讲解文档到本地桌面。当用户明确要求讲解、解释或分析PDF论文时使用。---
# 论文讲解 Skill
## 核心功能1. 读取PDF论文内容（使用 pypdf 库直接提取，避免云端处理的可靠性问题）2. 用通俗易懂的语言、类比和例子讲解复杂概念3. 采用对话式讲解风格，像在讲解给听众听4. 生成结构化的Markdown讲解内容5. 调用脚本将讲解内容转换为DOCX格式并保存到桌面
## 工作流程
### 1. 读取PDF内容使用 `scripts/extract_pdf.py` 脚本直接提取PDF文本内容。
**调用方式：**内容省略
### 2. 生成通俗易懂的讲解采用**对话式讲解风格**，像面对面讲解给听众听。使用以下结构：
#### 推荐的讲解结构：```markdown内容省略```
### 3. 生成DOCX文档使用 `scripts/paper_to_docx.py` 脚本将讲解内容转换为DOCX格式。
**调用方式：**内容省略
**脚本说明：**- 脚本会自动将Markdown内容转换为格式化的DOCX文档- 标题会居中显示为一级标题- 会自动添加生成时间戳- 支持标题、列表、粗体、斜体等格式- 默认保存到桌面，文件名格式：`{论文标题}_论文讲解.docx`
...

第四步：添加脚本

关于脚本，我在前面有说过，根据实际需要来判断是否需要添加。这一块儿属于可选项，而非必选项。

在当前的案例里，因为需要通过第三方库去提取PDF文件的文本，并且在对提取文本进行解读后，要将解读文本以DOCX格式自动保存到本地桌面。

所以我在SKILL.md里添加了两个脚本的调用：

• 一是读取PDF内容所需的脚本

• 二是将讲解内容转换格式所需的脚本

为了确保SKILL.md的内容不要过于冗长，我仅在SKILL.md里明确调用脚本文件的路径和方式，并未将完整脚本放在SKILL.md里。

若涉及到的相关脚本或者参考文档很长，我们都可以在技能文件夹根目录下对应的脚本/参考文件夹里去单独进行编写。

关于脚本这一块儿如何编写属于编程部分，并非今天我所要讲的主要内容，在此也不过多赘述了。

第五步：测试技能

当SKILL.md和相关脚本编写完后，在正式打包前，我们还需要对当前技能进行内部测试，以验证当前技能是否能被正常触发并且按照我们预期的工作流程进行相关处理。

关于测试技能这块儿在前面已有说明，在此不过多赘述。

第六步：打包技能

当技能测试通过后，就可以通过自然语言，要求Claude Code对指定技能进行打包。

3. 技能最终效果展示

我使用的技术论文是DeepSeek前段时间新发布的，论文原标题如下图左一所示。

保存到桌面的.docx格式文档，我是通过Mac的Pages文稿进行查看。

写在最后

在过去的几年里，Agent自身能力从一开始的函数调用到MCP，再从MCP到如今的技能，我们在这个过程中能够真切的感受到，Agent的能力在不断的得到提升和扩展。

随着Agent能力的不断提升，能够做的事情也不再仅仅局限于简单的问答。就如本文所讲到的技能，可以将Agent从通用的AI助手，打造成深度嵌入你日常生活或工作的领域专家。

在AI这波技术浪潮引领时代变革的当下，作为个人的我们，要紧跟时代的步伐，持续学习；同时，也要控制好自身的步速。

有时候快可能反而是慢，而慢有时候可能反而是快。找到适合自己的学习节奏，避免盲目跟风，也避免自我内耗。