skill-guide

Files (3)

• SKILL.md
• SKILL_en.md
• package_skill.py · scripts/

SKILL.md (first lines)

# Aurora Skills 开发指南（官方规范 + Aurora 扩展）

## 1. 目标

本指南用于回答三个问题：

1. 一个 Skill 至少要写成什么样（官方最小标准）
2. Aurora 额外支持了哪些字段和行为（项目扩展）
3. turns 在哪里配、按什么优先级生效（当前实现）

## 2. 官方最小标准（必须）

每个 Skill 目录必须包含 `SKILL.md`，文件头使用 YAML frontmatter，最小只需要两个字段：

```yaml
---
name: your-skill-name
description: WHAT + WHEN（做什么 + 何时触发）
---
```

约束：

- `name` 必填，建议小写连字符，如 `weather-fetcher`
- `description` 必填，必须写清楚 WHAT 和 WHEN
- 路由阶段只依赖 frontmatter（尤其是 `name`、`description`）
- 正文（Markdown body）是在 Skill 被触发后才加载，所以“何时使用”不要只写在正文里

## 3. SKILL 正文编写原则

正文只写 How（怎么做）：

1. 用简洁步骤描述执行流程（祈使句）
2. 可变体内容放到 `references/`，正文只保留入口和选择规则
3. 重复性强、可确定执行的逻辑放 `scripts/`
4. 输出模板或素材放 `assets/`
5. 避免堆砌背景说明，优先可执行指令

## 4. Aurora 的目录发现规则（当前实现）

Aurora 会递归扫描 `skills/`：

- 识别 `SKILL.md`
- 识别 `SKILL_<language>.md`（如 `SKILL_en.md`）
- 若指定语言文件不存在，回退到 `SKILL.md`
- 目录中只要存在以上文件之一，即可被识别为一个 Skill

推荐结构：

```text
skill-name/
├── SKILL.md
├── SKILL_en.md        # 可选
├── scripts/           # 可选
├── references/        # 可选
└── assets/            # 可选
```

## 5. Aurora frontmatter 扩展字段（可选）

官方最小只要求 `name` + `description`。Aurora 额外支持以下字段：

- `enabled: true|false`
- `locked: true|false`
- `for_ai: true|false`
- `platforms: [all|desktop|mobile|windows|macos|linux|android|ios]`
- `id: custom_id`（不填时默认目录名）
- `tools: [...]`（工具定义）
- `worker_mode: reasoner|executor`（Skill Worker 执行模式）

与 turns 相关的 Aurora 扩展字段：

- `skill_max_turns`
- 兼容别名：`skillMaxTurns`、`worker_max_turns`、`workerMaxTurns`、`subagent_max_turns`、`subagentMaxTurns`、`_aurora_skill_max_turns`、`max_turns`、`maxTurns`

说明：`skill_max_turns` 是 Aurora 项目扩展，不是官方必需 frontmatter 字段。

`worker_mode` 说明：

- `reasoner`（默认）：Worker 可多轮推理与工具调用
- `executor`：Worker 在拿到首个工具输出后直接返回结果，不在 Worker 内做二次收尾

兼容别名（模式字段）：

- `workerMode`
- `skill_worker_mode`
- `skillWorkerMode`
- `subagent_mode`
- `subagentMode`
- `_aurora_worker_mode`
- `_aurora_skill_worker_mode`

## 6. turns 配置与优先级（当前实现）

### 6.1 Orchestrator（主对话编排）

键名（按读取顺序）：

- `orchestrator_max_turns`
- `orchestratorMaxTurns`
- `_aurora_max_turns`
- `max_turns`
- `maxTurns`

来源与顺序：

1. Provider `customParameters`
2. Provider `globalSettings`

默认值与范围：

- 默认 `8`
- 限制 `1..50`

### 6.2 Skill Worker（单个 skill 执行）

键名（按读取顺序）：

- `skill_max_turns`

From huangusaki/Aurora, MIT.

More from huangusaki/Aurora