## Context

agent-fleet 核心功能已经实现并部署到 arm0 上运行。但没有任何 Agent 知道怎么用它。项目的可用性完全取决于 Agent 能否正确接入。

需要两个交付物：
1. **API 参考文档**：给 Agent 看的 HTTP API 手册
2. **通用 Skill**：遵循标准 skill 规范的能力描述，不绑定特定平台

关键约束：Skill 必须是平台无关的。承担 Team Leader 角色的不一定是 OpenClaw，Codex、Claude Code、OpenCode、Hermes Agent 都可能是调度者。

## Goals / Non-Goals

**Goals:**
- 提供完整、准确、可直接使用的 API 参考文档
- 提供通用 Skill，任何 Agent 加载后就知道如何与 agent-fleet 交互
- 覆盖两种执行模式（ssh_cli + http_pull）的完整工作流
- 覆盖 Forgejo 集成的 Git 工作流

**Non-Goals:**
- 不写人类运维文档（部署、配置、排障）→ 这是另一个 change
- 不写特定平台的集成脚本（如 OpenClaw skill 的安装脚本）
- 不实现 SDK 或客户端库

## Decisions

### Decision 1: 通用 Skill 规范，不绑定平台

**选择**: Skill 使用标准 YAML frontmatter + Markdown body 格式

**理由**:
- 所有主流 Agent 平台都支持这种格式（OpenClaw、Claude Code、Codex CLI、OpenCode）
- 不包含任何平台特定语法，Agent 自行转换
- curl 格式是通用语言，所有 Agent 都能理解

**替代方案**:
- OpenClaw 专用 skill：限制了使用范围
- 多平台各自写：重复劳动，容易不一致

### Decision 2: 文档放在 repo 内

**选择**: `docs/` 目录放 API 参考和接入指南，`skill/` 目录放 SKILL.md

**理由**:
- 与代码同仓库，版本一致
- Agent 可以通过 Forgejo 直接读取文档
- Skill 可以被各平台 fork 或 symlink

### Decision 3: 文档从代码自动生成 + 手动补充

**选择**: API 端点列表手动维护（Phase 1），后续考虑从代码注释自动生成

**理由**:
- Phase 1 端点数量有限（~12 个），手动维护成本低
- 自动生成需要额外工具链（如 `utoipa`），Phase 1 不值得投入

## Risks / Trade-offs

- **[文档过时] 代码变更后文档可能不一致** → 文档与代码同仓库，PR review 时检查
- **[Skill 通用性限制] 通用意味着不能利用平台特性** → 通用是正确选择，平台特定优化由各 Agent 自行处理

## Open Questions

_(resolved)_

- ~~Skill 是否需要包含多语言版本（中/英）？~~ → 全部使用英文。原因：LLM 训练语料以英文为主，英文更 token-efficient、语义歧义更小。Skill 的受众是 Agent 不是人类。