当你向 AI 助手提出需求，它可能会手忙脚乱。但如果你能给 AI 一份"操作手册"，告诉它"用这个工具，按这个步骤，注意这个坑"，它就能轻松搞定。Skills，就是一份岗位职责说明书+操作 SOP+避坑指南的合集。

一、Agent Skills 是什么

一个 Skill 就是一个文件夹。最关键的文件是 SKILL.md。

my-skill/
├── SKILL.md           # 必须：任务说明书
├── scripts/           # 可选：可执行脚本
├── references/        # 可选：参考文档
└── assets/           # 可选：静态资源

核心设计哲学：渐进式披露

就像外卖骑手接单：

步骤	展示内容	骑手行为
第一步	概要信息（订单摘要）	决定接不接
第二步	详细信息（取餐地址）	去取餐
第三步	完整内容（路线、小票）	开始配送

AI 也是如此：先给概要，理解需求后再逐步深入。

二、SKILL.md 结构速查

---
name: 技能名称
description: 一句话描述
version: 1.0.0
trigger: /skill-name
---

# 核心描述
技能是做什么的

## 触发场景
什么时候用这个技能

## 关键概念
需要理解的核心概念

## 操作步骤
详细操作流程

## 注意事项
容易踩的坑

## 输出格式
期望的输出样式

三、元数据字段详解

必须字段

字段	说明	示例
name	技能名称	"pdf-processor"
description	一句话描述	"从 PDF 中提取和处理数据"

可选字段

字段	说明	示例
version	版本号	"1.0.0"
trigger	触发命令	"/pdf"
author	作者	"作者名"
tags	标签	["pdf", "extraction"]

Claude Code 扩展字段

字段	说明
instructions	每次执行时都注入的内容
at_idle	空闲时执行的指令
disabled_for	禁用场景列表

四、6大写作技巧

技巧1：说清楚"做什么"

## 技能描述
这个技能帮助用户从 PDF 文档中提取结构化数据。
支持：
- 表格数据提取
- 文本提取
- 表单字段识别

技巧2：说清楚"怎么做"

## 操作流程
1. 使用 `pdfplumber` 加载 PDF
2. 提取页面文本
3. 识别表格结构
4. 输出 JSON 格式

技巧3：说清楚"注意什么"

## 注意事项
- PDF 必须是文本型（OCR 扫描件需先处理）
- 表格跨页时需要合并
- 中文编码使用 UTF-8

技巧4：说清楚"预期输出"

## 输出格式
{
  "text": "页面文本",
  "tables": [
    {"page": 1, "data": [[...]]}
  ],
  "forms": [...]
}

技巧5：说清楚"依赖环境"

## 环境要求
- Python 3.10+
- pdfplumber >= 0.10.0
- 安装命令：`pip install pdfplumber`

技巧6：说清楚"错误处理"

## 错误处理
- 加密 PDF：提示用户先解密
- 损坏 PDF：返回空结果并说明原因
- 超大文件：分页处理

五、让 Skill 被 AI 看到

方法1：目录约定

.claude/skills/
├── pdf-processor/
│   └── SKILL.md
├── data-cleaner/
│   └── SKILL.md
└── report-generator/
    └── SKILL.md

方法2：全局注册

# 注册全局 Skill
claude skill register ./my-skill

方法3：MCP 服务器

// skill-server.js
const { Server } = require('@anthropic-ai/mcp-server');

const server = new Server('skill-server');

server.tool('pdf-extract', async ({ file_path }) => {
  // 实现 PDF 提取
  return { text, tables, forms };
});

server.start();

六、评估 Skill 的方法

1. 设计测试用例

const testCases = [
  {
    name: "简单文本提取",
    input: "single-page.pdf",
    expected: { page_count: 1 }
  },
  {
    name: "多表格提取",
    input: "multi-table.pdf",
    expected: { table_count: 3 }
  }
];

2. 运行评估

# 运行测试
claude skill test pdf-processor --cases test-cases.json

# 输出结果
{
  "total": 10,
  "passed": 8,
  "failed": 2,
  "accuracy": "80%"
}

3. 编写断言

assert.equals(result.page_count, 5, "应提取5页");
assert.contains(result.text, "关键内容", "文本应包含关键内容");
assert.equals(result.tables.length, 3, "应提取3个表格");

4. 评分体系

分数	含义
5	完全符合预期
4	满足主要需求，有小问题
3	基本满足，需要调整
2	部分满足，需要大改
1	完全不满足

5. 迭代改进

设计 → 评估 → 发现问题 → 改进 → 再次评估
  ↑                                          │
  └──────────────────────────────────────────┘

七、编写脚本

Python 脚本

#!/usr/bin/env python3
# scripts/extract_tables.py

import sys
import json
from pdfplumber import open as open_pdf

def extract_tables(pdf_path):
    """从 PDF 提取表格"""
    with open_pdf(pdf_path) as pdf:
        tables = []
        for page in pdf.pages:
            page_tables = page.extract_tables()
            tables.extend(page_tables)
        return tables

if __name__ == "__main__":
    pdf_path = sys.argv[1]
    result = extract_tables(pdf_path)
    print(json.dumps(result, ensure_ascii=False))

Bash 脚本

#!/bin/bash
# scripts/install_deps.sh

echo "Installing PDF dependencies..."
pip install pdfplumber pymupdf
echo "Dependencies installed successfully."

八、模板总结

最小模板

---
name: skill-name
description: 一句话描述
---

# 技能名称
做什么的

## 使用方法
怎么用

## 注意事项
注意什么

完整模板

---
name: pdf-extractor
description: 从 PDF 提取文本和表格
version: 1.0.0
trigger: /pdf
author: your-name
tags: [pdf, extraction]
---

# PDF 数据提取器

## 技能描述
从 PDF 文档中提取结构化数据。

## 触发场景
当用户提供 PDF 文件并要求提取内容时使用。

## 关键概念
- 文本提取：使用 pdfplumber
- 表格提取：识别表格结构
- 表单提取：识别表单字段

## 操作流程
1. 确认 PDF 可读
2. 加载 PDF
3. 提取文本/表格/表单
4. 输出 JSON 格式

## 输出格式
```json
{
  "text": "...",
  "tables": [...],
  "forms": [...]
}

注意事项

• 加密 PDF 需要先解密
• OCR 扫描件效果有限

依赖

• Python 3.10+
• pdfplumber >= 0.10.0

## 九、常见问题

### Q：Skill 和 Prompt 有什么区别？
**A：** Skill 是持久化的、可复用的、有结构的标准格式；Prompt 是临时性的。

### Q：一个项目需要多少个 Skill？
**A：** 按领域组织，一般 3-7 个核心技能。

### Q：Skill 会被 AI 自动发现吗？
**A：** 需要在 `.claude/skills/` 目录或配置中注册。

### Q：Skill 可以调用外部 API 吗？
**A：** 可以，通过 scripts 或 MCP 服务器。

## 一句话总结

**Agent Skills = 渐进式披露的任务说明书。**

**核心要素**：
1. 元数据（name、description、trigger）
2. 操作流程（一步步怎么做）
3. 注意事项（容易踩的坑）
4. 输出格式（期望的样式）

**评估循环**：设计 → 测试 → 评分 → 改进 → 再测试。