如何编写一个 skill | Zegging's Tech Blog

引用

代码

pdf-parsing.zip

第一步：理解 Skill 的本质

不要被技术术语吓倒。一个 Skill 本质上就是一个文件夹，里面最核心的只有一个文件：SKILL.md。

文件夹名 = 技能的名字。
SKILL.md = 技能的说明书（告诉 Agent 什么时候用、怎么用）。
其他文件（可选）= 脚本（代码）、模板或参考资料。

第二步：创建你的第一个 Skill

我们要创建一个简单的 Skill，比如一个**“PDF 文本提取助手”**。

1. 建立文件夹结构

在你的电脑上创建一个文件夹，命名为 pdf-parsing（注意：名称通常用小写字母和连字符）。结构如下：

pdf-parsing/
├── SKILL.md          <-- 必须有：大脑（说明书）
└── scripts/          <-- 可选：手脚（执行代码）
    └── parse_pdf.py

2. 编写核心文件：SKILL.md

在 pdf-parsing 文件夹内新建 SKILL.md 文件。这个文件分为两部分：元数据（Frontmatter）和指令正文。

下面是一份最小可用的示例（你可以先照抄跑起来）：

---
name: pdf-processing
description: 当用户需要从PDF文件中提取文本、分析内容或读取PDF时使用此技能。
---

# PDF 处理指南

## 何时使用

当用户上传了 PDF 文件并要求总结、提取文字或回答关于该文件的问题时。

## 操作步骤

请使用本技能包中提供的 Python 脚本来解析 PDF。

1. **执行脚本**：
   使用以下命令运行脚本，将 `/path/to/file.pdf` 替换为用户实际提供的文件路径：

   ```bash
   python3 scripts/parse_pdf.py --file_path "/path/to/file.pdf"
   ```

2. 输出处理：脚本会返回提取的文本。请基于提取的内容回答用户的问题。

关键点解析：顶部的 --- 区域（元数据）是给 Agent 看的“名片”。

name：技能名称（Agent 内部识别用）。
description：Agent 会在启动时通过这句话判断“我现在要不要用这个技能”。
正文区域：这是给 Agent 看的“操作手册”。当 Agent 决定使用这个技能后，它会读取这部分内容，按步骤执行。

3. 编写工具脚本（可选但推荐）

如果任务很简单（比如写一段特定风格的文案），你不需要脚本。但如果你想让 Agent 拥有“超能力”（如处理文件），你就需要给它配代码。

在 pdf-parsing 文件夹下新建 scripts 文件夹，并在里面创建 parse_pdf.py：

# scripts/parse_pdf.py
import argparse
# 这是一个模拟脚本，实际使用可能需要安装 PyPDF2 库
# pip install PyPDF2

def extract_text(file_path):
    # 这里写实际的解析逻辑，为了演示简单，我们模拟一下
    print(f"成功从文件 {file_path} 中提取了文本内容：")
    print("--------------------------------------------------")
    print("这里是 PDF 的正文内容...（模拟数据）")
    print("--------------------------------------------------")

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--file_path", type=str, required=True)
    args = parser.parse_args()
    extract_text(args.file_path)

第三步：安装与运行

做好了技能包，怎么让 Agent（如 Claude Code 或 TRAE）用起来呢？

1. 放置位置

全局通用：将 pdf-parsing 文件夹放到 ~/.claude/skills/（MacOS/Linux）或对应的用户目录下。这样你在任何项目中都能用它。
项目专用：将文件夹放到你当前项目根目录下的 .claude/skills/ 中。

2. 触发使用

重启你的 Agent 工具（如 Claude Code）。
自动触发：直接对 Agent 说：“帮我读一下桌面上的 resume.pdf。” 因为你的 description 写了“当用户需要…读取PDF时使用”，Agent 会自动匹配并加载这个 Skill。
手动触发：你也可以输入 /pdf-processing（取决于你的技能名称）来强制调用。

第四步：进阶技巧（如何写得更好）

当你熟悉了基本流程，可以注意以下几点来提升 Skill 的质量：

单一职责：不要试图做一个“万能 Skill”。一个 Skill 只做一件事，比如“写周报”是一个 Skill，“查汇率”是另一个。这样 Agent 更容易准确调用。
给例子：在 SKILL.md 里不仅写指令，最好给出一两个“输入 -> 输出”的例子。例如：“如果用户输入 X，你应该输出 Y”。这对规范 Agent 的输出格式非常有效。
渐进式加载原理：Agent 启动时只会加载 Level 1（元数据，仅约 100 tokens）。只有当它决定使用技能时，才会加载 Level 2（SKILL.md 正文）。脚本代码（Level 3）永远不会进入上下文，只返回运行结果。这种设计让你可以在项目中安装几百个 Skill 而不会“撑爆”模型的大脑。
利用自动化工具：如果你懒得手写，甚至可以安装一个名为 skill-creator 的官方 Skill。安装后，你只需对 Agent 说：“帮我写一个能自动把 CSV 转成 Excel 的技能”，它就会自动帮你生成代码和 Markdown 文件。

总结

编写 Skill 的核心心法是：把你的专业经验（SOP）变成文档，把你的工具变成脚本，然后打包告诉 Agent 什么时候用。

继续阅读：SKILL 与 MCP 的区别与应用