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/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 调用方式