Anthropic API (unofficial showcase)
POST/v1/skills

Create a skill

Creates a skill from uploaded files and creates its initial version. Provide the files in a single top-level directory with SKILL.md at that directory's root; optionally set display_name to a human-readable label. If omitted, the label is derived from the SKILL.md frontmatter name.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

2 parameters · 2 body fields
anthropic-versionstringoptional
The version of the Claude API to use.
anthropic-workspace-idstringoptional
Workspace ID to select when the credential can act on multiple Workspaces. A credential tied to one Workspace can omit it; if supplied, it must match that Workspace.

Multipart form data containing the skill files and an optional display name.

filesarray<string>required
Files to upload for the skill. All files must be in the same top-level directory and must include a SKILL.md file at the root of that directory.
display_namestringoptional
Human-readable, single-line label for the Skill. Maximum 255 characters. Always set: derived from the SKILL.md frontmatter `name` when omitted at creation. Not unique.

17 status codes
200Returns the created skill object, including its ID, display name, source, timestamps, and ID for its latest version.
created_atstringrequired
ISO 8601 timestamp of when the skill was created.
display_namestringrequired
Human-readable, single-line label for the Skill. Maximum 255 characters. Always set: derived from the SKILL.md frontmatter `name` when omitted at creation. Not unique.
idstringrequired
Unique identifier for the skill. The format and length of IDs may change over time.
latest_version_idstringrequired
ID of the newest Skill Version — what `latest` references resolve to. Always set: a Skill holds at least one version.
sourceobjectrequired
Where the Skill comes from. Possible values: * `"custom"`: authored by the platform user; private to their workspace * `"anthropic"`: published by Anthropic; shared and read-only * `"anthropic_example"`: Anthropic-published sample Skill * `"plugin"`: resolved from an installed plugin
typestringrequired
Object type. For Skills, this is always `"skill"`.
Default:skill
updated_atstringrequired
ISO 8601 timestamp of when the skill was last updated.
400Returned when the request contains an invalid argument, such as missing or incorrectly structured skill files.
errorobjectrequired
request_idstringrequired
Default:null
typestringrequired
Default:error
401Returned when the request does not have valid authentication credentials.
errorobjectrequired
request_idstringrequired
Default:null
typestringrequired
Default:error
403Returned when the caller does not have permission to perform the operation.
errorobjectrequired
request_idstringrequired
Default:null
typestringrequired
Default:error
404Returned when a requested entity is not found.
errorobjectrequired
request_idstringrequired
Default:null
typestringrequired
Default:error
408Returned when the operation's deadline expires before completion.
errorobjectrequired
request_idstringrequired
Default:null
typestringrequired
Default:error
409Returned when a concurrency issue aborts the operation.
errorobjectrequired
request_idstringrequired
Default:null
typestringrequired
Default:error
412Returned when the operation is rejected because the system is not in the required state.
errorobjectrequired
request_idstringrequired
Default:null
typestringrequired
Default:error
413Returned when the operation is attempted beyond a valid range.
errorobjectrequired
request_idstringrequired
Default:null
typestringrequired
Default:error
429Returned when a resource is exhausted, such as when rate limits are reached.
errorobjectrequired
request_idstringrequired
Default:null
typestringrequired
Default:error
431Returned when request metadata is too large.
errorobjectrequired
request_idstringrequired
Default:null
typestringrequired
Default:error
499Returned when the client cancels the operation.
errorobjectrequired
request_idstringrequired
Default:null
typestringrequired
Default:error
500Returned when an internal server error occurs.
errorobjectrequired
request_idstringrequired
Default:null
typestringrequired
Default:error
501Returned when the operation is not implemented or supported.
errorobjectrequired
request_idstringrequired
Default:null
typestringrequired
Default:error
503Returned when the service is unavailable.
errorobjectrequired
request_idstringrequired
Default:null
typestringrequired
Default:error
504Returned when an upstream service does not respond in time.
errorobjectrequired
request_idstringrequired
Default:null
typestringrequired
Default:error
529Returned when the service is temporarily overloaded.
errorobjectrequired
request_idstringrequired
Default:null
typestringrequired
Default:error

Error handling

A 400 is returned for an invalid argument; a 401 for invalid authentication in the x-api-key header; a 403 when the caller lacks permission; a 404 when a requested entity is not found; a 408 when the deadline expires; and a 409 when a concurrency issue aborts the operation. A 412 is returned when a precondition is not met; a 413 when the operation exceeds a valid range; a 429 when a resource is exhausted; a 431 when request metadata is too large; a 499 when the client cancels the operation; a 500 for an internal error; a 501 when the operation is unsupported; a 503 when the service is unavailable; a 504 when an upstream service times out; and a 529 when the service is overloaded. The files field must include SKILL.md at the root of a single top-level directory; display_name can contain at most 255 characters.