Follow Discord
Sweep 22 Oct 2026 · 04:32Z Build v2.1.308 527 read Stable v2.1.308 Latest v2.1.308 Next v2.1.308 Feeds RSS JSON llms.txt llms-full.txt Unofficial
HomeDocsClaude Developer Platform 19 Aug 2026
One change · api

skills-guide changedbuild-with-claude/skills-guide

Nearest release: v2.1.237, published an hour after this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.

Recorded here
Lines+22added
Lines−155removed
From line 47 where the diff opens
First seen 14 Aug 2026 this site's first read of the page
Recorded edits21to this page, all time

The whole hunk

from line 47, old and new numbered
/
lines
from line 47
4747| ------------------ | ------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
4848| **Type value** | `anthropic` | `custom` |
4949| **Skill IDs** | Short names: `pptx`, `xlsx`, `docx`, `pdf` | Generated: `skill_01AbCdEfGhIjKlMnOpQrStUv` |
50| **Version format** | Date-based: `20251013` or `latest` | Epoch timestamp: `1759178010641129` or `latest` |
50| **Version format** | Date-based: `20251013` or `latest` | Version ID: `skver_01AbCdEfGhIjKlMnOpQrStUv` or `latest` |
5151| **Management** | Pre-built and maintained by Anthropic | Upload and manage through the [Skills API](https://platform.claude.com/docs/en/api/beta/skills/create) |
5252| **Availability** | Available to all users | Private to your workspace |
5353 
from line 58
5858To use Skills, you need:
5959 
60601. **Claude API key** from the [Claude Console](https://platform.claude.com/settings/keys)
612. **[Code execution tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool)** enabled in your requests
6162 
622. **Beta headers:**
63Skills are generally available on the Claude API and don't require an `anthropic-beta` header, either for the Skills API or for `container.skills` in Messages requests. The examples in this guide still send the `skills-2025-10-02` beta header (plus `code-execution-2025-08-25` in Messages requests) and use the SDKs' `beta` namespace. Both headers remain valid opt-ins, so the examples work as written, and you can omit them in your own requests.
6364 
64 * `code-execution-2025-08-25` - Enables code execution (required for Skills)
65 * `skills-2025-10-02` - Enables Skills API
66 * `files-api-2025-04-14` - Required only when you use the [Files API](https://platform.claude.com/docs/en/build-with-claude/files) to upload input files or download files a Skill produces
67 
683. **[Code execution tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool)** enabled in your requests
69 
7065Skills require the code execution tool, so use a model from its [model compatibility list](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool#model-compatibility).
7166 
7267***
from line 70
7570 
7671### Container parameter
7772 
78Skills are specified using the `container` parameter in the Messages API. You can include up to 8 Skills for each request.
73Skills are specified using the `container` parameter in the Messages API. You can include up to 20 Skills for each request.
7974 
8075The structure is identical for both Anthropic and custom Skills. Specify the required `type` and `skill_id`, and optionally include `version` to pin to a specific version:
8176 
from line 2251
22562251 
22572252Upload your custom Skill to make it available in your workspace. You can upload a zip archive or individual file objects. The Python SDK also provides a `files_from_dir` helper that accepts a directory path.
22582253 
2259Files are identified by the filename you attach. Per-file uploads must keep a common top-level directory in their paths (the `;filename=` suffix in the cURL example and the filename arguments in the SDK examples). A zip archive must contain the skill directory as its single top-level entry. For the walkthrough's skill, create one with `zip -r financial_skill.zip financial_skill/` and substitute it for the `example_skill.zip` placeholder in the zip-upload options.
2254Files are identified by the filename you attach (the `;filename=` suffix in the cURL example and the filename arguments in the SDK examples). For the walkthrough's skill, create a zip with `zip -r financial_skill.zip financial_skill/` and substitute it for the `example_skill.zip` placeholder in the zip-upload options.
22602255 
22612256<CodeGroup defaultLanguage="CLI">
22622257 ```bash cURL
from line 2521
25262521 
25272522**Requirements:**
25282523 
2529* Must include a `SKILL.md` file at the top level
2524* Must include a `SKILL.md` file at the upload root (or at the top of a single enclosing folder)
25302525 
2531* All files must specify a common root directory in their paths
2526* `display_name` is optional: when omitted, it derives from the `SKILL.md` `name`; an explicit value may be up to 255 characters and does not need to be unique within the workspace
25322527 
2533* The top-level directory name must match the `name` in `SKILL.md` frontmatter (case and underscore insensitive: `Financial_Skill` matches `financial-skill`)
2534 
2535* `display_title` is optional: when omitted, it derives from the `SKILL.md` `name`; an explicit value must be unique among the custom skills in your workspace
2536 
25372528* Total upload size must be under 30 MB (uncompressed)
25382529 
25392530* YAML frontmatter requirements:
from line 2787
27962787 
27972788### Deleting a Skill
27982789 
2799To delete a Skill, you must first delete all its versions:
2790Deleting a Skill also removes all of its versions. The cascade is GA-only behavior, so unlike the other examples in this guide, these call the GA surface directly rather than the `beta` namespace.
28002791 
28012792<CodeGroup defaultLanguage="CLI">
28022793 ```bash cURL
2803 # Step 1: List the versions, then delete each one
2804 curl "https://api.anthropic.com/v1/skills/skill_01AbCdEfGhIjKlMnOpQrStUv/versions" \
2805 -H "x-api-key: $ANTHROPIC_API_KEY" \
2806 -H "anthropic-version: 2023-06-01" \
2807 -H "anthropic-beta: skills-2025-10-02"
2808 
2809 # Repeat for each version the list returned
2810 curl -X DELETE "https://api.anthropic.com/v1/skills/skill_01AbCdEfGhIjKlMnOpQrStUv/versions/1759178010641129" \
2811 -H "x-api-key: $ANTHROPIC_API_KEY" \
2812 -H "anthropic-version: 2023-06-01" \
2813 -H "anthropic-beta: skills-2025-10-02"
2814 
2815 # Step 2: Delete the Skill
28162794 curl -X DELETE "https://api.anthropic.com/v1/skills/skill_01AbCdEfGhIjKlMnOpQrStUv" \
28172795 -H "x-api-key: $ANTHROPIC_API_KEY" \
2818 -H "anthropic-version: 2023-06-01" \
2819 -H "anthropic-beta: skills-2025-10-02"
2796 -H "anthropic-version: 2023-06-01"
28202797 ```
28212798 
28222799 ```bash CLI
2823 # Step 1: List the versions, then delete each one
2824 ant beta:skills:versions list \
2825 --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
2826 --transform version \
2827 --raw-output
2828 
2829 # Repeat for each version id the list returned
2830 ant beta:skills:versions delete \
2831 --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
2832 --version 1759178010641129 >/dev/null
2833 
2834 # Step 2: Delete the Skill
2835 ant beta:skills delete \
2800 ant skills delete \
28362801 --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null
28372802 ```
28382803 
from line 2804
28392804 ```python Python
28402805 client = anthropic.Anthropic()
28412806 
2842 # Step 1: Delete all versions
2843 for version in client.beta.skills.versions.list(
2844 skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv"
2845 ):
2846 client.beta.skills.versions.delete(
2847 skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
2848 version=version.version,
2849 )
2850 
2851 # Step 2: Delete the Skill
2852 client.beta.skills.delete(skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv")
2807 client.skills.delete(skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv")
28532808 ```
28542809 
28552810 ```typescript TypeScript
28562811 const client = new Anthropic();
28572812 
2858 // Step 1: Delete all versions
2859 for await (const version of client.beta.skills.versions.list(
2860 "skill_01AbCdEfGhIjKlMnOpQrStUv"
2861 )) {
2862 await client.beta.skills.versions.delete(version.version, {
2863 skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv"
2864 });
2865 }
2866 
2867 // Step 2: Delete the Skill
2868 await client.beta.skills.delete("skill_01AbCdEfGhIjKlMnOpQrStUv");
2813 await client.skills.delete("skill_01AbCdEfGhIjKlMnOpQrStUv");
28692814 ```
28702815 
28712816 ```csharp C#
2872 using Anthropic.Models.Beta.Skills.Versions;
2873 // ...
28742817 AnthropicClient client = new();
28752818 
2876 // Step 1: Delete all versions
2877 await foreach (var version in (await client.Beta.Skills.Versions.List("skill_01AbCdEfGhIjKlMnOpQrStUv")).Paginate())
2878 {
2879 await client.Beta.Skills.Versions.Delete(
2880 version.Version,
2881 new VersionDeleteParams { SkillID = "skill_01AbCdEfGhIjKlMnOpQrStUv" }
2882 );
2883 }
2884 
2885 // Step 2: Delete the Skill
2886 await client.Beta.Skills.Delete("skill_01AbCdEfGhIjKlMnOpQrStUv");
2819 await client.Skills.Delete("skill_01AbCdEfGhIjKlMnOpQrStUv");
28872820 ```
28882821 
28892822 ```go Go
28902823 client := anthropic.NewClient()
28912824 
2892 // Step 1: Delete all versions
2893 versions := client.Beta.Skills.Versions.ListAutoPaging(
2825 _, err := client.Skills.Delete(
28942826 context.TODO(),
28952827 "skill_01AbCdEfGhIjKlMnOpQrStUv",
2896 anthropic.BetaSkillVersionListParams{},
28972828 )
2898 
2899 for versions.Next() {
2900 version := versions.Current()
2901 _, err := client.Beta.Skills.Versions.Delete(
2902 context.TODO(),
2903 version.Version,
2904 anthropic.BetaSkillVersionDeleteParams{
2905 SkillID: "skill_01AbCdEfGhIjKlMnOpQrStUv",
2906 },
2907 )
2908 if err != nil {
2909 log.Fatal(err)
2910 }
2911 }
2912 if versions.Err() != nil {
2913 log.Fatal(versions.Err())
2914 }
2915 
2916 // Step 2: Delete the Skill
2917 _, err := client.Beta.Skills.Delete(
2918 context.TODO(),
2919 "skill_01AbCdEfGhIjKlMnOpQrStUv",
2920 anthropic.BetaSkillDeleteParams{},
2921 )
29222829 if err != nil {
29232830 log.Fatal(err)
29242831 }
from line 2832
29252832 ```
29262833 
29272834 ```java Java
2928 import com.anthropic.models.beta.skills.versions.VersionListPage;
2929 import com.anthropic.models.beta.skills.versions.VersionDeleteParams;
2930 // ...
29312835 void main() {
29322836 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
29332837 
2934 // Step 1: Delete all versions
2935 VersionListPage versions = client.beta().skills().versions().list("skill_01AbCdEfGhIjKlMnOpQrStUv");
2936 
2937 for (var version : versions.autoPager()) {
2938 client.beta().skills().versions().delete(
2939 version.version(),
2940 VersionDeleteParams.builder()
2941 .skillId("skill_01AbCdEfGhIjKlMnOpQrStUv")
2942 .build()
2943 );
2944 }
2945 
2946 // Step 2: Delete the Skill
2947 client.beta().skills().delete("skill_01AbCdEfGhIjKlMnOpQrStUv");
2838 client.skills().delete("skill_01AbCdEfGhIjKlMnOpQrStUv");
29482839 }
29492840 ```
29502841 
from line 2842
29512842 ```php PHP
29522843 $client = new Client();
29532844 
2954 // Step 1: Delete all versions
2955 $versions = $client->beta->skills->versions->list(
2845 $client->skills->delete(
29562846 skillID: 'skill_01AbCdEfGhIjKlMnOpQrStUv',
29572847 );
2958 
2959 foreach ($versions->pagingEachItem() as $version) {
2960 $client->beta->skills->versions->delete(
2961 skillID: 'skill_01AbCdEfGhIjKlMnOpQrStUv',
2962 version: $version->version,
2963 );
2964 }
2965 
2966 // Step 2: Delete the Skill
2967 $client->beta->skills->delete(
2968 skillID: 'skill_01AbCdEfGhIjKlMnOpQrStUv',
2969 );
29702848 ```
29712849 
29722850 ```ruby Ruby
29732851 client = Anthropic::Client.new
29742852 
2975 # Step 1: Delete all versions
2976 client.beta.skills.versions.list("skill_01AbCdEfGhIjKlMnOpQrStUv").auto_paging_each do |version|
2977 client.beta.skills.versions.delete(
2978 version.version,
2979 skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv"
2980 )
2981 end
2982 
2983 # Step 2: Delete the Skill
2984 client.beta.skills.delete("skill_01AbCdEfGhIjKlMnOpQrStUv")
2853 client.skills.delete("skill_01AbCdEfGhIjKlMnOpQrStUv")
29852854 ```
29862855</CodeGroup>
29872856 
2988Attempting to delete a Skill with existing versions returns a 400 error.
2989 
29902857### Versioning
29912858 
29922859Skills support versioning to manage updates safely:
from line 2866
29992866 
30002867**Custom Skills:**
30012868 
3002* Auto-generated epoch timestamps: `1759178010641129`
2869* Auto-generated version IDs: `skver_01AbCdEfGhIjKlMnOpQrStUv`
30032870* Use `"latest"` to always get the most recent version
30042871* Create new versions when updating Skill files
30052872 
3006A new version is a complete snapshot, not a delta: upload the Skill's full file set each time, under the same top-level directory name used at creation. Files you omit are not carried over. The following examples re-upload the complete `financial_skill/` bundle from [Creating a Skill](https://platform.claude.com/docs/en/build-with-claude/skills-guide#creating-a-skill).
2873A new version is a complete snapshot, not a delta: upload the Skill's full file set each time. Files you omit are not carried over, and the `name` in the new version's `SKILL.md` must match the Skill's existing name. The following examples re-upload the complete `financial_skill/` bundle from [Creating a Skill](https://platform.claude.com/docs/en/build-with-claude/skills-guide#creating-a-skill).
30072874 
30082875<CodeGroup defaultLanguage="CLI">
30092876 ```bash cURL
from line 3769
39023769 
39033770### Request limits
39043771 
3905* **Maximum Skills per request:** 8
3772* **Maximum Skills per request:** 20
39063773 
39073774* **Maximum Skill upload size:** 30 MB (all files combined, uncompressed)
39083775 
Feedback