之前写了一篇关于 SKILL 设计最佳实践的话题，感受到佬们的热情
【SKILL 设计的最佳实践】什么是 SKILL？怎么快速写一个优秀的 SKILL？ - 开发调优 - LINUX DO
也感觉好多佬们都对 SKILL 设计还蛮感兴趣的，加上最近一直在对自己的 SKILL 进行调优，研究跟看了不少官方文档以及实践示例，对 SKILL 的设计略有心得，所以就在之前的基础上，把最近关于 SKILL 的进阶设计模式简单分享一下自己的理解吧。
内容绝大多数参考了官方的最佳实践文档，然后也结合自身调优的一些体验。Claude 的文档写的还是不错的，有时间的佬友们还是蛮推荐读一读的，链接就放在下面了。
技能编写最佳实践 - Claude Docs — Skill authoring best practices - Claude Docs
还是一如既往的大纲 + 一图流，方便佬们快速了解文章的大致内容以及组织形式。
1. 引子
为了方便对 SKILL 还不太了解，或者没看过上期的佬们快速理解，我举一个例子再来说明一下什么是 SKILL。
假设你是一名喜欢到世界各地旅行，你需要准备很多装备 (对应 mcp tools) 以应对不同情况，例如：
- 登山：登山包、山地靴、登山杖、…
- 极地：防寒服、手套、护目镜、…
- 雨林：驱虫喷雾、开山斧、…
那么对于特定场景我们将所需的东西都打包起来叫做 "登山套装" 或者 "极地套装"。这种为了应对特殊场景需求的工具套装，Claude 官方把他叫做 SKILL。
SKILL 中还包含了一些工作流（workflow），也可以理解为在特殊场景的操作手册，告诉你在遇到突发情况时应该怎么处理。
所以通过安装 SKILL 的方式可以使得模型在特定场景发挥强大的作用，同时你也可以自己根据喜好重新安排对应的 SKILL 中工具或者进行工作流的微调。
2. 渐进式披露 & 二次披露
那么很自然的想法，SKILL 这种将现成工具打包起来的做法是不是多余的呢，为什么我们不能把所有工具跟手册都带上，那么就能处理所有情况呢？
很遗憾的是目前大模型的上下文是有限的，就像如果你带上所有的工具去旅行，那么不仅很笨重（有效上下文受限），而且遇到突发情况时，从一大堆工具中找到适合的工具的难度也上升了（上下文混淆）
所以 SKILL 的设计理念的核心在于 渐进式披露：
- 将所有的工具以及手册，先放到四次元口袋中，不随身携带（不加载上下文）
- 但是为了能快速加载所需工具，使用目录来进行快速查找
这种记录可用工具套装的纸条（包含 name 以及 description），在遇到特定场景的时候就可以加载对应的工具（MCP tools、脚本）以及手册（项目文档、工作流规范）的模式就是 SKILL 的工作原理。
而这种目录结构加载资源的方式就称为 渐进式披露。
而 “二次披露” 实在 渐进式披露 的基础上的进阶应用，可以进一步提高上下文的有效利用，避免宝贵的上下文资源浪费，为此 Claude 官方文档中提出三种模式来指导二次披露的使用
2.1. 模式一： 附参考资料的高级指南
同样以登山包为例，在一个 SKILL 中可以只包含基础工具以及新的索引，当基础工具不能应对情况的时候，可以再根据索引的信息加载高级工具来处理问题。
以官方示例为例：
---
name: pdf-processing
description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---
# PDF Processing ## Quick start
Extract text with pdfplumber:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
``` ## Advanced features **Form filling**: See [FORMS.md](FORMS.md) for complete guide
**API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
**Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns
这个示例中对于进阶的需求，并没有直接披露到 SKILL.md 的 body 中（就是 See xxx 这些内容），因此在 SKILL 调用的时候，这些额外的进阶内容并不会直接加载到上下文中挤占有限的上下文空间。
而当模型结合 SKILL 以及用户问题的时候，感知到可能需要 API reference 的时候，他也具备进一步读取 REFFERENCE.md 文档的能力，来补足上下文。这种二次披露的能力可以进一步使得 SKILL 的上下文得到更有效的利用。
在我的实践中还发现这种能力实际上可以诞生一种能力，我暂时将其称之为 sub-skill，具体的设计以及实现可以等之后发布了我的 SKILL 之后再详细介绍一下 嘻嘻
2.2. 模式二：领域特定组织的加载
官方文档的说法是涉及多个领域的技能，应按领域组织内容，避免加载无关的上下文。
例如，当用户询问销售指标时，Claude 只需要读取与销售相关的模式，而无需读取财务或市场营销数据。这样可以降低令牌使用量，并专注于上下文。
预先将相对独立的上下文进行分开存储，并且使用关键词来进行索引以及引导，当需要特定领域的上下文细节的时候 使用 grep 等工具实现上下文的全量加载
这实际上就是通过 文件组织 的形式，实现不同场景参考资料的分离，因此也是一种二次披露，每次只披露与使用者问题相关的场景上下文来补足信息。
与模式一不同的点在于：
- 模式一是 根据功能 进行区分，
- 模式二是根据 领域场景 进行区分
本质上都是对信息的有效整合以及分离调度，这里最需要学习的实际上是他参考资料的文件组织路径形式，将同类的参考进行归档，方便后续修改或者变更，也方便模型进行索引。
bigquery-skill/
├── SKILL.md (overview and navigation)
└── reference/
├── finance.md (revenue, billing metrics)
├── sales.md (opportunities, pipeline)
├── product.md (API usage, features)
└── marketing.md (campaigns, attribution) # BigQuery Data Analysis ## Available datasets **Finance**: Revenue, ARR, billing → See [reference/finance.md](reference/finance.md)
**Sales**: Opportunities, pipeline, accounts → See [reference/sales.md](reference/sales.md)
**Product**: API usage, features, adoption → See [reference/product.md](reference/product.md)
**Marketing**: Campaigns, attribution, email → See [reference/marketing.md](reference/marketing.md)
## Quick search
Find specific metrics using grep:
```bash
grep -i "revenue" reference/finance.md
grep -i "pipeline" reference/sales.md
grep -i "api usage" reference/product.md
```
2.3. 模式三：条件细节
这一点就更好理解了，就是在引用资源前添加条件，类似通过使用 For xxx 或者是 if xxx， then xxx 的方式来让模型显示的知道何时该主动二次披露相关内容
# DOCX Processing ## Creating documents
Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).
## Editing documents
For simple edits, modify the XML directly.
**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)
2.4. 反模式：避免深度嵌套引用
既然有二次披露，那么三次四次甚至更多次披露是不是能更省上下文呢？
Claude 的回答是：不！
原因在于虽然 Claude 具备嵌套引用，但是本身对于嵌套引用采取了 额外的限制 ，例如只读取前 100 行的内容（head -100），因此嵌套引用可能会导致 信息缺失 以及 逻辑结构混乱 的现象。
官方推荐的做法是最好只调用到 二次披露 ，即只在 SKILL.md 中进行索引，不要在更深的文件结构下进行索引的创建以及链接。
注意事项：
- 对于二次披露的参考文献应当限制长度（行数小于 100 行，因为 claude 可能只读前 100 行）
- 如果超过 100 行，建立目录来让 claude 具备感知全文内容的能力
- PS: 但如果目录超 100 行那就无话可说了 哈哈哈
文章正文就先写到这吧 哈哈哈（下面是一些自己的感悟以及碎碎念
总的来说 SKILL 并不是一个非常高深或者难的技术，甚至对计算机没有一点基础的小白也能迅速上手，但是更多的如果想要设计一个非常优秀的 SKILL 还是需要对这些底层的调用机制有一定了解的。
笔者在自己构建 SKILL 的过程中发现，虽然 skill-creator 这个官方工具能快速搭建一个大致框架，但是内容的详细程度还是没有想象的那么优秀，很多都还蛮简单的，而且设计模式并没有很好的贯彻最佳实践中的要点，特别是二次披露以及文件组织，常常因为获取的内容跟信息太少而没办法有效组织。
而在后续修改的过程中，如果设计者不了解最佳实践的基础原理，由于 Claude Code 谄媚的现象，往往会导致 SKILL 的后续修改反而脱离了最佳实践的要求，导致性能变差。
顺便预告一下，下次更新可能会介绍 SKILL 设计中 工作流以及反馈循环 怎么设计以及调优的相关内容。
佬们周中愉快 哈哈哈
📌 转载信息
原作者：
guanhuhao
转载时间：
2026/1/14 17:43:27
