AgentUse 标准协议

Skill Manifest 是 AgentUse 标准的核心数据结构。每个 Agent-Ready 软件必须提供一个符合规范的 Skill Manifest，使 Agent 能够自动发现和理解其能力。基于 SKILL.md 开放标准，采用 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
  agent-ready-level: gold
  protocols:
    - webmcp
    - cli
---

Agent-Ready 软件必须提供机器可读的能力清单。能力清单描述软件能做什么，而非如何做。

WebMCP/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-ax-idempotent": false,
      "x-ax-risk-level": "L1",
      "x-ax-capabilities": ["write", "create"]
    }
  ]
}

扩展属性使用 x-ax- 前缀（Agent Experience），与 MCP 原生命名空间兼容。

统一响应信封格式：

{
  "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 软件必须返回结构化错误，而非自然语言错误文本。

{
  "ok": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "type": "input_error",
    "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_'"
    ]
  },
  "meta": {
    "operation_id": "op-123",
    "timestamp": "2026-05-06T12:00:00Z"
  }
}