Library

Push a skill from local files (upsert)

Multipart upsert. If no skill with the SKILL.md's name exists in the caller's account, creates one with visibility: "private". If a skill already exists and the content has changed, releases a new version (server-classified major/minor bump from contract-field diff: description, allowed-tools, compatibility). If content is unchanged, returns 200 with action: "unchanged" and no new version is created.

File-path encoding. Each file part's relative path within the skill is carried via the multipart Content-Disposition: filename parameter per RFC 7578. Most HTTP libraries set this automatically when you pass a File or Blob with a name. The server does NOT read a parallel paths JSON field — only the filename parameter.

Payload size. Total multipart body capped at 4.5 MB (the Vercel Function platform body limit). Larger payloads return 413 payload_too_large. The cap is enforced pre-parse via Content-Length so oversized requests never buffer the body.

Idempotency. Supports the optional Idempotency-Key header. Retries with the same key + same body return the cached response (2xx OR 4xx) with Idempotent-Replayed: true. Retries with a different body return 422 idempotency_key_reused. Concurrent retries while the first is in-flight return 409 idempotency_key_in_progress. Cached responses live for 24h.

Error codes: missing_skill_md, invalid_skill_md, invalid_path, duplicate_path, invalid_multipart, payload_too_large, plan_limit, source_conflict, concurrent_create, concurrent_update, handle_required, rate_limited, not_found (account lookup), idempotency_key_*.

post/api/v1/library

Request

Base URL: https://skillrepo.dev
URL: https://skillrepo.dev/api/v1/library
Auth: HTTP bearer

Headers

Idempotency-Keystring

Client-supplied idempotency key (max 255 chars). Retries with the same key + same request body return the cached response (with Idempotent-Replayed: true) instead of re-executing the handler. Retries with the same key + a different body return 422 idempotency_key_reused. Concurrent retries while the original is in-flight return 409 idempotency_key_in_progress. Cached responses live for 24 hours.

Response

Skill upserted — action is updated (new version released) or unchanged (server SHA-matched the latest version; no new version created). On Idempotency-Key replays the same body is returned with Idempotent-Replayed: true.

action'created' | 'updated' | 'unchanged' required

Server-detected outcome of an upsert. created = first time this name was pushed for the account. updated = name existed and content (SKILL.md or files) changed, so a new version was released. unchanged = name existed and content was identical; no new version was created.

bump'major' | 'minor' nullable required

Server-classified version bump on the updated action: major if any contract-level frontmatter field changed (description, allowed-tools, compatibility); minor otherwise. Null for created and unchanged.

Example response

{
  "skill": {
    "files": [
      {
        "contentType": "text/markdown"
      }
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.