编写 Skill
Skill 是 Nephele 的扩展方式。它不需要写代码，而是一个自然语言工作流文档，教 Agent 在特定场景下如何更好地使用已有工具。
你可以把它理解为：给 Agent 写一份"岗位说明书"，让它在某些任务上更专业。
Skill 是什么
Skill 不定义新功能，也不注册新工具。它只做一件事：把领域知识注入 Agent 的系统提示词。
比如 Nephele 内置了一个 find-references skill，它告诉 Agent：
- 去 Pixiv 搜索时，先把中文关键词翻译成日文
- 如果搜索没有结果，不要放弃，换几个同义词再试
- 结果要按相关性排序，优先展示高质量作品
这些不是代码能表达的，而是经验和工作流。Skill 就是用来固化这种经验的。
提示
Skill 和工具的关系：工具是"能做什么"，Skill 是"怎么做更好"。工具用 Python 写，Skill 用 Markdown 写。
Skill 的文件格式
每个 Skill 是一个目录，里面至少有一个 SKILL.md 文件：
~/.nephele_workshop/skills/
└── my-skill/
└── SKILL.md
SKILL.md 分成两部分：YAML 前置信息 + Markdown 正文。
YAML 前置信息
放在文件最开头，用三个短横线包裹：
---
name: my-skill-name
description: "这个 Skill 是做什么的"
emoji: "🚀"
tools: [tool_a, tool_b]
keywords: [关键词1, 关键词2, 关键词3]
---| 字段 | 必填 | 说明 |
|---|---|---|
| name | 是 | Skill 标识名，同名 Skill 用户版会覆盖内置版 |
| description | 是 | 一句话描述，Agent 用它理解这个 Skill 的用途 |
| emoji | 否 | 显示在提示词里的图标，让 Agent 更容易识别 |
| tools | 否 | 这个 Skill 涉及哪些工具，仅作提示用 |
| keywords | 是 | 触发关键词，Agent 根据用户输入匹配这些词来决定是否注入这个 Skill |
Markdown 正文
YAML 结束之后，就是自由格式的 Markdown。这里是教 Agent 怎么做的地方。
你可以写：
- 决策树（什么情况下走哪条路）
- 翻译规则（关键词怎么转换）
- 输出模板（结果要怎么组织）
- 反模式提醒（不要做什么事）
- 分步骤工作流
技巧
正文最长 2000 字符。Agent 每次最多注入 2 个 Skill。写的时候要精炼，不要塞百科全书。
完整示例
下面是一个自定义 Skill 的完整例子。假设你经常需要找特定画师的微博图来参考，你可以写一个 Skill 教 Agent 怎么高效地搜：
---
name: weibo-artist-reference
description: 在微博搜索画师作品和参考图
emoji: "📷"
tools: [browser_navigate, browser_snapshot, browser_extract]
keywords: [微博, 画师, 作品, 参考, weibo, 微博搜图, 搜微博]
---
## 工作流程
1. 打开微博搜索页面：`https://s.weibo.com/weibo?q={关键词}`
2. 切换到"图片"标签筛选只显示图片的结果
3. 滚动加载更多结果（微博是懒加载，需要模拟滚动）
4. 提取图片 URL 和原帖链接
5. 返回结果时按时间倒序排列，最新的在前
## 搜索技巧
- 搜具体画师时，用画师微博昵称而不是真名
- 如果昵称搜不到，尝试搜 "画师名 + 作品" 或 "画师名 + 插画"
- 中文关键词不需要翻译
## 注意事项
- 微博图片有防盗链，返回的 URL 要在 5 分钟内使用
- 不要尝试登录微博，只用公开搜索
- 如果搜索结果为空，提示用户换个关键词把这个文件存到 ~/.nephele_workshop/skills/weibo-artist-reference/SKILL.md，重启 Nephele 后就能生效。
匹配机制
Agent 怎么决定用哪个 Skill？它是根据关键词匹配的：
| 匹配位置 | 权重 |
|---|---|
| keywords 命中 | +2 |
| description 命中 | +0.5 |
| name 命中 | +3 |
Agent 会把权重最高的前 2 个 Skill 注入当前对话的提示词里。
技巧
keywords 要尽量覆盖用户可能说的同义词。比如找参考的 Skill，关键词里要同时包含"找图"、"参考"、"灵感"、"搜图"等。
覆盖内置 Skill
如果你想修改 Nephele 内置的某个 Skill，只需要：
- 创建一个同名 Skill（
name字段相同） - 放到
~/.nephele_workshop/skills/下 - 重启 Nephele
用户 Skill 会覆盖内置 Skill。这样你不需要改软件代码，就能定制 Agent 的行为。
调试 Skill
写好 Skill 后，怎么知道它有没有被 Agent 用到？
- 观察思维链 —— Agent 思考时如果提到了你的 Skill 名字或 emoji，说明 Skill 被注入了
- 测试关键词 —— 用 keywords 里的词发起对话，看 Agent 行为是否按你写的流程走
- 逐步简化 —— 如果 Agent 没按预期执行，可能是正文太复杂。尝试删减到最核心的 3-5 条规则
注意
Skill 不能定义新工具。如果你的需求需要全新的功能（比如调用一个 Nephele 没有的 API），你需要写 Python 工具而不是 Skill。Skill 只能教 Agent 更好地使用已有工具。
什么时候写 Skill，什么时候写工具
| 场景 | 写 Skill | 写工具 |
|---|---|---|
| 教 Agent 在特定平台搜索的最佳实践 | 是 | 否 |
| 定义输出格式和报告模板 | 是 | 否 |
| 给 Agent 设定决策逻辑和判断标准 | 是 | 否 |
| 需要调用外部 API 获取数据 | 否 | 是 |
| 需要执行文件系统或系统级操作 | 否 | 是 |
| 需要全新的 UI 交互组件 | 否 | 是 |
简单说：策略写 Skill，能力写工具。