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