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

前言

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

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

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

一、Skill 的完整目录结构

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

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

三层加载机制

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

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

二、多领域 Skill 的组织模式

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

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

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

## 执行流程 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-cleanerSkill，需要清洗 Excel 文件中的脏数据：

SKILL.md：

--- name: xlsx-cleaner description: 当用户上传 Excel 文件并需要数据清洗、去重、格式规范化时触发。 涉及 .xlsx、.csv、.xls 文件的数据处理任务都应使用此技能。 --- # Excel 数据清洗 ## 执行步骤 1. 确认用户上传的文件路径（位于 `/mnt/user-data/uploads/`） 2. 运行清洗脚本： ```bash python scripts/clean.py <input_path> <output_path>

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

参数说明

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

**`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])

脚本设计原则

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

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

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

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

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

为什么 description 如此重要？

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

Description 的常见问题

问题一：过于简短

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

问题二：触发词不够丰富

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

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

问题三：缺乏"推动性"

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

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

触发评估方法

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

应该触发的（Positive）：

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

不应该触发的（Negative）：

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

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

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

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

实践上意味着：

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

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

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

SKILL.md：

--- 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 质量。