Repository Public
1---2title: Skills3url: https://platform.claude.com/docs/en/api/skills4---56# Skills78## Create Skill910**POST** `/v1/skills`1112Create Skill1314### Headers1516- `"anthropic-workspace-id": optional string`1718### Body parameters (form-data)1920- `files: array of string`2122 Files to upload for the skill.2324 All files must be in the same top-level directory and must include a SKILL.md file at the root of that directory.2526- `display_name: optional string or null`2728 Human-readable, single-line label for the Skill. Maximum 255 characters.29 Always set: derived from the SKILL.md frontmatter `name` when omitted at30 creation. Not unique.3132### Returns3334- `Skill object`3536 - `type: "skill"`3738 Object type.3940 For Skills, this is always `"skill"`.4142 default: skill4344 - `id: string`4546 Unique identifier for the skill.4748 The format and length of IDs may change over time.4950 - `created_at: string`5152 ISO 8601 timestamp of when the skill was created.5354 format: date-time5556 - `display_name: string`5758 Human-readable, single-line label for the Skill. Maximum 255 characters.59 Always set: derived from the SKILL.md frontmatter `name` when omitted at60 creation. Not unique.6162 - `latest_version_id: string`6364 ID of the newest Skill Version — what `latest` references resolve to. Always set: a Skill holds at least one version.6566 - `source: SkillSource`6768 Where the Skill comes from.6970 Possible values:7172 * `"custom"`: authored by the platform user; private to their workspace73 * `"anthropic"`: published by Anthropic; shared and read-only74 * `"anthropic_example"`: Anthropic-published sample Skill75 * `"plugin"`: resolved from an installed plugin7677 - `type: "custom" or "anthropic" or "anthropic_example" or "plugin"`7879 Where the Skill comes from.8081 Possible values:8283 * `"custom"`: authored by the platform user; private to their workspace84 * `"anthropic"`: published by Anthropic; shared and read-only85 * `"anthropic_example"`: Anthropic-published sample Skill86 * `"plugin"`: resolved from an installed plugin8788 - `"custom"`8990 - `"anthropic"`9192 - `"anthropic_example"`9394 - `"plugin"`9596 - `updated_at: string`9798 ISO 8601 timestamp of when the skill was last updated.99100 format: date-time101102### Example103104```bash105curl https://api.anthropic.com/v1/skills \106 -H 'Content-Type: multipart/form-data' \107 -H 'anthropic-version: 2023-06-01' \108 -H "X-Api-Key: $ANTHROPIC_API_KEY" \109 -F 'files[]=@/path/to/file'110```111112#### Response (200)113114```json115{116 "id": "skill_01JAbcdefghijklmnopqrstuvw",117 "created_at": "2024-10-30T23:58:27.427722Z",118 "display_name": "display_name",119 "latest_version_id": "latest_version_id",120 "source": {121 "type": "custom"122 },123 "type": "skill",124 "updated_at": "2024-10-30T23:58:27.427722Z"125}126```127128## List Skills129130**GET** `/v1/skills`131132List Skills133134### Query parameters135136- `limit: optional number`137138 Number of results to return per page.139140 Ranges from `1` to `1000`. Defaults to `20`.141142 default: 20, minimum: 1, maximum: 1000143144- `page: optional string`145146 Pagination token for fetching a specific page of results.147148 Pass the value from a previous response's `next_page` field to get the next page of results.149150- `source: optional string`151152 Filter skills by source.153154 If provided, only skills from the specified source will be returned:155156 * `"custom"`: only return user-created skills157 * `"anthropic"`: only return Anthropic-created skills158159### Headers160161- `"anthropic-workspace-id": optional string`162163### Returns164165- `data: array of Skill`166167 List of skills.168169 - `type: "skill"`170171 Object type.172173 For Skills, this is always `"skill"`.174175 default: skill176177 - `id: string`178179 Unique identifier for the skill.180181 The format and length of IDs may change over time.182183 - `created_at: string`184185 ISO 8601 timestamp of when the skill was created.186187 format: date-time188189 - `display_name: string`190191 Human-readable, single-line label for the Skill. Maximum 255 characters.192 Always set: derived from the SKILL.md frontmatter `name` when omitted at193 creation. Not unique.194195 - `latest_version_id: string`196197 ID of the newest Skill Version — what `latest` references resolve to. Always set: a Skill holds at least one version.198199 - `source: SkillSource`200201 Where the Skill comes from.202203 Possible values:204205 * `"custom"`: authored by the platform user; private to their workspace206 * `"anthropic"`: published by Anthropic; shared and read-only207 * `"anthropic_example"`: Anthropic-published sample Skill208 * `"plugin"`: resolved from an installed plugin209210 - `type: "custom" or "anthropic" or "anthropic_example" or "plugin"`211212 Where the Skill comes from.213214 Possible values:215216 * `"custom"`: authored by the platform user; private to their workspace217 * `"anthropic"`: published by Anthropic; shared and read-only218 * `"anthropic_example"`: Anthropic-published sample Skill219 * `"plugin"`: resolved from an installed plugin220221 - `"custom"`222223 - `"anthropic"`224225 - `"anthropic_example"`226227 - `"plugin"`228229 - `updated_at: string`230231 ISO 8601 timestamp of when the skill was last updated.232233 format: date-time234235- `next_page: string or null`236237 Token for fetching the next page of results.238239 If `null`, there are no more results available. Pass this value to the `page` parameter in the next request to get the next page.240241### Example242243```bash244curl https://api.anthropic.com/v1/skills \245 -H 'anthropic-version: 2023-06-01' \246 -H "X-Api-Key: $ANTHROPIC_API_KEY"247```248249#### Response (200)250251```json252{253 "data": [254 {255 "id": "skill_01JAbcdefghijklmnopqrstuvw",256 "created_at": "2024-10-30T23:58:27.427722Z",257 "display_name": "display_name",258 "latest_version_id": "latest_version_id",259 "source": {260 "type": "custom"261 },262 "type": "skill",263 "updated_at": "2024-10-30T23:58:27.427722Z"264 }265 ],266 "next_page": "next_page"267}268```269270## Get Skill271272**GET** `/v1/skills/{skill_id}`273274Get Skill275276### Path parameters277278- `skill_id: string`279280 Unique identifier for the skill.281282 The format and length of IDs may change over time.283284### Headers285286- `"anthropic-workspace-id": optional string`287288### Returns289290- `Skill object`291292 - `type: "skill"`293294 Object type.295296 For Skills, this is always `"skill"`.297298 default: skill299300 - `id: string`301302 Unique identifier for the skill.303304 The format and length of IDs may change over time.305306 - `created_at: string`307308 ISO 8601 timestamp of when the skill was created.309310 format: date-time311312 - `display_name: string`313314 Human-readable, single-line label for the Skill. Maximum 255 characters.315 Always set: derived from the SKILL.md frontmatter `name` when omitted at316 creation. Not unique.317318 - `latest_version_id: string`319320 ID of the newest Skill Version — what `latest` references resolve to. Always set: a Skill holds at least one version.321322 - `source: SkillSource`323324 Where the Skill comes from.325326 Possible values:327328 * `"custom"`: authored by the platform user; private to their workspace329 * `"anthropic"`: published by Anthropic; shared and read-only330 * `"anthropic_example"`: Anthropic-published sample Skill331 * `"plugin"`: resolved from an installed plugin332333 - `type: "custom" or "anthropic" or "anthropic_example" or "plugin"`334335 Where the Skill comes from.336337 Possible values:338339 * `"custom"`: authored by the platform user; private to their workspace340 * `"anthropic"`: published by Anthropic; shared and read-only341 * `"anthropic_example"`: Anthropic-published sample Skill342 * `"plugin"`: resolved from an installed plugin343344 - `"custom"`345346 - `"anthropic"`347348 - `"anthropic_example"`349350 - `"plugin"`351352 - `updated_at: string`353354 ISO 8601 timestamp of when the skill was last updated.355356 format: date-time357358### Example359360```bash361curl https://api.anthropic.com/v1/skills/$SKILL_ID \362 -H 'anthropic-version: 2023-06-01' \363 -H "X-Api-Key: $ANTHROPIC_API_KEY"364```365366#### Response (200)367368```json369{370 "id": "skill_01JAbcdefghijklmnopqrstuvw",371 "created_at": "2024-10-30T23:58:27.427722Z",372 "display_name": "display_name",373 "latest_version_id": "latest_version_id",374 "source": {375 "type": "custom"376 },377 "type": "skill",378 "updated_at": "2024-10-30T23:58:27.427722Z"379}380```381382## Delete Skill383384**DELETE** `/v1/skills/{skill_id}`385386Delete Skill387388### Path parameters389390- `skill_id: string`391392 Unique identifier for the skill.393394 The format and length of IDs may change over time.395396### Headers397398- `"anthropic-workspace-id": optional string`399400### Returns401402- `DeletedSkill object`403404 - `type: "skill_deleted"`405406 Deleted object type.407408 For Skills, this is always `"skill_deleted"`.409410 default: skill_deleted411412 - `id: string`413414 Unique identifier for the skill.415416 The format and length of IDs may change over time.417418### Example419420```bash421curl https://api.anthropic.com/v1/skills/$SKILL_ID \422 -X DELETE \423 -H 'anthropic-version: 2023-06-01' \424 -H "X-Api-Key: $ANTHROPIC_API_KEY"425```426427#### Response (200)428429```json430{431 "id": "skill_01JAbcdefghijklmnopqrstuvw",432 "type": "skill_deleted"433}434```435436## Domain types437438### Deleted Skill439440- `DeletedSkill object`441442 - `type: "skill_deleted"`443444 Deleted object type.445446 For Skills, this is always `"skill_deleted"`.447448 default: skill_deleted449450 - `id: string`451452 Unique identifier for the skill.453454 The format and length of IDs may change over time.455456### Skill457458- `Skill object`459460 - `type: "skill"`461462 Object type.463464 For Skills, this is always `"skill"`.465466 default: skill467468 - `id: string`469470 Unique identifier for the skill.471472 The format and length of IDs may change over time.473474 - `created_at: string`475476 ISO 8601 timestamp of when the skill was created.477478 format: date-time479480 - `display_name: string`481482 Human-readable, single-line label for the Skill. Maximum 255 characters.483 Always set: derived from the SKILL.md frontmatter `name` when omitted at484 creation. Not unique.485486 - `latest_version_id: string`487488 ID of the newest Skill Version — what `latest` references resolve to. Always set: a Skill holds at least one version.489490 - `source: SkillSource`491492 Where the Skill comes from.493494 Possible values:495496 * `"custom"`: authored by the platform user; private to their workspace497 * `"anthropic"`: published by Anthropic; shared and read-only498 * `"anthropic_example"`: Anthropic-published sample Skill499 * `"plugin"`: resolved from an installed plugin500501 - `type: "custom" or "anthropic" or "anthropic_example" or "plugin"`502503 Where the Skill comes from.504505 Possible values:506507 * `"custom"`: authored by the platform user; private to their workspace508 * `"anthropic"`: published by Anthropic; shared and read-only509 * `"anthropic_example"`: Anthropic-published sample Skill510 * `"plugin"`: resolved from an installed plugin511512 - `"custom"`513514 - `"anthropic"`515516 - `"anthropic_example"`517518 - `"plugin"`519520 - `updated_at: string`521522 ISO 8601 timestamp of when the skill was last updated.523524 format: date-time525526### Skill Source527528- `SkillSource object`529530 - `type: "custom" or "anthropic" or "anthropic_example" or "plugin"`531532 Where the Skill comes from.533534 Possible values:535536 * `"custom"`: authored by the platform user; private to their workspace537 * `"anthropic"`: published by Anthropic; shared and read-only538 * `"anthropic_example"`: Anthropic-published sample Skill539 * `"plugin"`: resolved from an installed plugin540541 - `"custom"`542543 - `"anthropic"`544545 - `"anthropic_example"`546547 - `"plugin"`548549## Skills › Versions550551### Create Skill Version552553**POST** `/v1/skills/{skill_id}/versions`554555Create Skill Version556557#### Path parameters558559- `skill_id: string`560561 Unique identifier for the skill.562563 The format and length of IDs may change over time.564565#### Headers566567- `"anthropic-workspace-id": optional string`568569#### Body parameters (form-data)570571- `files: array of string`572573 Files to upload for the skill.574575 All files must be in the same top-level directory and must include a SKILL.md file at the root of that directory.576577#### Returns578579- `SkillVersion object`580581 - `type: "skill_version"`582583 Object type.584585 For Skill Versions, this is always `"skill_version"`.586587 default: skill_version588589 - `id: string`590591 Unique identifier for this Skill Version. The id addresses the version in592 paths and pins it in references.593594 - `created_at: string`595596 ISO 8601 timestamp of when the skill was created.597598 format: date-time599600 - `description: string`601602 Description of the skill version.603604 This is extracted from the SKILL.md file in the skill upload.605606 - `name: string`607608 The Skill's immutable kebab-case slug, set at creation from the first609 upload's SKILL.md frontmatter `name` (or its enclosing directory). Every610 later upload must resolve to the same value. Also the top-level directory611 of the Skill's mounted files and the base name of a downloaded archive.612613 - `skill_id: string`614615 Unique identifier for the skill.616617 The format and length of IDs may change over time.618619#### Example620621```bash622curl https://api.anthropic.com/v1/skills/$SKILL_ID/versions \623 -H 'Content-Type: multipart/form-data' \624 -H 'anthropic-version: 2023-06-01' \625 -H "X-Api-Key: $ANTHROPIC_API_KEY" \626 -F 'files[]=@/path/to/file'627```628629##### Response (200)630631```json632{633 "id": "id",634 "created_at": "2024-10-30T23:58:27.427722Z",635 "description": "description",636 "name": "name",637 "skill_id": "skill_01JAbcdefghijklmnopqrstuvw",638 "type": "skill_version"639}640```641642### List Skill Versions643644**GET** `/v1/skills/{skill_id}/versions`645646List Skill Versions647648#### Path parameters649650- `skill_id: string`651652 Unique identifier for the skill.653654 The format and length of IDs may change over time.655656#### Query parameters657658- `limit: optional number`659660 Number of results to return per page.661662 Ranges from `1` to `1000`. Defaults to `20`.663664 default: 20, minimum: 1, maximum: 1000665666- `page: optional string`667668 Optionally set to the `next_page` token from the previous response.669670#### Headers671672- `"anthropic-workspace-id": optional string`673674#### Returns675676- `data: array of SkillVersion`677678 List of skills.679680 - `type: "skill_version"`681682 Object type.683684 For Skill Versions, this is always `"skill_version"`.685686 default: skill_version687688 - `id: string`689690 Unique identifier for this Skill Version. The id addresses the version in691 paths and pins it in references.692693 - `created_at: string`694695 ISO 8601 timestamp of when the skill was created.696697 format: date-time698699 - `description: string`700701 Description of the skill version.702703 This is extracted from the SKILL.md file in the skill upload.704705 - `name: string`706707 The Skill's immutable kebab-case slug, set at creation from the first708 upload's SKILL.md frontmatter `name` (or its enclosing directory). Every709 later upload must resolve to the same value. Also the top-level directory710 of the Skill's mounted files and the base name of a downloaded archive.711712 - `skill_id: string`713714 Unique identifier for the skill.715716 The format and length of IDs may change over time.717718- `next_page: string or null`719720 Token for fetching the next page of results.721722 If `null`, there are no more results available. Pass this value to the `page` parameter in the next request to get the next page.723724#### Example725726```bash727curl https://api.anthropic.com/v1/skills/$SKILL_ID/versions \728 -H 'anthropic-version: 2023-06-01' \729 -H "X-Api-Key: $ANTHROPIC_API_KEY"730```731732##### Response (200)733734```json735{736 "data": [737 {738 "id": "id",739 "created_at": "2024-10-30T23:58:27.427722Z",740 "description": "description",741 "name": "name",742 "skill_id": "skill_01JAbcdefghijklmnopqrstuvw",743 "type": "skill_version"744 }745 ],746 "next_page": "next_page"747}748```749750### Get Skill Version751752**GET** `/v1/skills/{skill_id}/versions/{version}`753754Get Skill Version755756#### Path parameters757758- `skill_id: string`759760 Unique identifier for the skill.761762 The format and length of IDs may change over time.763764- `version: string`765766 Identifies the skill version: a version ID, or the literal `latest` for the skill's most recent version.767768 Requests carrying the `skills-2025-10-02` beta header address versions by their Unix epoch timestamp instead (e.g., "1759178010641129").769770#### Headers771772- `"anthropic-workspace-id": optional string`773774#### Returns775776- `SkillVersion object`777778 - `type: "skill_version"`779780 Object type.781782 For Skill Versions, this is always `"skill_version"`.783784 default: skill_version785786 - `id: string`787788 Unique identifier for this Skill Version. The id addresses the version in789 paths and pins it in references.790791 - `created_at: string`792793 ISO 8601 timestamp of when the skill was created.794795 format: date-time796797 - `description: string`798799 Description of the skill version.800801 This is extracted from the SKILL.md file in the skill upload.802803 - `name: string`804805 The Skill's immutable kebab-case slug, set at creation from the first806 upload's SKILL.md frontmatter `name` (or its enclosing directory). Every807 later upload must resolve to the same value. Also the top-level directory808 of the Skill's mounted files and the base name of a downloaded archive.809810 - `skill_id: string`811812 Unique identifier for the skill.813814 The format and length of IDs may change over time.815816#### Example817818```bash819curl https://api.anthropic.com/v1/skills/$SKILL_ID/versions/$VERSION \820 -H 'anthropic-version: 2023-06-01' \821 -H "X-Api-Key: $ANTHROPIC_API_KEY"822```823824##### Response (200)825826```json827{828 "id": "id",829 "created_at": "2024-10-30T23:58:27.427722Z",830 "description": "description",831 "name": "name",832 "skill_id": "skill_01JAbcdefghijklmnopqrstuvw",833 "type": "skill_version"834}835```836837### Delete Skill Version838839**DELETE** `/v1/skills/{skill_id}/versions/{version}`840841Delete Skill Version842843#### Path parameters844845- `skill_id: string`846847 Unique identifier for the skill.848849 The format and length of IDs may change over time.850851- `version: string`852853 Identifies the skill version by its version ID.854855 Requests carrying the `skills-2025-10-02` beta header address versions by their Unix epoch timestamp instead (e.g., "1759178010641129").856857#### Headers858859- `"anthropic-workspace-id": optional string`860861#### Returns862863- `DeletedSkillVersion object`864865 - `type: "skill_version_deleted"`866867 Deleted object type.868869 For Skill Versions, this is always `"skill_version_deleted"`.870871 default: skill_version_deleted872873 - `id: string`874875 Unique identifier for this Skill Version. The id addresses the version in876 paths and pins it in references.877878#### Example879880```bash881curl https://api.anthropic.com/v1/skills/$SKILL_ID/versions/$VERSION \882 -X DELETE \883 -H 'anthropic-version: 2023-06-01' \884 -H "X-Api-Key: $ANTHROPIC_API_KEY"885```886887##### Response (200)888889```json890{891 "id": "id",892 "type": "skill_version_deleted"893}894```895