docs: add agent API reference, onboarding guide, and universal skill

- docs/agent-api-reference.md (473 lines): complete HTTP API reference for all 12 endpoints
- docs/agent-onboarding-guide.md (272 lines): ssh_cli and http_pull workflows, Forgejo integration
- skill/SKILL.md (281 lines): universal agent skill, platform-agnostic, curl-based examples

All content in English. No code changes.

openspec/changes/agent-onboarding-docs/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-12

openspec/changes/agent-onboarding-docs/design.md

@@ -0,0 +1,65 @@
+## 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 不是人类。

openspec/changes/agent-onboarding-docs/proposal.md

@@ -0,0 +1,37 @@
+## Why
+
+agent-fleet 的所有核心功能（双执行模型、Forgejo 集成、Receipt 验证）已经实现并在 arm0 上跑通。但没有任何 Agent 知道如何使用它。
+
+当前状态：
+- API 端点已经实现（注册、心跳、dequeue、status、receipt、webhook 等）
+- 双执行模式（ssh_cli + http_pull）已经实现
+- 但没有任何文档告诉 Agent "怎么接入、怎么调 API、怎么配合工作流"
+
+项目的可用性完全取决于 Agent 能否正确接入。没有文档和 skill，agent-fleet 就是一个没人会用的 API。
+
+同时，需要的是一个**通用 skill**（不绑定 OpenClaw），因为：
+- 承担 Team Leader 角色的不一定是 OpenClaw
+- Codex、Claude Code、OpenCode、Hermes Agent 等都需要能理解和使用 agent-fleet
+- Skill 是通用的 Agent 能力描述，遵循通用规范
+
+## What Changes
+
+- 新增 `docs/agent-api-reference.md`：完整的 HTTP API 参考文档，供任何 Agent 阅读
+- 新增 `docs/agent-onboarding-guide.md`：Agent 接入指南，包含两种模式的完整工作流程
+- 新增 `skill/` 目录：通用 Agent Skill 定义（SKILL.md），遵循通用 skill 规范
+- Skill 内容：API 调用方式、认证、任务生命周期、Forgejo 工作流、错误处理
+
+## Capabilities
+
+### New Capabilities
+- `agent-api-reference`: HTTP API 完整参考文档（端点、请求/响应格式、错误码、示例）
+- `agent-skill`: 通用 Agent Skill 定义，描述 Agent 如何与 agent-fleet 交互
+
+### Modified Capabilities
+_(无)_
+
+## Impact
+
+- **文档**：新增 2 个 Markdown 文档 + 1 个 Skill 定义
+- **代码**：无代码变更
+- **项目**：Skill 目录是新增结构，可能需要考虑放在 repo 的哪个位置

openspec/changes/agent-onboarding-docs/specs/agent-api-reference/spec.md

@@ -0,0 +1,43 @@
+## ADDED Requirements
+
+### Requirement: Complete HTTP API reference documentation
+项目 SHALL 提供完整的 HTTP API 参考文档（`docs/agent-api-reference.md`），供任何 Agent 阅读。文档 SHALL 覆盖所有公开端点，包含请求/响应格式、错误码、示例。
+
+#### Scenario: Agent reads API reference to understand available endpoints
+- **WHEN** Agent 阅读 `docs/agent-api-reference.md`
+- **THEN** 文档 SHALL 列出所有端点：healthz、agents/register、agents/heartbeat、agents/deregister、agents (GET)、tasks (GET)、tasks/{id} (GET)、tasks/dequeue、tasks/{id}/status、tasks/{id}/retry、tasks/{id}/complete、receipts、webhooks/forgejo
+- **AND** 每个端点 SHALL 包含：HTTP 方法、URL、请求体格式、响应格式、错误码、curl 示例
+
+#### Scenario: Agent checks authentication requirements
+- **WHEN** Agent 查看 API 参考的认证部分
+- **THEN** 文档 SHALL 说明：http_pull 模式需要 Bearer token（注册时获取），ssh_cli 模式不需要 Agent 认证，webhook 端点需要 HMAC-SHA256 签名
+
+#### Scenario: Agent understands error responses
+- **WHEN** Agent 收到错误响应
+- **THEN** 文档 SHALL 列出所有错误码：401 Unauthorized、403 Forbidden、404 Not Found、400 Bad Request、500 Internal Server Error
+- **AND** 每个错误码 SHALL 包含触发场景描述
+
+### Requirement: Agent onboarding guide
+项目 SHALL 提供 Agent 接入指南（`docs/agent-onboarding-guide.md`），描述两种执行模式的完整工作流程。
+
+#### Scenario: New agent team leader reads onboarding guide
+- **WHEN** 新的 Team Leader Agent（如 Jeeves）阅读 onboarding guide
+- **THEN** 文档 SHALL 描述两种执行模式的区别和使用场景：
+  - ssh_cli：Orchestrator 主动调度，适用于 Codex、Claude Code、OpenCode 等有 CLI 的 Agent
+  - http_pull：Agent 自主拉取，适用于 OpenClaw/Jeeves、Hermes 等有自己的调度器的 Agent
+
+#### Scenario: Agent follows ssh_cli workflow
+- **WHEN** Agent 按 ssh_cli 模式接入
+- **THEN** 文档 SHALL 描述完整流程：配置 host → Agent 安装 CLI → Orchestrator 自动发现 → 任务自动分配和执行 → PR 创建 → webhook 回调
+
+#### Scenario: Agent follows http_pull workflow
+- **WHEN** Agent 按 http_pull 模式接入
+- **THEN** 文档 SHALL 描述完整流程：调用 register API → 获取 token → 定期 heartbeat → 调用 dequeue 拉任务 → 执行 → 调用 complete/receipt API
+
+#### Scenario: Agent understands Forgejo integration
+- **WHEN** Agent 阅读 Forgejo 集成部分
+- **THEN** 文档 SHALL 描述：Issue 如何变成任务（webhook → label 解析）、任务如何关联 Git 分支（`task/{task_id}`）、PR 生命周期如何驱动状态更新（opened → review_pending、merged → completed）
+
+#### Scenario: Agent understands structured prompt format
+- **WHEN** ssh_cli 模式的 Agent 需要理解传入的 prompt
+- **THEN** 文档 SHALL 描述结构化 prompt 的格式：Task ID、Type、Goal、Constraints、Branch、Expected output、Validation

openspec/changes/agent-onboarding-docs/specs/agent-skill/spec.md

@@ -0,0 +1,41 @@
+## ADDED Requirements
+
+### Requirement: Universal Agent Skill definition
+项目 SHALL 提供一个通用 Agent Skill（`skill/SKILL.md`），遵循标准 skill 规范（YAML frontmatter + Markdown body）。Skill SHALL 不绑定任何特定 Agent 平台（OpenClaw、Claude Code、Codex、OpenCode、Hermes 等均可使用）。
+
+#### Scenario: Any agent discovers and loads the skill
+- **WHEN** 任意 Agent（Codex、Claude Code、OpenCode、Hermes 等）加载 skill/SKILL.md
+- **THEN** Skill SHALL 包含 YAML frontmatter：`name: agent-fleet-integration`，`description` 描述用途和触发条件
+- **AND** Skill body SHALL 使用标准 Markdown 格式（标题、代码块、示例）
+
+#### Scenario: Skill teaches agent how to interact with agent-fleet
+- **WHEN** Agent 阅读 Skill 内容
+- **THEN** Skill SHALL 包含 Quick Start 部分（最简单的接入示例，3 步以内）
+- **AND** 包含 Instructions 部分（详细的 API 调用流程）
+- **AND** 包含 Examples 部分（每种操作的 curl 示例）
+- **AND** 包含 Guidelines 部分（错误处理、重试策略、认证规则）
+
+#### Scenario: Skill covers both execution modes
+- **WHEN** Agent 需要选择执行模式
+- **THEN** Skill SHALL 清晰说明 ssh_cli 和 http_pull 的区别
+- **AND** 指导 Agent 如何判断自己应该使用哪种模式：
+  - 如果有 CLI 且在配置的主机上 → ssh_cli（由 Orchestrator 调度）
+  - 如果有自己的调度器或不在配置的主机上 → http_pull（自主拉取）
+
+#### Scenario: Skill includes Forgejo workflow
+- **WHEN** Agent 需要理解 Git 工作流
+- **THEN** Skill SHALL 描述分支命名约定（`task/{task_id}`）、PR 创建流程、webhook 触发机制
+
+#### Scenario: Skill includes error recovery guidance
+- **WHEN** Agent 遇到 API 错误
+- **THEN** Skill SHALL 提供常见错误的处理方式：
+  - 401 → 检查 token，必要时重新注册
+  - 404 → 任务可能已完成或不存在
+  - 409/400 → 检查任务状态是否允许该操作
+  - 网络错误 → 重试（指数退避）
+
+#### Scenario: Skill is portable across agent platforms
+- **WHEN** Skill 被不同平台的 Agent 使用
+- **THEN** Skill SHALL 不包含任何平台特定的语法或指令（如 OpenClaw 的 `sessions_send`、Claude Code 的 `hooks` 等）
+- **AND** 所有交互通过标准 HTTP 请求描述（curl 格式）
+- **AND** Agent 可根据自身能力将 curl 转换为对应的 HTTP 调用方式

openspec/changes/agent-onboarding-docs/tasks.md

@@ -0,0 +1,36 @@
+## 1. API 参考文档
+
+- [ ] 1.1 创建 `docs/agent-api-reference.md`
+- [ ] 1.2 列出所有公开端点（~12 个），每个包含：HTTP 方法、URL、请求体、响应体、错误码、curl 示例
+- [ ] 1.3 认证部分：http_pull token、webhook HMAC-SHA256 签名
+- [ ] 1.4 错误码汇总：401/403/404/400/500，每个附触发场景
+- [ ] 1.5 通用说明：base_url、Content-Type、字符编码、分页（如有）
+
+## 2. Agent 接入指南
+
+- [ ] 2.1 创建 `docs/agent-onboarding-guide.md`
+- [ ] 2.2 两种执行模式对比表（ssh_cli vs http_pull）
+- [ ] 2.3 ssh_cli 模式完整工作流：配置 host → CLI 安装 → 自动调度 → PR 工作流
+- [ ] 2.4 http_pull 模式完整工作流：register → heartbeat → dequeue → execute → complete/receipt
+- [ ] 2.5 Forgejo 集成说明：Issue → Task、分支命名、PR 生命周期
+- [ ] 2.6 结构化 prompt 格式说明（ssh_cli 模式下 Agent 收到的 prompt 结构）
+- [ ] 2.7 常见问题 FAQ
+
+## 3. 通用 Agent Skill
+
+- [ ] 3.1 创建 `skill/SKILL.md`（YAML frontmatter + Markdown body）
+- [ ] 3.2 Quick Start：最简接入示例（3 步以内）
+- [ ] 3.3 Instructions：详细 API 调用流程（register → heartbeat → dequeue → execute → complete）
+- [ ] 3.4 Examples：每种操作的 curl 示例
+- [ ] 3.5 Guidelines：错误处理、重试策略、认证规则
+- [ ] 3.6 执行模式选择指南：Agent 如何判断自己用 ssh_cli 还是 http_pull
+- [ ] 3.7 Forgejo 工作流说明（分支命名、PR 创建、webhook 触发）
+- [ ] 3.8 验证：Skill 内容与 API 参考文档一致、curl 示例可执行
+
+## 4. 验证
+
+- [ ] 4.1 API 参考文档覆盖所有已实现端点
+- [ ] 4.2 curl 示例基于 arm0 实例可执行
+- [ ] 4.3 Skill 格式符合标准规范（YAML frontmatter + Markdown body）
+- [ ] 4.4 Skill 不包含任何平台特定语法
+- [ ] 4.5 接入指南与当前代码实现一致