AgentUse 标准协议

SKILL.md 是强烈建议的上下文与分发载体，可与 CLI、MCP、OpenAPI 3.1 任一适配方式组合使用。它不是所有软件的强制入口，但适合补充使用场景、工作流与领域说明，采用 YAML Frontmatter + Markdown Body 结构。

---
name: my-skill
description: Clearly describe the skill's function and trigger scenarios
license: MIT
compatibility: ">=1.0.0"
allowed-tools: Bash Read Write
metadata:
  author: your-org
  version: "1.0.0"
  category: document-processing
  protocols:
    - mcp
    - cli
---

Agent-Ready 软件必须通过 CLI 能力清单、MCP tools/list 或 OpenAPI 文档提供机器可读契约。不同入口应覆盖相同核心语义：能力 ID、描述、输入、输出、认证、风险与结果。

MCP 能力声明示例（tools/list）：

{
  "tools": [
    {
      "name": "create_order",
      "description": "Create a new order. Accepts product ID, quantity, and shipping address; returns order ID and status.",
      "inputSchema": {
        "type": "object",
        "required": ["product_id", "quantity"],
        "properties": {
          "product_id": {
            "type": "string",
            "pattern": "^prod_[a-zA-Z0-9]+$",
            "description": "Unique product identifier",
            "example": "prod_A8k3Xp"
          },
          "quantity": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000,
            "description": "Order quantity, range 1-1000",
            "example": 5
          }
        }
      },
      "x-agentuse-idempotent": false,
      "x-agentuse-risk-level": "L1",
      "x-agentuse-capabilities": ["write", "create"]
    }
  ]
}

协议扩展属性统一使用 x-agentuse-* 前缀，与 MCP 和 OpenAPI 原生命名空间并存。

统一响应信封格式：

{
  "ok": true,
  "data": { /* operation result */ },
  "warnings": [ /* non-fatal warnings, can be empty array */ ],
  "meta": {
    "operation_id": "op-123",
    "timestamp": "2026-05-06T12:00:00Z",
    "schema_version": "1.0"
  }
}

Agent-Ready 软件必须返回统一的结构化错误分类；CLI 映射为退出码，HTTP 映射为状态码，MCP 映射为结构化错误结果。

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "Parameter product_id format is invalid",
    "details": {
      "field": "product_id",
      "value": "12345",
      "expected_pattern": "^prod_[a-zA-Z0-9]+$"
    },
    "retryable": false,
    "suggestions": [
      "Use 'mytool products list' to query valid product IDs",
      "product_id must start with 'prod_'"
    ],
    "request_id": "req-123"
  },
  "meta": {
    "operation_id": "op-123",
    "timestamp": "2026-05-06T12:00:00Z"
  }
}