结构层面——Skill 的三级加载机制（元数据 → 正文 → 资源文件），以及如何控制各层大小让上下文窗口高效使用。
写作层面——最核心的一条是「解释 why，而不是堆 MUST」。LLM 足够聪明，理解原因后能泛化到新场景；全大写命令只会导致机械执行和边界崩溃。
触发层面——Description 是决定 Skill 是否被调用的关键，当前 Claude 倾向于「触发不足」，所以要写得稍微"强势"一点，同时包含明确的排除条件防止误触发。
测试层面——评估 query 要像真人说话（带路径、背景、口语），重点放在边界情况和「近似干扰项」，而非显而易见的正反例。
一、什么是 Skill？
Skill 是一组可复用的指令集，让 Claude 在特定任务场景下表现更好。它本质上是一个文件夹，核心是一个 `SKILL.md` 文件，外加可选的脚本、参考文档和资源文件。
skill-name/
├── SKILL.md ← 必须：YAML 元数据 + Markdown 指令
├── scripts/ ← 可选：确定性/重复性任务的脚本
├── references/ ← 可选：按需加载的参考文档
└── assets/ ← 可选：模板、图标、字体等资源二、SKILL.md 的结构
2.1 YAML Frontmatter（必填）
---
name: my-skill
description: "一句话说明做什么 + 什么时候触发。要具体、要'强势'。"
compatibility: "claude.ai, Claude Desktop, Cowork" # 可选
---关于 description 的关键原则：
- 这是触发机制的核心——Claude 根据 description 决定是否启用该 Skill
- 不仅要说「做什么」，更要说「什么时候用」
- 倾向于写得"强势"一点，因为 Claude 目前有「触发不足」的倾向
- 包含正面触发词和反面排除条件
好的 description 示例：
description: >
Use this skill whenever the user wants to create, read, edit, or
manipulate Word documents (.docx). Triggers include: any mention of
'Word doc', '.docx', or requests to produce professional documents.
Do NOT use for PDFs, spreadsheets, or Google Docs.2.2 Markdown 正文
正文就是给 Claude 的详细指令，用 Markdown 写。
三、核心编写原则
3.1 解释「为什么」，而不是堆「必须」
这是最重要的一条。今天的 LLM 足够聪明，当你解释清楚原因时，它能举一反三；当你只是堆砌 MUST/NEVER/ALWAYS，它只会机械执行，遇到边界情况就崩。
# ❌ 坏写法
ALWAYS use `python-docx` library. NEVER use any other library.
MUST set font size to 12pt.
# ✅ 好写法
Use python-docx because it's the only library pre-installed in this
environment that handles .docx reliably. Other libraries (like docxtpl)
aren't available and will cause import errors.
Default to 12pt body text — this is the standard for business documents
and ensures readability when printed.如果你发现自己在写全大写的 ALWAYS/NEVER，这是一个黄色警告——试着换成解释推理的方式。
3.2 用祈使句
指令用祈使句（"Read the file first"），而不是描述句（"The file should be read first"）。祈使句更直接，消耗更少 token。
3.3 追求泛化，而非过拟合
Skill 可能被使用无数次。不要为了修复某个测试用例加入过于狭窄的规则，而是思考背后的通用规律。
# ❌ 过拟合
If the user's CSV has a column named "Revenue_Q3", put it in column C.
# ✅ 泛化
Detect numeric columns automatically and place them after text/ID columns,
preserving the original order within each group.3.4 保持精简
- SKILL.md 正文控制在 500 行以内
- 如果内容更多，拆分到
references/子目录，在 SKILL.md 中用指针引导 - 大型参考文件（>300 行）加目录
- 移除没有产生实际效果的指令（看测试转录记录来判断）
3.5 「无惊讶原则」
Skill 的行为不应让用户感到意外。如果把 Skill 的内容描述给用户听，他们不应该觉得不对劲。
四、三级加载机制（Progressive Disclosure）
这是 Skill 系统的核心架构思想：
| 层级 | 内容 | 何时加载 | 大小建议 |
|---|---|---|---|
| L1 元数据 | name + description | 始终在上下文中 | ~100 词 |
| L2 正文 | SKILL.md body | Skill 被触发时 | <500 行 |
| L3 资源 | scripts/, references/, assets/ | 按需读取 | 无限制 |
关键点： 脚本可以不被读入上下文就直接执行。所以重型逻辑放脚本里，SKILL.md 只写「何时调用」和「怎么调用」。
五、Description 优化（触发率调优）
5.1 评估集设计
准备 ~20 条评估 query，分为「应该触发」和「不应该触发」两类：
[
{"query": "帮我把这个 xlsx 加一列利润率，收入在C列成本在D列", "should_trigger": true},
{"query": "解释一下什么是利润率", "should_trigger": false}
]评估 query 的要求：
- 要像真人说话：包含文件路径、个人背景、口语化表达、缩写、错别字
- 长度混合：有长有短
- 重点放在边界情况，而非显而易见的场景
- 不要写太简单的否定例子（"写个斐波那契函数"作为 PDF 技能的否定样本没有测试价值）
好的评估 query：
"我老板刚发了个 xlsx 文件（在下载文件夹里，叫什么 'Q4 sales final FINAL v2.xlsx'），她让我加一列利润率百分比。收入在C列成本好像在D列"
差的评估 query：
"Format this data"（太泛）、"Extract text from PDF"（太明显）
5.2 优化循环
通过自动化脚本进行迭代：
1. 把评估集分为 60% 训练 / 40% 测试
2. 评估当前 description 的触发率（每个 query 跑 3 次取均值）
3. 根据失败样本让 Claude 提出改进
4. 在训练集和测试集上重新评估
5. 迭代最多 5 轮
6. 以测试集得分选最优（避免过拟合训练集）
六、测试与迭代流程
6.1 完整循环
明确意图 → 写草稿 → 设计测试用例 → 运行测试 → 评估输出 → 改进 → 重复6.2 测试用例设计
- 2~3 条起步，模拟真实用户的真实说法
- 保存为
evals/evals.json - 先只写 prompt，不写断言——在测试运行期间再补
{
"skill_name": "my-skill",
"evals": [
{
"id": 1,
"prompt": "用户的真实任务描述",
"expected_output": "期望结果的描述",
"files": []
}
]
}6.3 断言设计
好的断言是：
- 客观可验证的（不是主观判断）
- 有描述性名称（看名字就知道测什么）
- 可编程检查的优先用脚本（比人工判断更快、更可靠、可复用）
主观质量（写作风格、设计美感）更适合人工定性评估，不要强塞断言。
6.4 改进时的思维框架
- 从反馈中泛化——不是修单个样本，而是找通用规律
- 保持精简——删掉没起作用的指令（看转录记录判断）
- 解释为什么——比全大写命令更有效
- 提取重复模式——如果每次测试 Agent 都独立写了类似的辅助脚本，说明应该把脚本预置到
scripts/里
七、多领域/多框架 Skill 的组织
当一个 Skill 需要支持多个变体（比如多云部署），用引用文件按领域分组：
cloud-deploy/
├── SKILL.md ← 工作流 + 选择逻辑
└── references/
├── aws.md
├── gcp.md
└── azure.mdClaude 只读取相关的参考文件，节省上下文窗口。
八、Agent 编写技巧
Agent 是 Skill 的高阶应用场景——它不仅是指令集，还涉及多步编排、工具调用、状态管理。
8.1 给 Agent 明确的角色定位
在 SKILL.md 开头就建立角色框架：
Approach this as the design lead at a design studio known for
giving every client a distinct visual identity.这不是角色扮演，而是调整 Claude 的决策框架和审美标准。
8.2 定义清晰的工作流程
用分阶段的结构组织复杂任务：
## Gather（收集信息）
检查可用连接，分类工具角色：日历 · 邮件 · 聊天 · 其他
## Sort（分类处理）
每条候选项归入「需要关注」或「已解决」，或静默丢弃
## Write（生成输出）
按模板生成 HTML 页面...8.3 处理缺失和异常
好的 Agent Skill 会预设降级策略：
A missing role is skipped; the page adapts.
（缺失的角色被跳过，页面自动适配。）而不是在缺少某个工具时报错停止。
8.4 上下文管理
- Agent 在每次调用之间没有记忆——所有相关状态必须在每次请求中完整传递
- 对于需要多轮交互的任务，设计好状态序列化方案
- 利用文件系统做持久化（工作目录 → 迭代目录结构）
8.5 搭配 MCP 工具
Agent 可以通过 MCP (Model Context Protocol) 连接外部服务。设计 Skill 时：
- 检查可用的 MCP 连接
- 对缺失的连接提供建议（connector suggestion cards）
- 在无法提供建议时，优雅降级
九、写作风格的反面模式（Anti-patterns）
| 反面模式 | 为什么不好 | 替代方案 |
|---|---|---|
| 堆砌 MUST/NEVER/ALWAYS | 机械执行，边界崩溃 | 解释原因，让模型理解 |
| 过度具体的硬编码规则 | 只对特定案例有效 | 泛化为通用策略 |
| 超长 SKILL.md (>500行) | 上下文膨胀，重点淹没 | 拆分到 references/ |
| Description 写得太保守 | Skill 不被触发 | 写得"强势"一点，覆盖更多触发词 |
| 没有排除条件 | 误触发其他领域的请求 | 明确写"Do NOT use for..." |
| 没解释 why，只写 what | 模型无法应对新场景 | 解释每条规则背后的原因 |
| 评估 query 太简单/太明显 | 无法检测真实性能 | 用边界情况和近似干扰项 |
十、一个完整 Skill 的最小示例
---
name: commit-message
description: >
Generate conventional commit messages from diffs or descriptions.
Use whenever the user asks to write, format, or improve a commit
message, or pastes a git diff and asks what to write. Do NOT use
for general git help or branch management.
---
# Commit Message Generator
Write commit messages following the Conventional Commits spec because
most CI/CD tools and changelog generators depend on this format.
## Format
`<type>(<scope>): <subject>`
Types: feat, fix, docs, style, refactor, test, chore
Scope: the module or area affected (optional but encouraged)
Subject: imperative mood, no period, under 72 chars
## How to decide the type
Look at what changed, not how it was described:
- New behavior users can observe → feat
- Broken behavior now fixed → fix
- Only .md or comment changes → docs
- Formatting/whitespace only → style
## Examples
**Example 1:**
Input: Added user authentication with JWT tokens
Output: feat(auth): implement JWT-based authentication
**Example 2:**
Input: Fixed the bug where login page crashes on Safari
Output: fix(auth): resolve Safari crash on login page总结：核心检查清单
在发布 Skill 之前，过一遍：
- ✅ Description 是否足够具体且"强势"，包含触发条件和排除条件？
- ✅ 正文是否解释了「为什么」而非只有「做什么」？
- ✅ 是否控制在 500 行以内，大内容是否拆到了 references/？
- ✅ 是否有 2~3 个真实场景的测试用例？
- ✅ 重复出现的辅助代码是否已提取到 scripts/？
- ✅ 是否处理了缺失工具/输入异常的降级场景？
- ✅ 评估 query 是否包含边界情况和近似干扰项？
- ✅ 是否在迭代中追求泛化而非过拟合？
除非注明，否则均为李锋镝的博客原创文章，转载必须以链接形式标明本文链接
文章评论