Claude Skill 进阶：多文件结构、脚本集成与触发优化

前言

上一篇文章中，我们写出了第一个单文件 Skill。但在实际项目中，你很快会遇到这样的问题：

Skill 越写越长，SKILL.md 超过了 500 行
不同子场景的处理逻辑差异很大，全塞在一起很混乱
有些操作需要执行脚本，而不是靠 Claude 自己推理

本文将带你掌握 Skill 的进阶结构设计，包括多文件组织、资源分层加载、脚本集成，以及如何系统性地优化触发准确率。

一、Skill 的完整目录结构

一个成熟的 Skill 可以包含多个文件，按职责分层组织：

bash 复制代码

my-skill/
├── SKILL.md               ← 核心入口（必须）
├── scripts/               ← 可执行脚本
│   ├── process.py
│   └── validate.sh
├── references/            ← 参考文档（按需加载）
│   ├── api-spec.md
│   ├── aws.md
│   └── gcp.md
└── assets/                ← 模板、字体、图标等静态资源
    ├── template.docx
    └── logo.png

三层加载机制

Skill 采用渐进式加载策略，避免一次性将所有内容塞入上下文：

层级	内容	何时加载
第一层	`name` + `description`	始终在上下文中（约100词）
第二层	`SKILL.md` 正文	触发时完整加载（建议 < 500 行）
第三层	`scripts/`、`references/`、`assets/`	按需加载，不受大小限制

设计原则：把"判断逻辑"放在 SKILL.md，把"详细内容"放在 references，把"机械操作"放在 scripts。

二、多领域 Skill 的组织模式

当一个 Skill 需要支持多种变体时（比如云部署支持 AWS/GCP/Azure），推荐按领域拆分参考文档：

bash 复制代码

cloud-deploy/
├── SKILL.md               ← 工作流主入口 + 选择逻辑
└── references/
    ├── aws.md             ← AWS 专属操作细节
    ├── gcp.md             ← GCP 专属操作细节
    └── azure.md           ← Azure 专属操作细节

SKILL.md 中写清楚选择逻辑：

bash 复制代码

## 执行流程

1. 询问用户目标云平台（AWS / GCP / Azure）
2. 根据选择，读取对应的参考文档：
   - AWS → 读取 `references/aws.md`
   - GCP → 读取 `references/gcp.md`
   - Azure → 读取 `references/azure.md`
3. 按照参考文档中的步骤执行部署

这样 Claude 每次只会加载当前任务所需的那一份文档，节省上下文，也更精准。

三、在 Skill 中集成脚本

有些操作让 Claude "推理执行"既慢又容易出错，更好的方式是直接调用脚本完成。

典型场景

文件格式转换（PDF → Word，Excel 数据清洗）
批量处理（遍历文件夹、批量重命名）
环境检查（验证依赖是否安装）

脚本集成示例

假设我们有一个 xlsx-cleaner Skill，需要清洗 Excel 文件中的脏数据：

SKILL.md：

bash 复制代码

---
name: xlsx-cleaner
description: 当用户上传 Excel 文件并需要数据清洗、去重、格式规范化时触发。
涉及 .xlsx、.csv、.xls 文件的数据处理任务都应使用此技能。
---

# Excel 数据清洗

## 执行步骤

1. 确认用户上传的文件路径（位于 `/mnt/user-data/uploads/`）
2. 运行清洗脚本：
   ```bash
   python scripts/clean.py <input_path> <output_path>

将输出文件移动至 /mnt/user-data/outputs/
向用户展示清洗报告（行数变化、删除的重复行数等）

参数说明

input_path：用户上传文件的完整路径
output_path：建议命名为 cleaned_<原始文件名>

python 复制代码

**`scripts/clean.py`：**
```python
import pandas as pd
import sys

def clean_excel(input_path, output_path):
    df = pd.read_excel(input_path)
    
    original_rows = len(df)
    
    # 去重
    df = df.drop_duplicates()
    
    # 去除全空行
    df = df.dropna(how='all')
    
    # 字符串列去首尾空格
    str_cols = df.select_dtypes(include='object').columns
    df[str_cols] = df[str_cols].apply(lambda x: x.str.strip())
    
    df.to_excel(output_path, index=False)
    
    print(f"原始行数: {original_rows}")
    print(f"清洗后行数: {len(df)}")
    print(f"删除行数: {original_rows - len(df)}")

if __name__ == '__main__':
    clean_excel(sys.argv[1], sys.argv[2])

脚本设计原则

脚本做确定性操作：格式转换、文件操作、数据验证------不要让脚本做需要推理的事
Claude 做判断：选择哪个脚本、解释结果、处理异常
清晰的输出：脚本打印关键信息，Claude 读取后再呈现给用户

四、references 参考文档的最佳实践

当参考文档超过 300 行时，建议在文档开头加目录，方便 Claude 快速定位需要的章节：

bash 复制代码

# AWS 部署参考

## 目录

- [1. 前置条件检查](#1-前置条件检查)
- [2. IAM 权限配置](#2-iam-权限配置)
- [3. ECS 部署步骤](#3-ecs-部署步骤)
- [4. 常见错误处理](#4-常见错误处理)

---

## 1. 前置条件检查
...

五、提升触发准确率：description 优化

为什么 description 如此重要？

Claude 在决定是否触发 Skill 时，只能看到 name 和 description（第一层），看不到 Skill 正文。因此 description 的质量直接决定触发率。

Description 的常见问题

问题一：过于简短

bash 复制代码

# ❌
description: 处理 PDF 文件。

# ✅
description: 当用户上传 PDF、提到提取文字、合并 PDF、分割页面、
添加水印、填写表单、或进行 OCR 时触发。任何涉及 .pdf 文件的操作
都应使用此技能，即使用户没有显式说"PDF技能"。

问题二：触发词不够丰富

Description 应该覆盖用户可能使用的各种表达方式：

bash 复制代码

description: 当用户提到以下任一场景时触发：
- "帮我写个 Word 文档" / "生成报告" / "做一份总结文档"
- 需要 .docx 格式输出
- 提到表格、页眉页脚、目录等 Word 特性
- 需要正式的可下载文档

问题三：缺乏"推动性"

Claude 有低估触发必要性的倾向。Description 应该明确告知什么情况下"必须"使用：

bash 复制代码

description: ... 凡是用户上传了 .xlsx 文件，无论请求多简单，都应触发此技能。

触发评估方法

构造一批测试用例，分两类：

应该触发的（Positive）：

"帮我把这个 Excel 里的重复数据删掉"
"读取上传的表格，统计每列的缺失值"
"这个 .xlsx 文件格式有问题，帮我修一下"

不应该触发的（Negative）：

"用 Python 写一个读取 Excel 的函数"（代码任务，非文件处理）
"什么是 VLOOKUP？"（知识问答）

逐一测试，看触发率是否符合预期，不符合则调整 description。

六、SKILL.md 的"不意外原则"

这是 Skill 设计中一条重要准则：Skill 的行为应该和名字、description 描述的完全一致，不应该有隐藏的惊喜。

实践上意味着：

Skill 的范围和 description 声明的一致，不要偷偷做 description 没提到的事
输出格式在 SKILL.md 中明确定义，不随意改变
如果有特殊限制（比如"仅支持 Python 代码"），在 description 和正文中都要说明

七、实战示例：完整的 PDF 处理 Skill

bash 复制代码

pdf-toolkit/
├── SKILL.md
├── scripts/
│   ├── extract_text.py
│   ├── merge_pdfs.py
│   └── split_pdf.py
└── references/
    ├── ocr_guide.md
    └── form_fields.md

SKILL.md：

bash 复制代码

---
name: pdf-toolkit
description: 当用户上传 PDF 文件或提到以下操作时触发：提取文字、合并 PDF、
分割页面、添加水印、识别扫描件（OCR）、填写或读取 PDF 表单。
任何涉及 .pdf 文件的任务都应使用此技能。
---

# PDF 工具箱

## 操作路由

根据用户需求选择对应操作：

| 用户需求 | 使用脚本 | 参考文档 |
|---------|---------|---------|
| 提取文字 | `scripts/extract_text.py` | - |
| 合并 PDF | `scripts/merge_pdfs.py` | - |
| 分割页面 | `scripts/split_pdf.py` | - |
| OCR 识别 | `scripts/extract_text.py --ocr` | `references/ocr_guide.md` |
| 表单操作 | - | `references/form_fields.md` |

## 通用步骤

1. 确认文件位于 `/mnt/user-data/uploads/`
2. 选择对应脚本或参考文档
3. 执行操作，输出至 `/mnt/user-data/outputs/`
4. 向用户报告结果

## 错误处理

- 文件损坏：提示用户重新上传
- 加密 PDF：询问密码，传入 `--password` 参数
- 扫描件识别失败：切换至 `--ocr` 模式

八、小结

本文覆盖了 Skill 的进阶设计：

多文件结构 ：scripts/、references/、assets/ 各司其职
三层加载机制：按需加载，节省上下文
脚本集成：确定性操作交给脚本，判断性操作交给 Claude
触发优化：description 要具体、丰富、有推动性
不意外原则：Skill 行为与声明完全一致

下一篇文章，我们将进入最高阶的主题------Skill 的测试、评估与迭代，包括如何构建测试集、量化评估触发准确率，以及系统化地改进 Skill 质量。