Skill

Skill 最佳实践

写能在正确时机激活、节省上下文、并稳定产出结果的 Skill。

写出聚焦触发的描述

描述是 Agent 激活前看到的目录项。它应该描述用户意图、任务形状和边界，而不只是主题。

# 弱
description: 帮助处理 PDF。

# 更强
description: 提取 PDF 文本、拆分或合并页面、填写表单，并校验生成的 PDF 输出。

一旦激活，SKILL.md 的每个字都要和用户请求、项目上下文、工具结果和其他活动指令竞争上下文。把高价值流程留在主文件里，把少见细节放到 references。

保留

激活规则、工作流、成功标准、默认值和关键坑点。

搬出去

冗长 API 参考、详尽示例、风格指南、schema 和大模板。

按需加载

明确告诉 Agent 什么时候读某个参考、脚本或资源。

Agent 比起抽象原则，更会跟着操作步骤走。把“迁移要小心”改成一个可执行清单。

检查输入

列出 Agent 在动作前必须检查的文件、字段或信号。

执行修改

说明允许的动作和不确定情况的默认处理方式。

验证

明确测试、断言、复核检查或输出标准。

当最终答案必须遵循固定格式时，直接给出模板。Agent 对例子的模式匹配通常比对抽象说明更可靠。

## 最终报告

摘要：
- ...

发现：
| 严重性 | 问题 | 证据 | 建议 |
| --- | --- | --- | --- |

未解决问题：
- ...

脚本适合做解析、校验、转换、评分、报告生成等确定性工作。要按 Agent 的使用方式设计，而不是按人类交互来设计。

不要交互接受参数，失败时给清楚信息，不要等人工输入。

帮助信息支持 --help，让 Agent 能快速看懂用法。

结构化输出优先用 JSON、CSV 或分隔行，不要只靠肉眼对齐表格。

前置条件在 SKILL.md 或兼容性元数据里写清楚运行要求。