我要投稿

Agent Skills实操心得：Claude Code篇

发布日期：2026-02-13 06:00:07 浏览次数： 1545

作者：木昜因心

微信搜一搜，关注“木昜因心”

- ｜想，都是问题；做，才是答案。｜ -

引言：你是否卡在Skills入门第一步？

[ Skills，中文翻译为技能，为方便阅读，本文统一用技能来代表Skills。 ]

你是不是也遇到过这种情况？

对着Claude的技能官方文档看了半天，准备创建第一个技能时，却发现自己连技能的目录结构都还没搞明白？

别担心，今天我们就来聊聊在Claude Code创建技能时，那些让人头痛的点，以及我的一些实操心得。

文章概要

本文主要分为三个部分：

第一部分，对初学者在创建技能时常见的痛点进行分析
第二部分，对如何“破解”这些痛点进行经验分享
第三部分，通过一个实战案例，手把手教你如何创建行之有效的技能

实战案例的完整文件可在我的公众号回复"pdf"进行领取

下面，我们开始今天的正文。

一、直击新手痛点

初学者刚开始创建自己的第一个技能时，首先要面对的是两个痛点：

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

我们逐一来说。

1. 目录结构混乱，导致技能不生效

包括我在内的很多初学者，在刚开始上手创建第一个技能时，对于技能的目录结构不够重视。

哪怕按照官方文档照猫画虎，但多数人在刚开始实践时也会因目录结构的问题导致整个技能无法生效。

可能有的初学者对此表示疑惑。其实Claude的技能系统是一个非常严格的模块化体系，目录结构就是这个体系的骨架，其核心目的是为了保证技能的一致性和可维护性。

比如，你创建的技能是存放在个人技能的文件夹里，还是存放在特定项目的文件夹里，这个取决于你的实际需求。不同的存放位置会直接影响技能的适用范围，这一块儿后面我会讲到。

再比如，每个技能文件夹里都必须有一个SKILL.md，并且这个文件必须存放在技能文件夹的根目录下，这是技能发现和加载机制的核心要求。

若上述原则未遵守或者存放位置出现错误，那技能将无法被Claude所识别和发现，自然也就不会在你请求时被触发。

关于目录结构这块儿，当你真正理解相关规则后，就会发现这个规则可以让你的技能更有条理，更容易分享和复用。

2. 技能描述不会写，导致无法触发技能

当目录结构没有问题后，你重新发起请求，可能又会遇到技能无法被触发的情况。此时，你可以重点检查一下SKILL.md里的description字段的描述是否存在问题。

因description字段的描述过于宽泛、模糊或者笼统而造成Claude无法触发对应技能也是刚开始编写SKILL.md时经常遇到的问题。

很多人编写SKILL.md时，最容易忽视的就是description字段。看起来只是一段普通的描述文字，实际上它决定了Claude什么时候会使用你的技能。

一个好的description不仅描述技能的功能，更是为Claude提供精确的触发条件。花时间优化description，你的技能才能真正发挥作用。

二、破局指南

针对前面相关痛点，我们应该如何“破局”呢？

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

首先，我们需要先回答一个问题：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`
...