从 0 到 1 打造你的第一个 AI 技能：SKILL.md 编写规范与发布实战

天天喝旺仔

283人浏览 · 2026-08-05 13:24:05

天天喝旺仔 · 2026-08-05 13:24:05 发布

从 0 到 1 打造你的第一个 AI 技能：SKILL.md 编写规范与发布实战

导语

你有没有过这样的经历：同样的工具、同一套排查步骤，每隔几天就要给 AI 助手重新讲一遍。今天教它怎么从 PDF 里抽表格，明天换个文件又要从头解释；这次配好一套发布流程，下次新开会话又得复述一遍。经验没有沉淀下来，每次都像在开荒。

其实 AI 助手缺的不是能力，而是“你这套被验证过的做法”。把这做法写成一份结构化文件，它就能在任何支持技能的客户端里被反复调用——这就是 AI 技能（Skill）。本文带你从零写一个真正能用的技能，并把它发布、安装到不同客户端。

声明：本文基于个人使用体验，非商业推广。

一、什么是 AI 技能（Skill）

简单来说，Skill 就是一份写给 AI 助手看的“标准作业程序”。它把某类任务的背景知识、操作步骤、命令和注意事项固化下来，让助手在接到相关需求时自动加载、照着执行，而不是每次都等你口述。

可能有读者会问：这和存一段“提示词模板”有什么区别？模板通常是零散的文本片段，适合一次对话内复制粘贴；而 Skill 是常驻的、带触发条件的“能力插件”，一旦写好，助手会在合适的时机自动调用，不需要你每次手动贴进去。你可以把 Skill 理解成“带使用说明书的提示词”，而 SKILL.md 就是那份说明书。

不同客户端对技能的实现略有差异，但主流做法是统一的：用一份 SKILL.md 文件作为技能的入口。只要这个文件放在客户端约定的 skills/ 目录里，助手启动时就能发现并调用它。这也是为什么同一份技能文件，往往能在多个 AI 客户端之间复用——你写一次，到处能跑。

什么是 AI 技能

小知识：技能文件本质是 Markdown，但多了 frontmatter（文件头元数据）。助手靠 frontmatter 判断“什么时候该用这个技能”，靠正文知道“具体怎么做”。理解这一点，后面写起来就很顺了。

二、一个最小可用的 SKILL.md 长什么样

一份能跑起来的 SKILL.md 只需要两块：frontmatter + 正文。

frontmatter：用 --- 包裹，至少写 name 和 description，是给助手“检索匹配”用的。
正文：就是给助手看的操作说明，可以是步骤、命令、注意事项，甚至是示例代码。

---
name: pdf-table-extract
description: 从 PDF 文件中提取表格并导出为 CSV/Excel。
  当用户需要从 PDF 抽取表格数据、把发票/报表转成结构化文件时使用。
---

# PDF 表格提取

## 何时使用
用户给了 PDF 并希望拿到表格数据。

## 步骤
1. 确认本地已安装 Python 与 pdfplumber。
2. 读取 PDF，定位包含表格的页码。
3. 调用 extract_tables 并导出。

## 注意
- 扫描件需先做 OCR，pdfplumber 无法直接读图。
- 合并单元格会被拆成多行，导出后需人工核对。

description 特别关键：它要写清楚“什么场景用”，因为助手是靠这段文本做匹配决策的。写得越具体，误触发和漏触发都越少。比如不要只写“处理 PDF”，而要写“从 PDF 提取表格为 CSV”。

最小 SKILL.md 结构

三、实战：写一个“PDF 表格提取”技能

光看结构不过瘾，我们把它写成一个真正能用的技能。下面是完整 SKILL.md 的骨架，重点在正文要“可执行”——助手读完就知道敲什么命令。

---
name: pdf-table-extract
description: 从 PDF 提取表格为 CSV。适用于报表、发票、名单等
  结构化抽取；用户说“把这份 PDF 的表格导出来”时调用。
---

# PDF 表格提取

你负责把 PDF 里的表格变成干净的结构化数据。

## 环境检查
先确认依赖，缺失则安装：
```bash
python -c "import pdfplumber" 2>/dev/null || pip install pdfplumber
```

## 提取流程
1. 用 pdfplumber.open 打开文件。
2. 遍历每页 page.extract_tables()，得到二维列表。
3. 写入 CSV，文件名与 PDF 同名。

## 参考代码
```python
import pdfplumber, csv, sys

with pdfplumber.open(sys.argv[1]) as pdf:
    for i, page in enumerate(pdf.pages):
        for table in page.extract_tables():
            with open(f"page_{i}.csv", "w", newline="", encoding="utf-8") as f:
                csv.writer(f).writerows(table)
```

## 边界情况
- 无表格的页直接跳过。
- 表格线缺失时 extract_tables 可能为空，改用 page.find_tables() 定位。

把这份文件存到 ~/.workbuddy/skills/pdf-table-extract/SKILL.md（目录名即技能名），客户端重启后即可通过对话触发。你会发现，以后只要说“帮我把这份 PDF 的表格导出来”，助手就会照着执行，不用再解释一遍环境怎么配、代码怎么写。

PDF 表格提取实战

四、把技能发布到社区

技能写好了，可以只自己用，也可以分享出去。国内有一个 AI 技能社区（SkillHub），上面已沉淀了超过 10 万个技能，搜索、分类、榜单一应俱全。把技能发布到这类社区，本质是三件事：打包、提交、过审。

值得一说的是它的上架机制。每个技能提交后都要走过一条三线并行的安全审核流水线：内容合规过滤、深度漏洞扫描、AI 模型安全评估，三者全部通过才会自动上架，任意一条不通过就直接拒绝。换句话说，你安装到的每个技能都附带一份安全评估报告，这点对“要不要放心装到 AI 助手上”是很实在的保障。

三线安全审核

提示：发布前记得在技能里去掉任何含密钥、内网地址的示例，审核对这类信息很敏感；另外正文里的中文路径、命令也要在干净环境里跑通再提交。

五、安装与跨平台调用

发布之后，别人怎么装？以 SkillHub 为例，它提供的命令行工具，安装一个技能只需要指名 + 指定客户端目录：

# 1. 安装 CLI（首次）
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash

# 2. 搜索技能
skillhub search pdf table

# 3. 安装到指定客户端的 skills 目录
skillhub install pdf-table-extract --dir ~/.workbuddy/skills

--dir 是关键：不同客户端的 skills 目录不同（如 Claude Code 是 ~/.claude/skills/，Cursor 是 ~/.cursor/skills/），指错目录助手就“看不见”这个技能。安装前先用 ls ~/.workbuddy/skills（或对应客户端目录）确认路径存在；如果目录不存在，手动建一下再执行安装。

这也是技能跨平台复用的真正落点——同一份 SKILL.md，换目录即换客户端。你不用为每个 AI 助手各写一套说明，只需要把文件放到对的位置。

安装与跨平台调用

除了命令行，社区也支持在网页或小程序里一键安装，或把技能打包成 Zip 手动放到目录，适合离线或受限网络环境。

六、进阶：团队、付费与评测

当你不只是个人使用，还可以往三个方向走：

团队空间：企业认证后能获得独立团队空间，把内部能力沉淀成私有技能，仅团队可见；对外发布的技能还能挂上认证标签，统一管理成员与审核流程。
付费技能（SkillPay）：如果你有现成的付费服务，可以把它封装成“按次计费”的付费技能，基于 X402 协议在调用时触发用户支付授权，无需重构业务逻辑。
质量评测（TRACE）：社区用一套五维体系评估技能质量——信任、可靠性、适用性、规范性、有效性。挑技能时，与其看下载量，不如先看这五个维度是否都站得住。

TRACE 五维评测