Skip to main content

Contract: Skill Scanner Upload Validation Errors

Endpoint​

POST /scan-upload

Uploads a zipped skill package and scans the first discovered SKILL.md.

Existing Successful Response​

Successful scans continue to return the scanner's normal JSON response.

{
  "scan_id": "string",
  "skill_name": "string",
  "is_safe": true,
  "max_severity": "safe",
  "findings_count": 0,
  "scan_duration_seconds": 0.0,
  "timestamp": "2026-05-13T00:00:00",
  "findings": []
}

Validation Failure Response​

Malformed skill definitions that fail known skill loading or validation checks must return an HTTP validation failure, preferably 422 Unprocessable Entity.

{
  "detail": "SKILL.md missing required field: name"
}

Required Behavior​

  • A SKILL.md missing the required name field returns a validation failure with the actionable missing-field message.
  • Known skill loading and validation exceptions return validation failures instead of generic internal scan errors.
  • Unexpected scanner faults continue to return internal failure responses.
  • Validation response details must be sanitized and must not include stack traces, secrets, tokens, or unnecessary runtime paths.
  • Existing 400 Bad Request responses for archive-level request problems, such as invalid ZIP archives or no SKILL.md, remain unchanged.

Compatibility Notes​

  • Server-side UI clients already treat non-2xx scanner responses as unscanned; this contract improves the reason string without requiring browser-visible scanner access.
  • Automated callers can distinguish malformed skill submissions from service faults by response status.