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