Writing a Skill

A Skill is how you extend Nephele. It doesn't require writing code — it's a natural-language workflow document that teaches the Agent how to make better use of existing tools in specific situations.

Think of it as writing a "job description" for the Agent, so it becomes more proficient at certain tasks.

What a Skill Is

A Skill doesn't define new features, and it doesn't register new tools. It does just one thing: it injects domain knowledge into the Agent's system prompt.

For example, Nephele ships with a built-in find-references skill that tells the Agent:

• When searching Pixiv, first translate the Chinese keywords into Japanese or English (Pixiv is a Japanese-language site, and the original Chinese terms almost never return results)
• If a search comes up empty, don't give up — try a few synonyms instead
• Sort results by relevance, showing high-quality works first

These aren't things that code can express — they're experience and workflow. A Skill is what you use to codify that experience.

Skill File Format

Each Skill is a directory containing at least one SKILL.md file:

~/.nephele_workshop/skills/
└── my-skill/
    └── SKILL.md

SKILL.md has two parts: YAML front matter + Markdown body.

YAML Front Matter

Placed at the very beginning of the file, wrapped in three dashes:

---
name: my-skill-name
description: "这个 Skill 是做什么的"
emoji: "🚀"
tools: [tool_a, tool_b]
keywords: [关键词1, 关键词2, 关键词3]
---

Markdown Body

After the YAML ends comes free-form Markdown. This is where you teach the Agent how to do it.

You can write:

• Decision trees (which path to take in which situation)
• Translation rules (how to convert keywords)
• Output templates (how results should be organized)
• Anti-pattern reminders (what not to do)
• Step-by-step workflows

A Complete Example

Below is a complete example of a custom Skill. Suppose you often need to find a specific artist's images on Weibo for reference — you can write a Skill that teaches the Agent how to search efficiently:

---
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 分钟内使用
- 不要尝试登录微博，只用公开搜索
- 如果搜索结果为空，提示用户换个关键词

Save this file to ~/.nephele_workshop/skills/weibo-artist-reference/SKILL.md, restart Nephele, and it will take effect.

Matching Mechanism

How does the Agent decide which Skill to use? It goes by keyword matching:

The Agent injects the top 2 highest-weighted Skills into the current conversation's prompt.

Overriding a Built-in Skill

If you want to modify one of Nephele's built-in Skills, all you need to do is:

1. Create a Skill with the same name (matching the name field)
2. Put it under ~/.nephele_workshop/skills/
3. Restart Nephele

The user Skill overrides the built-in one. This way you can customize the Agent's behavior without changing the software's code.

Debugging a Skill

Once you've written a Skill, how do you know whether the Agent is actually using it?

1. Watch the chain of thought — if the Agent mentions your Skill's name or emoji while thinking, the Skill was injected
2. Test the keywords — start a conversation using the words from your keywords and see whether the Agent's behavior follows the workflow you wrote
3. Simplify step by step — if the Agent isn't doing what you expect, the body may be too complex. Try trimming it down to the most essential 3-5 rules

When to Write a Skill vs. a Tool

In short: write strategy as a Skill, write capability as a tool.