Publishing - MasterSkills

Publishing is two-phase so a human approval can sit between packaging and upload — the CLI enforces that pause; API consumers must honor it too.

`POST /publish/prepare`

Registers a draft from a client-built manifest and returns a presigned upload URL. No file content is sent here — only paths, sizes, and hashes.

// request
{
  "org": "acme",
  "slug": "review-checklist",
  "displayName": "Review checklist",
  "description": "…",
  "visibility": "private",
  "manifest": {
    "files": [
      { "path": "SKILL.md", "size": 4096, "sha256": "…" },
      { "path": "references/standards.md", "size": 20480, "sha256": "…" }
    ],
    "totalSize": 24576
  }
}

// 200
{
  "draftId": "…",
  "name": "@acme/review-checklist",
  "org": "acme",
  "uploadUrl": "https://…",        // presigned PUT for the package
  "nextVersion": 4,
  "warnings": []
}

org defaults to the device’s home org; membership in the target org is required. Validation on prepare:

Check	Failure
Slug format (lowercase letters, digits, dashes)	`400`
`SKILL.md` present in the manifest	`422`
Caps: 100 MB package, 50 MB per file	`422`
Path sanity (no traversal, no absolute paths)	`422`
Secret-looking files in the manifest	`422 secret_file`

`POST /publish/:draftId/complete`

After uploading the package to uploadUrl, complete the publish. The draft is bound to its creator.

// 200
{
  "skill": { "name": "@acme/review-checklist", "org": "acme", "slug": "review-checklist" },
  "version": { "number": 4, "contentHash": "…" }
}

Status	Body	Meaning
`422`	`{ "scanFindings": [ … ] }`	The server-side secret scan found something — nothing was published; show the findings
`422`	`manifest_mismatch`	Uploaded bytes differ from the prepared manifest — what was approved is not what arrived

The server never auto-publishes and never silently drops a finding — rejections carry the details, for a human to see.

⌘I