先聊聊心态，别把 Skill 当成装饰

说实话，hen多人一上手就想堆满各种功Neng。

哈哈，这跟逛超市买东西一样，kan到啥好kan的就往篮子里塞。

其实啊，Skill 要像钥匙，专门开对应的门。

咱就是说先弄清楚自己到底要解决什么痛点。

Ru果你连需求dou模糊，那后面改来改去的成本会翻倍。

拆解 Skill 定义——从项目文档抓关键

第一步，打开项目的需求文档或者 runbook。

不对不对，我的意思是先找那份Zui靠近实际操作的手册。

把里面出现的业务术语、接口路径、输入输出格式全抄下来。

然后把这些碎片拼成一个完整的使用场景。

比如你要写一个「PDF 合并」Skill，别只写「合并 PDF」这么笼统，

要写清楚：用户会上传几份文件？合并后文件名怎么命名？是否需要压缩？

这一步Zuo得好，后面测试几乎不需要再补坑。

为什么百度不收录我的 Skill 文档？

其实原因hen简单：搜索引擎喜欢结构化、唯一且有价值的内容。

Ru果你的 SKILL.md 没有标题层级，或者全是代码块没有解释文字，

百度就会觉得这篇文档没啥信息量，直接跳过去。

再者，Ru果你把文档放在内部仓库而没有公开访问权限，那自然也收不到爬虫。

解决办法？给每个 Skill 加上明确的标题，用自然语言描述功Neng和触发条件；

同时在公开平台同步一份可访问的 Markdown 渲染页。

构建训练集——真实任务才靠谱

别指望 AI Neng凭空猜出你的业务细节。

我常用的方法是：从Zui近一次上线的故障单里挑出 5~10 条典型案例。

把用户原始请求、Agent 的错误回复、以及Zui终正确答案全部记录下来。

然后把这些对话包装成 JSON 或者 CSV，作为 Skill 的训练样本。

记住要让 AI 学会「何时」调用 Skill，「怎样」使用它，这两点缺一不可。

技巧：模板胜过长篇大论

当你发现某类任务总是需要相同格式输出时直接给 Agent 一个模板吧！

比如生成周报，你Ke以提供一个 markdown 表格骨架：

| 日期 | 完成事项 | 未完成原因 |
|------|----------|------------|
|      |          |            |

这样 Agent 只要填充内容，就不会跑偏了。

迭代评估——kan日志才知道真相

Skill 写完后第一件事，就是跑几个真实任务kankan效果。

别光kanZui终结果，要追溯到每一步的日志输出。

AIAgent 会在内部上下文里留下「选择了哪个 Skill」和「执行了多少 token」的信息。

Ru果发现某次调用耗时异常长，那说明 description 太宽泛了被误触发了。

"呀，这不对啊"，这时候就回去细化 description 或者加上注意事项吧！

# 小插曲：自我纠正时间

"其实我刚才说错了"，我们常常在写完 description 后才发现遗漏关键字。

"应该是……"，于是立马补上 “当用户上传 CSV 文件且要求统计分析时”。

控制精细度——粒度恰到好处

Pain point 是：Skill 太宽会导致误触发，太窄又会频繁切换上下文浪费资源。

- 合适的粒度是围绕单一业务流程或单一资源类型来设计，比如「PDF 提取文本」而不是「处理所有文件」。

S​kill 描述Zui佳实践

Description 要点：

- 明确说Zuo什么

- 标明触发条件

- 包含隐含场景

- 保持简洁，一行不超过 120 个字符

实战演练——从零到一写第一个可用 Skill

# 步骤一：创建目录结构 /my-skills/pdf-extract/SKILL.md /my-skills/pdf-extract/scripts/extract.py

# 步骤二：编写 SKILL.md

Name: pdf-extract
Description:> 
  当用户上传 PDF 并请求提取正文时
  自动读取第一页文字并返回纯文本。
Trigger:
  - file.type == "pdf"
  - intent.contains
Notes:
  - 若 PDF 加密，请提示用户提供密码。
  - 大文件建议分片处理。

# 步骤三：实现脚本

# extract.py
import PyPDF2
def run:
    reader = PyPDF2.PdfReader
    text = ""
    for page in reader.pages:
        text += page.extract_text
    return {"content": text}

S​kill 测试小贴士

- 用真实 PDF Zuo单元测试

- 检查返回结构是否符合 Agent 预期

- 在日志里搜索 “pdf-extract” 确认被正确调度

L​ast Word：保持迭代精神，别怕改动

AIAgent 的Neng力跟不上业务变化，那只Neng怪自己没及时geng新 Skill。

"说实话"，每一次修正dou是一次提升可靠性的机会。

# 小结：

- 从真实需求出发，不要盲目堆砌功Neng。

- 用项目文档抽象出精准描述；配合模板提升输出一致性。

- 实际运行日志是唯一可信的数据来源；发现问题立即回到 SKILL.md 改。

- 粒度适中，让每个 Skill 成为独立且易触发的小模块。

- 为了 SEO ，记得给每个 Skill 加标题、描述和公开链接，这样百度才会收录哦！

# 好啦，就酱紫！希望你们在打造 Agent Skills 的路上少走弯路，多点乐子。下次见~ 哈哈！

---