skill-writer

Files (1)

• SKILL.md

SKILL.md (first lines)

# 技能编写器：设计参考

技能是通过 `use_skill` 加载、用于指导 Agent 行为的 Markdown 指令文档。它们不是代码，而是结构化说明。本指南帮助你设计高质量、可复用的技能。

## 自主创建技能

技能创建的主要机制是**自主创建**：任务完成后，`EVOLVE` 阶段会判断这次经验是否值得沉淀为可复用技能。不需要等用户明确提出；只要发现反复出现的模式，就可以创建技能。

也可以在 `EXECUTE` 阶段通过 `create_skill` 工具手动创建，适用于：

- 希望主动为一类重复工作准备技能。
- 用户明确要求创建技能（这种情况应当比较少，因为技能创建本来就是 Agent 的职责）。

## 什么时候创建技能

**适合创建技能：**

- 解决了很可能再次出现的多步骤问题。
- 工作流有清晰且可重复的步骤。
- 技能能够节省时间或提高一致性。
- 发现了值得保存的有效操作流程。

**不适合创建技能：**

- 只会出现一次的一次性任务。
- 简单事实（应写入记忆，而不是技能）。
- 已经被现有技能覆盖的内容。
- 模糊或尚未完整验证的模式。

## 设计规范

### 命名

- 使用小写字母和连字符，例如 `code-review`、`git-commit`、`bug-triage`。
- 名称要具体，例如使用 `python-test-writer`，不要只写 `test`。
- 最长 64 个字符，并且必须匹配 `/^[a-z0-9][a-z0-9-]*$/`。

### description

- 一行，最长 200 个字符。
- 以动词开头，例如“审查……”“生成……”“分析……”。
- 具体到足以让 Agent 判断是否应该使用它。

### when_to_use

- 清楚描述触发条件。
- 示例：“当用户要求审查代码质量或最佳实践时”。

### 正文

正文是调用 `use_skill` 时加载的实际指令，应当：

1. 以 `# 标题` 和 `## 概览` 开始，说明技能用途。
2. 用编号列表写出按执行顺序排列的步骤。
3. 包含示例，展示什么结果才算好。
4. 引用需要使用的具体工具，例如“使用 `exec` 运行命令”“使用 `read` 读取文件”。
5. 保持自包含，不依赖其他技能正文才能理解。
6. 写明决策标准，说明何时走不同路径。
7. 具体、可执行，因为 Agent 会按字面读取这些指令。

## 创建技能

调用 `create_skill` 工具：

```text
create_skill({
  name: "my-skill",
  description: "一句话描述这个技能解决的问题",
  when_to_use: "当……时使用",
  body: "# 我的技能\n\n## 概览\n技能用途。\n\n## 步骤\n1. 第一步……\n2. 第二步……"
})
```

该工具会将文件写入活动应用数据根的 `<data-root>/skills/<name>/SKILL.md` 并热加载索引。`<data-root>` 可以整体迁移，不能假设它固定在用户主目录。技能会立即可用并持久保存。

## 质量检查清单

创建技能前确认：

- [ ] 名称使用小写连字符，具体，长度不超过 64 个字符。
- [ ] `description` 是一行，以动词开头，长度不超过 200 个字符。
- [ ] `when_to_use` 清楚描述触发条件。
- [ ] 正文以 `# 标题` 和 `## 概览` 开始。
- [ ] 正文包含编号步骤。
- [ ] 正文引用必要工具。
- [ ] 正文包含示例或决策标准。
- [ ] 技能没有重复已有技能。

From HiOSheep/littlesheep-agent, MIT.

More from HiOSheep/littlesheep-agent