spherse-create-skill

创建自定义 Skill

Skill 是一段可被 agent 通过 load_skill 工具按需加载的指令（instructions）。你可以创建自己的 skill，将常用的写作规范、领域知识、工作流程封装成可复用的指令包。

Skill 的两个层级

Skill 按作用范围分为两个层级：

层级	目录路径	作用范围
Project-level	.spherse/skills/{skill-name}/	项目内所有 agent 共享
Agent-level	.spherse/agents/{agent-slug}/skills/{skill-name}/	仅该 agent 私有

如何选择

• Project-level：适用于所有 agent 都应遵循的通用规范（如世界观术语表、项目写作风格、文件命名约定）。
• Agent-level：适用于某个 agent 专属的工作方式（如某个角色扮演 agent 的对话风格、某个助手 agent 的特定输出格式）。Agent-level skill 放在该 agent 自己的目录下，不污染其它 agent 的 skill 列表。
• 项目根目录的 .agents/skills/{skill-name}/ 也会作为 project-level 兼容目录被载入。已有项目可以直接复用该目录；新建 Skill 时仍优先写入 .spherse/skills，因为 Skill Panel、安装与市场更新只管理这个主目录。

优先级

同名 skill 的优先级为 agent-level > .spherse/skills > .agents/skills > builtin。

如何获取 agent slug

创建 agent-level skill 时，需要知道目标 agent 的 slug（即 agent 目录名，形如 writer-a1b2c3）：

• 当前 agent 自身：在你的 system prompt 的 <session-context> 块中，agent-slug: {slug} 即为当前 agent 的目录名。用它构造路径 .spherse/agents/{slug}/skills/{skill-name}/SKILL.md。
• 其它 agent：询问用户目标 agent 的 slug，或查看 .spherse/agents/ 目录下的子目录名。

标准目录结构

{skill-name}/
├── SKILL.md              # 必需：YAML frontmatter + Markdown 指令正文
├── references/           # 可选：参考文档（如规范、模板说明）
│   └── style-guide.md
└── scripts/              # 可选：辅助模板或代码片段
    └── outline.md

• SKILL.md（必需）：skill 的唯一入口，包含 frontmatter 和指令正文。
• companion files（可选）：SKILL.md 之外的任意文件会被自动枚举为该 skill 的附加文件。agent 加载 skill 时会获得文件清单，可用 read_file 按需读取。建议用 references/、scripts/ 等语义化子目录组织。

SKILL.md 格式

SKILL.md 由两部分组成：

1. YAML Frontmatter

文件开头使用 --- 分隔的 YAML 块，必须包含两个字段：

字段	类型	说明
name	string	skill 名称，必须与目录名完全一致，不可含 /、\、:，不可以 . 开头
description	string	一句话描述 skill 的用途，agent 据此判断是否需要加载该 skill

2. Markdown 指令正文

frontmatter 之后的 Markdown 内容即为 skill 的指令正文。这部分会在 agent 调用 load_skill 时被注入到上下文中，应写清：skill 的目标、具体规则、示例、注意事项。

完整示例

---
name: fiction-style
description: 项目统一的小说写作风格规范，包括人称、时态、对话格式与章节结构约定
---

# 小说写作风格规范

## 人称与视角

- 全文使用第三人称限制视角
- 每章聚焦单一 POV 角色

## 对话格式

对话使用中文引号，人物语言与动作描写分行：

> 林晓转身看向窗外。
> 「这件事，我需要再想想。」

## 注意事项

- 避免大段心理独白，通过动作和环境暗示情绪