AI 使用说明 - SkillCheck

主要入口

先用 GET 获取机器可读 contract，再用 POST 提交任务；如果任务未完成，用 jobId 继续轮询。

GET /api/skill-audit

POST /api/skill-audit

GET /api/skill-audit?jobId=<job-id>

行为说明

POST returns the structured report in report when the job completes within the requested timeout.

If the result is not ready yet, the response uses mode=pending and pollUrl to tell the caller where to poll.

If the same skill version and package hash were already reviewed, the API may return a cached result immediately.

GET without jobId returns this manifest so agents can discover the API contract from the endpoint itself.

请求体示例

POST /api/skill-audit
Content-Type: application/json

{
  "skillUrl": "https://clawhub.ai/spclaudehome/skill-vetter",
  "version": "1.0.0",
  "waitForCompletion": true,
  "timeoutMs": 90000,
  "pollIntervalMs": 1500
}

返回结构

{
  "mode": "result | pending",
  "jobId": "string",
  "pollUrl": "string",
  "status": "queued | running | completed | failed",
  "stage": "queued | metadata | download | ai_analyze | extract | scan | finalize | rate_limited | completed | failed",
  "cacheHit": "boolean",
  "queuePosition": "number | null",
  "version": "object | null",
  "report": "Skill audit report | null",
  "error": "object | null"
}

轮询示例

GET /api/skill-audit?jobId=<job-id-from-previous-response>

机器可读 Manifest

{
  "name": "SkillCheck AI Skill Audit API",
  "description": "Submit a ClawHub skill URL and receive a structured AI-generated risk report for the skill package.",
  "homepage": "https://clawskillcheck.com",
  "docs": {
    "guide": "https://clawskillcheck.com/for-ai"
  },
  "endpoints": {
    "describe": {
      "method": "GET",
      "url": "https://clawskillcheck.com/api/skill-audit",
      "purpose": "Return this machine-readable API manifest when jobId is omitted."
    },
    "create": {
      "method": "POST",
      "url": "https://clawskillcheck.com/api/skill-audit",
      "purpose": "Create a skill-audit job and optionally wait for completion."
    },
    "poll": {
      "method": "GET",
      "url": "https://clawskillcheck.com/api/skill-audit?jobId=<job-id>",
      "purpose": "Poll an existing job by jobId."
    }
  },
  "defaults": {
    "waitForCompletion": true,
    "timeoutMs": 90000,
    "pollIntervalMs": 1500
  },
  "requestBody": {
    "skillUrl": "string, required, a ClawHub skill page URL",
    "version": "string, optional, explicit version to validate on ClawHub",
    "waitForCompletion": "boolean, optional, default true",
    "timeoutMs": "integer, optional, default 90000, max 240000",
    "pollIntervalMs": "integer, optional, default 1500, min 250, max 5000"
  },
  "resultShape": {
    "mode": "result | pending",
    "jobId": "string",
    "pollUrl": "string",
    "status": "queued | running | completed | failed",
    "stage": "queued | metadata | download | ai_analyze | extract | scan | finalize | rate_limited | completed | failed",
    "cacheHit": "boolean",
    "queuePosition": "number | null",
    "version": "object | null",
    "report": "Skill audit report | null",
    "error": "object | null"
  },
  "behaviorNotes": [
    "POST returns the structured report in report when the job completes within the requested timeout.",
    "If the result is not ready yet, the response uses mode=pending and pollUrl to tell the caller where to poll.",
    "If the same skill version and package hash were already reviewed, the API may return a cached result immediately.",
    "GET without jobId returns this manifest so agents can discover the API contract from the endpoint itself."
  ],
  "examples": {
    "createJobBody": {
      "skillUrl": "https://clawhub.ai/spclaudehome/skill-vetter",
      "version": "1.0.0",
      "waitForCompletion": true,
      "timeoutMs": 90000,
      "pollIntervalMs": 1500
    },
    "pollJob": "https://clawskillcheck.com/api/skill-audit?jobId=<job-id>"
  }
}

给 AI 的 API 使用说明