---
title: Usare le Agent Skills con l'API
url: https://platform.claude.com/docs/it/build-with-claude/skills-guide
description: Scopri come usare le Agent Skills per estendere le capacità di Claude tramite l'API.
---
Le Agent Skills estendono le capacità di Claude tramite cartelle organizzate di istruzioni, script e risorse. Questa guida ti mostra come usare sia le Skills predefinite sia quelle personalizzate con la Claude API.
Per il riferimento API completo, inclusi gli schemi di richiesta/risposta e tutti i parametri, consulta:
* [Riferimento API per la gestione delle Skills](https://platform.claude.com/docs/it/api/skills/list) - Operazioni CRUD per le Skills
* [Riferimento API per le versioni delle Skills](https://platform.claude.com/docs/it/api/skills/versions/list) - Gestione delle versioni
Per scoprire come la "zero data retention" (conservazione zero dei dati), o ZDR, si applica a questa funzionalità, consulta [API e conservazione dei dati](https://platform.claude.com/docs/it/manage-claude/api-and-data-retention).
## Link rapidi
Scopri come usare le Agent Skills per creare documenti con la Claude API in meno di 10 minuti.
Scopri come scrivere Skills efficaci che Claude possa individuare e usare con successo.
## Panoramica
Per uno sguardo approfondito all'architettura e alle applicazioni reali delle Agent Skills, leggi il post del blog di ingegneria: [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills).
Le Skills si integrano con la Messages API tramite lo [strumento di esecuzione del codice](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool). Sia che tu usi Skills predefinite gestite da Anthropic sia Skills personalizzate che hai caricato, la forma dell'integrazione è identica: entrambe richiedono l'esecuzione del codice e usano la stessa struttura `container`.
### Usare le Skills
Le Skills si integrano in modo identico nella Messages API indipendentemente dalla loro origine. Specifichi le Skills nel parametro `container` con `skill_id`, `type` e un `version` opzionale, e vengono eseguite nell'ambiente di esecuzione del codice.
Puoi usare Skills da due origini:
| Aspetto | Skills di Anthropic | Skills personalizzate |
| -------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **Valore di type** | `anthropic` | `custom` |
| **ID delle Skills** | Nomi brevi: `pptx`, `xlsx`, `docx`, `pdf` | Generati: `skill_01AbCdEfGhIjKlMnOpQrStUv` |
| **Formato della versione** | Basato sulla data: `20251013` o `latest` | ID di versione: `skver_01AbCdEfGhIjKlMnOpQrStUv` o `latest` |
| **Gestione** | Predefinite e mantenute da Anthropic | Carica e gestisci tramite la [Skills API](https://platform.claude.com/docs/it/api/skills/create) |
| **Disponibilità** | Disponibili per tutti gli utenti | Private per il tuo workspace |
Entrambe le origini di skill vengono restituite dall'[endpoint List Skills](https://platform.claude.com/docs/it/api/skills/list) (usa il parametro `source` per filtrare). La forma dell'integrazione e l'ambiente di esecuzione sono identici. L'unica differenza è da dove provengono le Skills e come vengono gestite.
### Prerequisiti
Per usare le Skills, hai bisogno di:
1. **Chiave API di Claude** dalla [Claude Console](https://platform.claude.com/settings/keys)
2. **[Strumento di esecuzione del codice](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool)** abilitato nelle tue richieste
Le Skills richiedono lo strumento di esecuzione del codice, quindi usa un modello presente nel suo [elenco di compatibilità dei modelli](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool#compatibility).
***
## Usare le Skills in Messages
### Parametro container
Le Skills vengono specificate usando il parametro `container` nella Messages API. Puoi includere fino a 20 Skills per ogni richiesta.
La struttura è identica sia per le Skills di Anthropic sia per quelle personalizzate. Specifica i campi obbligatori `type` e `skill_id` e, facoltativamente, includi `version` per fissare una versione specifica:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"container": {
"skills": [
{
"type": "anthropic",
"skill_id": "pptx",
"version": "latest"
}
]
},
"messages": [{
"role": "user",
"content": "Create a presentation about renewable energy"
}],
"tools": [{
"type": "code_execution_20250825",
"name": "code_execution"
}]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-5-5
max_tokens: 4096
container:
skills:
- type: anthropic
skill_id: pptx
version: latest
messages:
- role: user
content: Create a presentation about renewable energy
tools:
- type: code_execution_20250825
name: code_execution
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
container={
"skills": [{"type": "anthropic", "skill_id": "pptx", "version": "latest"}]
},
messages=[
{"role": "user", "content": "Create a presentation about renewable energy"}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
skills: [
{
type: "anthropic",
skill_id: "pptx",
version: "latest"
}
]
},
messages: [
{
role: "user",
content: "Create a presentation about renewable energy"
}
],
tools: [
{
type: "code_execution_20250825",
name: "code_execution"
}
]
});
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Container = new ContainerParams
{
Skills =
[
new SkillParams
{
Type = SkillParamsType.Anthropic,
SkillID = "pptx",
Version = "latest",
},
],
},
Messages = [new() { Role = Role.User, Content = "Create a presentation about renewable energy" }],
Tools = [new CodeExecutionTool20250825()],
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Container: anthropic.MessageCreateParamsContainerUnion{
OfContainers: &anthropic.ContainerParams{
Skills: []anthropic.SkillParams{
{
Type: anthropic.SkillParamsTypeAnthropic,
SkillID: "pptx",
Version: anthropic.String("latest"),
},
},
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Create a presentation about renewable energy")),
},
Tools: []anthropic.ToolUnionParam{
{OfCodeExecutionTool20250825: &anthropic.CodeExecutionTool20250825Param{}},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
```
```java Java
import com.anthropic.models.messages.ContainerParams;
import com.anthropic.models.messages.SkillParams;
import com.anthropic.models.messages.CodeExecutionTool20250825;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.container(ContainerParams.builder()
.addSkill(SkillParams.builder()
.type(SkillParams.Type.ANTHROPIC)
.skillId("pptx")
.version("latest")
.build())
.build())
.addUserMessage("Create a presentation about renewable energy")
.addTool(CodeExecutionTool20250825.builder().build())
.build();
Message response = client.messages().create(params);
System.out.println(response);
}
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => 'Create a presentation about renewable energy']
],
model: 'claude-opus-5-5',
container: [
'skills' => [
[
'type' => 'anthropic',
'skillID' => 'pptx',
'version' => 'latest'
]
]
],
tools: [
['type' => 'code_execution_20250825', 'name' => 'code_execution']
]
);
echo $message;
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
skills: [
{
type: "anthropic",
skill_id: "pptx",
version: "latest"
}
]
},
messages: [
{ role: "user", content: "Create a presentation about renewable energy" }
],
tools: [
{ type: "code_execution_20250825", name: "code_execution" }
]
)
puts message
```
### Scaricare i file generati
Quando le Skills creano documenti (Excel, PowerPoint, PDF, Word), restituiscono attributi `file_id` nella risposta. Devi usare la Files API per scaricare questi file.
**Come funziona:**
1. Le Skills creano file durante l'esecuzione del codice.
2. La risposta include un `file_id` per ogni file creato, all'interno dei blocchi di risultato dello strumento di esecuzione del codice (vedi [Formato della risposta](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool#response-format)).
3. Usa la Files API per scaricare il contenuto effettivo del file.
4. Salva in locale o elabora secondo necessità.
Per fornire file di input su cui le Skills possano lavorare, [caricali con la Files API](https://platform.claude.com/docs/it/build-with-claude/files#uploading-a-file) e fai riferimento a essi nella tua richiesta con un [blocco container upload](https://platform.claude.com/docs/it/build-with-claude/files#container-upload-blocks).
**Esempio: creare e scaricare un file Excel**
```bash cURL
# Passaggio 1: usa una Skill per creare un file
RESPONSE=$(curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"container": {
"skills": [
{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}
]
},
"messages": [{
"role": "user",
"content": "Create an Excel file with a simple budget spreadsheet"
}],
"tools": [{
"type": "code_execution_20250825",
"name": "code_execution"
}]
}')
# Passaggio 2: estrai file_id dalla risposta (con jq)
FILE_ID=$(echo "$RESPONSE" | jq -r '.content[] | select(.type=="bash_code_execution_tool_result") | .content | select(.type=="bash_code_execution_result") | .content[] | select(.file_id) | .file_id')
# Passaggio 3: ottieni il nome del file dai metadati
FILENAME=$(curl "https://api.anthropic.com/v1/files/$FILE_ID" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" | jq -r '.filename')
# Passaggio 4: scarica il file con la Files API
curl "https://api.anthropic.com/v1/files/$FILE_ID/content" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
--output "$FILENAME"
echo "Downloaded: $FILENAME"
```
```bash CLI
# Passaggio 1: usa la Skill xlsx per creare un file
# Passaggio 2: estrai file_id dalla risposta con --transform (percorso GJSON)
FILE_ID=$(ant messages create \
--transform 'content.#.content.content.#.file_id|@flatten|0' \
--raw-output <<'YAML'
model: claude-opus-5-5
max_tokens: 4096
container:
skills:
- type: anthropic
skill_id: xlsx
version: latest
messages:
- role: user
content: Create an Excel file with a simple budget spreadsheet
tools:
- type: code_execution_20250825
name: code_execution
YAML
)
# Passaggio 3: ottieni il nome del file dai metadati del file
FILENAME=$(ant files retrieve-metadata \
--file-id "$FILE_ID" \
--transform filename \
--raw-output)
# Passaggio 4: scarica il file usando la Files API
ant files download --file-id "$FILE_ID" --output "$FILENAME" > /dev/null
printf 'Downloaded: %s\n' "$FILENAME"
```
```python Python
client = anthropic.Anthropic()
# Passaggio 1: usa una Skill per creare un file
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
container={
"skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
},
messages=[
{
"role": "user",
"content": "Create an Excel file with a simple budget spreadsheet",
}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
# Passaggio 2: estrai gli ID dei file dalla risposta
def extract_file_ids(response):
file_ids = []
for item in response.content:
if item.type == "bash_code_execution_tool_result":
content_item = item.content
if content_item.type == "bash_code_execution_result":
# ogni elemento di contenuto è un blocco bash_code_execution_output con un file_id
for file in content_item.content:
file_ids.append(file.file_id)
return file_ids
# Passaggio 3: scarica il file usando la Files API
for file_id in extract_file_ids(response):
file_metadata = client.files.retrieve_metadata(file_id=file_id)
file_content = client.files.download(file_id=file_id)
# Passaggio 4: salva su disco
file_content.write_to_file(file_metadata.filename)
print(f"Downloaded: {file_metadata.filename}")
```
```typescript TypeScript
import { writeFile } from "node:fs/promises";
const client = new Anthropic();
// Passaggio 1: usa una Skill per creare un file
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
skills: [{ type: "anthropic", skill_id: "xlsx", version: "latest" }]
},
messages: [
{
role: "user",
content: "Create an Excel file with a simple budget spreadsheet"
}
],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
});
// Passaggio 2: estrai gli ID dei file dalla risposta
const fileIds: string[] = [];
for (const block of response.content) {
if (
block.type === "bash_code_execution_tool_result" &&
block.content.type === "bash_code_execution_result"
) {
for (const outputBlock of block.content.content) {
fileIds.push(outputBlock.file_id);
}
}
}
// Passaggio 3: scarica ogni file e salvalo su disco
for (const fileId of fileIds) {
const fileMetadata = await client.files.retrieveMetadata(fileId);
const fileResponse = await client.files.download(fileId);
await writeFile(fileMetadata.filename, Buffer.from(await fileResponse.arrayBuffer()));
console.log(`Downloaded: ${fileMetadata.filename}`);
}
```
```csharp C#
AnthropicClient client = new();
// Passaggio 1: usa una Skill per creare un file
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Container = new ContainerParams
{
Skills =
[
new SkillParams
{
Type = SkillParamsType.Anthropic,
SkillID = "xlsx",
Version = "latest",
},
],
},
Messages = [new() { Role = Role.User, Content = "Create an Excel file with a simple budget spreadsheet" }],
Tools = [new CodeExecutionTool20250825()],
};
var response = await client.Messages.Create(parameters);
// Passaggio 2: estrai gli ID dei file dalla risposta
List fileIds = [];
foreach (var block in response.Content)
{
if (block.TryPickBashCodeExecutionToolResult(out var toolResult)
&& toolResult.Content.TryPickBashCodeExecutionResultBlock(out var result))
{
foreach (var output in result.Content)
{
fileIds.Add(output.FileID);
}
}
}
// Passaggio 3: scarica ogni file e salvalo su disco
foreach (var fileId in fileIds)
{
var fileMetadata = await client.Files.RetrieveMetadata(fileId);
using var download = await client.Files.Download(fileId);
using var downloadStream = await download.ReadAsStream();
using var outputFile = File.Create(fileMetadata.Filename);
await downloadStream.CopyToAsync(outputFile);
Console.WriteLine($"Downloaded: {fileMetadata.Filename}");
}
```
```go Go
func main() {
client := anthropic.NewClient()
// Passo 1: usa una Skill per creare un file
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Container: anthropic.MessageCreateParamsContainerUnion{
OfContainers: &anthropic.ContainerParams{
Skills: []anthropic.SkillParams{
{
Type: anthropic.SkillParamsTypeAnthropic,
SkillID: "xlsx",
Version: anthropic.String("latest"),
},
},
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Create an Excel file with a simple budget spreadsheet")),
},
Tools: []anthropic.ToolUnionParam{
{OfCodeExecutionTool20250825: &anthropic.CodeExecutionTool20250825Param{}},
},
})
if err != nil {
log.Fatal(err)
}
// Passo 2: estrai gli ID dei file dalla risposta
fileIDs := extractFileIDs(response)
// Passo 3: scarica il file usando la Files API
for _, fileID := range fileIDs {
fileMetadata, err := client.Files.GetMetadata(context.TODO(), fileID, anthropic.FileGetMetadataParams{})
if err != nil {
log.Fatal(err)
}
fileContent, err := client.Files.Download(context.TODO(), fileID, anthropic.FileDownloadParams{})
if err != nil {
log.Fatal(err)
}
// Passo 4: salva su disco
out, err := os.Create(fileMetadata.Filename)
if err != nil {
log.Fatal(err)
}
if _, err := io.Copy(out, fileContent.Body); err != nil {
log.Fatal(err)
}
out.Close()
fileContent.Body.Close()
fmt.Printf("Downloaded: %s\n", fileMetadata.Filename)
}
}
func extractFileIDs(response *anthropic.Message) []string {
var fileIDs []string
for _, item := range response.Content {
switch v := item.AsAny().(type) {
case anthropic.BashCodeExecutionToolResultBlock:
if v.Content.Type == "bash_code_execution_result" {
for _, output := range v.Content.Content {
fileIDs = append(fileIDs, output.FileID)
}
}
}
}
return fileIDs
}
```
```java Java
import com.anthropic.models.messages.ContainerParams;
import com.anthropic.models.messages.SkillParams;
import com.anthropic.models.messages.CodeExecutionTool20250825;
import com.anthropic.models.messages.ContentBlock;
import com.anthropic.models.files.FileMetadata;
import com.anthropic.core.http.HttpResponse;
// ...
void main() throws Exception {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Passaggio 1: usa una Skill per creare un file
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.container(ContainerParams.builder()
.addSkill(SkillParams.builder()
.type(SkillParams.Type.ANTHROPIC)
.skillId("xlsx")
.version("latest")
.build())
.build())
.addUserMessage("Create an Excel file with a simple budget spreadsheet")
.addTool(CodeExecutionTool20250825.builder().build())
.build();
Message response = client.messages().create(params);
// Passaggio 2: estrai gli ID dei file dalla risposta
List fileIds = new ArrayList<>();
for (ContentBlock block : response.content()) {
if (block.isBashCodeExecutionToolResult()) {
var content = block.asBashCodeExecutionToolResult().content();
if (content.isBashCodeExecutionResultBlock()) {
for (var outputBlock : content.asBashCodeExecutionResultBlock().content()) {
fileIds.add(outputBlock.fileId());
}
}
}
}
// Passaggio 3: scarica il file usando la Files API
for (String fileId : fileIds) {
FileMetadata fileMetadata = client.files().retrieveMetadata(fileId);
HttpResponse fileContent = client.files().download(fileId);
// Passaggio 4: salva su disco
try (InputStream is = fileContent.body();
FileOutputStream fos = new FileOutputStream(fileMetadata.filename())) {
is.transferTo(fos);
}
System.out.println("Downloaded: " + fileMetadata.filename());
}
}
```
```php PHP
$client = new Client();
// Passaggio 1: usa una Skill per creare un file
$response = $client->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => 'Create an Excel file with a simple budget spreadsheet']
],
model: 'claude-opus-5-5',
container: [
'skills' => [
['type' => 'anthropic', 'skillID' => 'xlsx', 'version' => 'latest']
]
],
tools: [
['type' => 'code_execution_20250825', 'name' => 'code_execution']
]
);
// Passaggio 2: estrai gli ID dei file dalla risposta
function extractFileIds($response) {
$fileIds = [];
foreach ($response->content as $item) {
if ($item->type === 'bash_code_execution_tool_result') {
$contentItem = $item->content;
if ($contentItem->type === 'bash_code_execution_result') {
foreach ($contentItem->content as $file) {
$fileIds[] = $file->fileID;
}
}
}
}
return $fileIds;
}
// Passaggio 3: scarica il file usando la Files API
foreach (extractFileIds($response) as $fileId) {
$fileMetadata = $client->files->retrieveMetadata($fileId);
$fileContent = $client->files->download($fileId);
// Passaggio 4: salva su disco
file_put_contents($fileMetadata->filename, $fileContent);
echo "Downloaded: {$fileMetadata->filename}\n";
}
```
```ruby Ruby
client = Anthropic::Client.new
# Passaggio 1: usa una Skill per creare un file
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
skills: [{ type: "anthropic", skill_id: "xlsx", version: "latest" }]
},
messages: [
{
role: "user",
content: "Create an Excel file with a simple budget spreadsheet"
}
],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
)
# Passaggio 2: estrai gli ID dei file dalla risposta
def extract_file_ids(response)
file_ids = []
response.content.each do |item|
if item.type == :bash_code_execution_tool_result
content_item = item.content
if content_item.type == :bash_code_execution_result
content_item.content.each do |file|
file_ids << file.file_id
end
end
end
end
file_ids
end
# Passaggio 3: scarica il file usando la Files API
extract_file_ids(response).each do |file_id|
file_metadata = client.files.retrieve_metadata(file_id)
file_content = client.files.download(file_id)
# Passaggio 4: salva su disco
File.binwrite(file_metadata.filename, file_content.read)
puts "Downloaded: #{file_metadata.filename}"
end
```
**Operazioni aggiuntive della Files API:**
```bash cURL
# Ottieni i metadati del file
curl "https://api.anthropic.com/v1/files/$FILE_ID" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01"
# Elenca tutti i file
curl "https://api.anthropic.com/v1/files" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01"
# Elimina un file
curl -X DELETE "https://api.anthropic.com/v1/files/$FILE_ID" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01"
```
```bash CLI
# Ottieni i metadati del file
ant files retrieve-metadata \
--file-id "$FILE_ID" \
--transform '{filename,size_bytes}' \
--format yaml
# Elenca tutti i file
ant files list --transform '{filename,created_at}' --format yaml
# Elimina un file
ant files delete --file-id "$FILE_ID" >/dev/null
```
```python Python
client = anthropic.Anthropic()
file_id = "file_011CNha8iCJcU1wXNR6q4V8w"
# Ottieni i metadati del file
file_info = client.files.retrieve_metadata(file_id=file_id)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")
# Elenca tutti i file
for file in client.files.list():
print(f"{file.filename} - {file.created_at}")
# Elimina un file
client.files.delete(file_id=file_id)
```
```typescript TypeScript
const client = new Anthropic();
const fileId = "file_011CNha8iCJcU1wXNR6q4V8w";
// Ottieni i metadati del file
const fileInfo = await client.files.retrieveMetadata(fileId);
console.log(`Filename: ${fileInfo.filename}, Size: ${fileInfo.size_bytes} bytes`);
// Elenca tutti i file
for await (const file of client.files.list()) {
console.log(`${file.filename} - ${file.created_at}`);
}
// Elimina un file
await client.files.delete(fileId);
```
```csharp C#
AnthropicClient client = new();
var fileId = "file_011CNha8iCJcU1wXNR6q4V8w";
// Ottieni i metadati del file
var fileInfo = await client.Files.RetrieveMetadata(fileId);
Console.WriteLine($"Filename: {fileInfo.Filename}, Size: {fileInfo.SizeBytes} bytes");
// Elenca i file
await foreach (var file in (await client.Files.List()).Paginate())
{
Console.WriteLine($"{file.Filename} - {file.CreatedAt}");
}
// Elimina il file
await client.Files.Delete(fileId);
```
```go Go
client := anthropic.NewClient()
fileID := "file_011CNha8iCJcU1wXNR6q4V8w"
// Ottieni i metadati del file
fileInfo, err := client.Files.GetMetadata(context.TODO(), fileID, anthropic.FileGetMetadataParams{})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Filename: %s, Size: %d bytes\n", fileInfo.Filename, fileInfo.SizeBytes)
// Elenca tutti i file
files := client.Files.ListAutoPaging(context.TODO(), anthropic.FileListParams{})
for files.Next() {
file := files.Current()
fmt.Printf("%s - %s\n", file.Filename, file.CreatedAt)
}
if files.Err() != nil {
log.Fatal(files.Err())
}
// Elimina un file
_, err = client.Files.Delete(context.TODO(), fileID, anthropic.FileDeleteParams{})
if err != nil {
log.Fatal(err)
}
```
```java Java
import com.anthropic.models.files.FileMetadata;
import com.anthropic.models.files.FileListPage;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
String fileId = "file_011CNha8iCJcU1wXNR6q4V8w";
// Ottieni i metadati del file
FileMetadata fileInfo = client.files().retrieveMetadata(fileId);
System.out.println("Filename: " + fileInfo.filename() + ", Size: " + fileInfo.sizeBytes() + " bytes");
// Elenca i file (prima pagina)
FileListPage files = client.files().list();
for (var file : files.data()) {
System.out.println(file.filename() + " - " + file.createdAt());
}
// Elimina un file
client.files().delete(fileId);
}
```
```php PHP
$client = new Client();
$fileId = 'file_011CNha8iCJcU1wXNR6q4V8w';
// Ottieni i metadati del file
$fileInfo = $client->files->retrieveMetadata($fileId);
echo "Filename: {$fileInfo->filename}, Size: {$fileInfo->sizeBytes} bytes\n";
// Elenca i file (prima pagina)
foreach ($client->files->list()->getItems() as $file) {
echo "{$file->filename} - {$file->createdAt->format(DATE_ATOM)}\n";
}
// Elimina un file
$client->files->delete($fileId);
```
```ruby Ruby
client = Anthropic::Client.new
file_id = "file_011CNha8iCJcU1wXNR6q4V8w"
# Ottieni i metadati del file
file_info = client.files.retrieve_metadata(file_id)
puts "Filename: #{file_info.filename}, Size: #{file_info.size_bytes} bytes"
# Elenca tutti i file
client.files.list.auto_paging_each do |file|
puts "#{file.filename} - #{file.created_at}"
end
# Elimina un file
client.files.delete(file_id)
```
Per i dettagli completi, consulta [Files API](https://platform.claude.com/docs/it/build-with-claude/files).
### Conversazioni multi-turno
L'oggetto `container` della risposta contiene l'`id` del container e il timestamp `expires_at` (vedi [Riutilizzo del container](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool#container-reuse) per i dettagli sulla durata). Riutilizza lo stesso container in più messaggi specificando l'ID del container:
Il riutilizzo del container su più turni richiede più logica di un singolo comando shell, quindi usa il Claude SDK per farlo. Per costruire le richieste autonomamente, acquisisci `container.id` dalla prima risposta. Poi passalo nella richiesta successiva come `"container": {"id": "...", "skills": [...]}`, insieme alla cronologia della conversazione.
```bash CLI
# La prima richiesta crea il container
CONTAINER_ID=$(ant messages create \
--transform container.id \
--raw-output <<'YAML'
model: claude-opus-5-5
max_tokens: 4096
container:
skills:
- {type: anthropic, skill_id: xlsx, version: latest}
messages:
- role: user
content: Create a sample sales dataset and analyze it
tools:
- {type: code_execution_20250825, name: code_execution}
YAML
)
# Continua la conversazione con lo stesso container
ant messages create < block.type === "text")
.map((block) => block.text)
.join("\n")
},
{ role: "user", content: "What was the total revenue?" }
];
const response2 = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
id: response1.container!.id, // Reuse container
skills: [{ type: "anthropic", skill_id: "xlsx", version: "latest" }]
},
messages,
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
});
```
```csharp C#
AnthropicClient client = new();
// Prima richiesta con una Skill
var parameters1 = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Container = new ContainerParams
{
Skills =
[
new SkillParams
{
Type = SkillParamsType.Anthropic,
SkillID = "xlsx",
Version = "latest",
},
],
},
Messages = [new() { Role = Role.User, Content = "Create a sample sales dataset and analyze it" }],
Tools = [new CodeExecutionTool20250825()],
};
var response1 = await client.Messages.Create(parameters1);
// Continua la conversazione nello stesso container
// Riporta avanti il testo dell'assistente; container.id mantiene lo stato di esecuzione
var assistantText = string.Join(
"\n",
response1.Content.Select(block => block.TryPickText(out var text) ? text.Text : null).Where(text => text is not null)
);
var parameters2 = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Container = new ContainerParams
{
ID = response1.Container!.ID,
Skills =
[
new SkillParams
{
Type = SkillParamsType.Anthropic,
SkillID = "xlsx",
Version = "latest",
},
],
},
Messages =
[
new() { Role = Role.User, Content = "Create a sample sales dataset and analyze it" },
new() { Role = Role.Assistant, Content = assistantText },
new() { Role = Role.User, Content = "What was the total revenue?" },
],
Tools = [new CodeExecutionTool20250825()],
};
var response2 = await client.Messages.Create(parameters2);
Console.WriteLine(response2);
```
```go Go
client := anthropic.NewClient()
response1, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Container: anthropic.MessageCreateParamsContainerUnion{
OfContainers: &anthropic.ContainerParams{
Skills: []anthropic.SkillParams{
{
Type: anthropic.SkillParamsTypeAnthropic,
SkillID: "xlsx",
Version: anthropic.String("latest"),
},
},
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Create a sample sales dataset and analyze it")),
},
Tools: []anthropic.ToolUnionParam{
{OfCodeExecutionTool20250825: &anthropic.CodeExecutionTool20250825Param{}},
},
})
if err != nil {
log.Fatal(err)
}
// Riporta avanti il testo dell'assistente; container.id conserva lo stato di esecuzione
var textParts []string
for _, block := range response1.Content {
if block.Type == "text" {
textParts = append(textParts, block.Text)
}
}
assistantText := strings.Join(textParts, "\n")
response2, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Container: anthropic.MessageCreateParamsContainerUnion{
OfContainers: &anthropic.ContainerParams{
ID: anthropic.String(response1.Container.ID), // Reuse container
Skills: []anthropic.SkillParams{
{
Type: anthropic.SkillParamsTypeAnthropic,
SkillID: "xlsx",
Version: anthropic.String("latest"),
},
},
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Create a sample sales dataset and analyze it")),
{
Role: anthropic.MessageParamRoleAssistant,
Content: []anthropic.ContentBlockParamUnion{anthropic.NewTextBlock(assistantText)},
},
anthropic.NewUserMessage(anthropic.NewTextBlock("What was the total revenue?")),
},
Tools: []anthropic.ToolUnionParam{
{OfCodeExecutionTool20250825: &anthropic.CodeExecutionTool20250825Param{}},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response2)
```
```java Java
import com.anthropic.models.messages.ContainerParams;
import com.anthropic.models.messages.SkillParams;
import com.anthropic.models.messages.CodeExecutionTool20250825;
import com.anthropic.models.messages.ContentBlock;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params1 = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.container(ContainerParams.builder()
.addSkill(SkillParams.builder()
.type(SkillParams.Type.ANTHROPIC)
.skillId("xlsx")
.version("latest")
.build())
.build())
.addUserMessage("Create a sample sales dataset and analyze it")
.addTool(CodeExecutionTool20250825.builder().build())
.build();
Message response1 = client.messages().create(params1);
MessageCreateParams params2 = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.container(ContainerParams.builder()
.id(response1.container().get().id())
.addSkill(SkillParams.builder()
.type(SkillParams.Type.ANTHROPIC)
.skillId("xlsx")
.version("latest")
.build())
.build())
.addUserMessage("Create a sample sales dataset and analyze it")
// Riporta avanti il testo dell'assistente; container.id conserva lo stato di esecuzione
.addAssistantMessage(response1.content().stream()
.filter(ContentBlock::isText)
.map(block -> block.asText().text())
.collect(Collectors.joining("\n")))
.addUserMessage("What was the total revenue?")
.addTool(CodeExecutionTool20250825.builder().build())
.build();
Message response2 = client.messages().create(params2);
System.out.println(response2);
}
```
```php PHP
$client = new Client();
$response1 = $client->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => 'Create a sample sales dataset and analyze it']
],
model: 'claude-opus-5-5',
container: [
'skills' => [
['type' => 'anthropic', 'skillID' => 'xlsx', 'version' => 'latest']
]
],
tools: [
['type' => 'code_execution_20250825', 'name' => 'code_execution']
]
);
$messages = [
['role' => 'user', 'content' => 'Create a sample sales dataset and analyze it'],
// Riporta avanti il testo dell'assistente; container.id mantiene lo stato di esecuzione
['role' => 'assistant', 'content' => implode("\n", array_map(
fn ($block) => $block->text,
array_filter($response1->content, fn ($block) => $block->type === 'text'),
))],
['role' => 'user', 'content' => 'What was the total revenue?']
];
$response2 = $client->messages->create(
maxTokens: 4096,
messages: $messages,
model: 'claude-opus-5-5',
container: [
'id' => $response1->container->id,
'skills' => [
['type' => 'anthropic', 'skillID' => 'xlsx', 'version' => 'latest']
]
],
tools: [
['type' => 'code_execution_20250825', 'name' => 'code_execution']
]
);
echo $response2;
```
```ruby Ruby
client = Anthropic::Client.new
response1 = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
skills: [{ type: "anthropic", skill_id: "xlsx", version: "latest" }]
},
messages: [
{ role: "user", content: "Create a sample sales dataset and analyze it" }
],
tools: [
{ type: "code_execution_20250825", name: "code_execution" }
]
)
messages = [
{ role: "user", content: "Create a sample sales dataset and analyze it" },
{
# Riporta avanti il testo dell'assistente; container.id conserva lo stato di esecuzione
role: "assistant",
content: response1.content.filter_map { |block| block.text if block.type == :text }.join("\n")
},
{ role: "user", content: "What was the total revenue?" }
]
response2 = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
id: response1.container.id,
skills: [
{ type: "anthropic", skill_id: "xlsx", version: "latest" }
]
},
messages: messages,
tools: [
{ type: "code_execution_20250825", name: "code_execution" }
]
)
puts response2
```
### Operazioni di lunga durata
Le Skills possono eseguire operazioni che richiedono più turni. Gestisci gli stop reason `pause_turn`:
```bash cURL
# Richiesta iniziale
RESPONSE=$(curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"container": {
"skills": [
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest"
}
]
},
"messages": [{
"role": "user",
"content": "Generate and process a large sample dataset"
}],
"tools": [{
"type": "code_execution_20250825",
"name": "code_execution"
}]
}')
# Se stop_reason è "pause_turn", continua nello stesso container, aggiungendo
# l'array content della risposta precedente a messages come turno dell'assistente.
# Ripeti questa richiesta di continuazione finché stop_reason non è più "pause_turn".
STOP_REASON=$(echo "$RESPONSE" | jq -r '.stop_reason')
CONTAINER_ID=$(echo "$RESPONSE" | jq -r '.container.id')
RESPONSE=$(curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d "{
\"model\": \"claude-opus-5-5\",
\"max_tokens\": 4096,
\"container\": {
\"id\": \"$CONTAINER_ID\",
\"skills\": [{
\"type\": \"custom\",
\"skill_id\": \"skill_01AbCdEfGhIjKlMnOpQrStUv\",
\"version\": \"latest\"
}]
},
\"messages\": [],
\"tools\": [{
\"type\": \"code_execution_20250825\",
\"name\": \"code_execution\"
}]
}")
```
```bash CLI
RESP=$(mktemp)
# Richiesta iniziale: salva la risposta JSON completa in un file temporaneo
ant messages create > "$RESP" <<'YAML'
model: claude-opus-5-5
max_tokens: 4096
container:
skills:
- type: custom
skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
version: latest
messages:
- role: user
content: Generate and process a large sample dataset
tools:
- type: code_execution_20250825
name: code_execution
YAML
# Se stop_reason è "pause_turn", continua nello stesso container,
# aggiungendo l'array content della risposta precedente a messages come
# turno dell'assistente. Ripeti finché stop_reason non è più "pause_turn".
CONTAINER_ID=$(jq -r '.container.id' "$RESP")
ant messages create > "$RESP" < messages =
[
new() { Role = Role.User, Content = "Generate and process a large sample dataset" },
];
var maxRetries = 10;
string? containerId = null;
Message? response = null;
for (var i = 0; i < maxRetries; i++)
{
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Container = containerId is null
? new ContainerParams
{
Skills =
[
new SkillParams
{
Type = SkillParamsType.Custom,
SkillID = "skill_01AbCdEfGhIjKlMnOpQrStUv",
Version = "latest",
},
],
}
: new ContainerParams
{
ID = containerId,
Skills =
[
new SkillParams
{
Type = SkillParamsType.Custom,
SkillID = "skill_01AbCdEfGhIjKlMnOpQrStUv",
Version = "latest",
},
],
},
Messages = messages,
Tools = [new CodeExecutionTool20250825()],
};
response = await client.Messages.Create(parameters);
containerId = response.Container!.ID;
if (response.StopReason != StopReason.PauseTurn)
{
break;
}
// Aggiungi il contenuto del turno in pausa e continua
var assistantContent = JsonSerializer.SerializeToElement(
response.Content.Select(block => block.Json).ToArray()
);
messages.Add(new() { Role = Role.Assistant, Content = new MessageParamContent(assistantContent) });
}
```
```go Go
client := anthropic.NewClient()
messages := []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Generate and process a large sample dataset")),
}
maxRetries := 10
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Container: anthropic.MessageCreateParamsContainerUnion{
OfContainers: &anthropic.ContainerParams{
Skills: []anthropic.SkillParams{
{
Type: anthropic.SkillParamsTypeCustom,
SkillID: "skill_01AbCdEfGhIjKlMnOpQrStUv",
Version: anthropic.String("latest"),
},
},
},
},
Messages: messages,
Tools: []anthropic.ToolUnionParam{
{OfCodeExecutionTool20250825: &anthropic.CodeExecutionTool20250825Param{}},
},
})
if err != nil {
log.Fatal(err)
}
for i := 0; i < maxRetries; i++ {
if response.StopReason != anthropic.StopReasonPauseTurn {
break
}
messages = append(messages, response.ToParam())
response, err = client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Container: anthropic.MessageCreateParamsContainerUnion{
OfContainers: &anthropic.ContainerParams{
ID: anthropic.String(response.Container.ID), // Reuse container
Skills: []anthropic.SkillParams{
{
Type: anthropic.SkillParamsTypeCustom,
SkillID: "skill_01AbCdEfGhIjKlMnOpQrStUv",
Version: anthropic.String("latest"),
},
},
},
},
Messages: messages,
Tools: []anthropic.ToolUnionParam{
{OfCodeExecutionTool20250825: &anthropic.CodeExecutionTool20250825Param{}},
},
})
if err != nil {
log.Fatal(err)
}
}
fmt.Println(response)
```
```java Java
import com.anthropic.models.messages.ContainerParams;
import com.anthropic.models.messages.SkillParams;
import com.anthropic.models.messages.CodeExecutionTool20250825;
import com.anthropic.models.messages.StopReason;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
List messages = new ArrayList<>();
messages.add(
MessageParam.builder()
.role(MessageParam.Role.USER)
.content("Generate and process a large sample dataset")
.build()
);
int maxRetries = 10;
Message response = client.messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.container(ContainerParams.builder()
.addSkill(SkillParams.builder()
.type(SkillParams.Type.CUSTOM)
.skillId("skill_01AbCdEfGhIjKlMnOpQrStUv")
.version("latest")
.build())
.build())
.messages(messages)
.addTool(CodeExecutionTool20250825.builder().build())
.build());
for (int i = 0; i < maxRetries; i++) {
if (!response.stopReason().isPresent()
|| !response.stopReason().get().equals(StopReason.PAUSE_TURN)) {
break;
}
messages.add(response.toParam());
response = client.messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.container(ContainerParams.builder()
.id(response.container().get().id())
.addSkill(SkillParams.builder()
.type(SkillParams.Type.CUSTOM)
.skillId("skill_01AbCdEfGhIjKlMnOpQrStUv")
.version("latest")
.build())
.build())
.messages(messages)
.addTool(CodeExecutionTool20250825.builder().build())
.build());
}
}
```
```php PHP
$client = new Client();
$messages = [
['role' => 'user', 'content' => 'Generate and process a large sample dataset']
];
$maxRetries = 10;
$response = $client->messages->create(
maxTokens: 4096,
messages: $messages,
model: 'claude-opus-5-5',
container: [
'skills' => [
[
'type' => 'custom',
'skillID' => 'skill_01AbCdEfGhIjKlMnOpQrStUv',
'version' => 'latest'
]
]
],
tools: [['type' => 'code_execution_20250825', 'name' => 'code_execution']]
);
for ($i = 0; $i < $maxRetries; $i++) {
if ($response->stopReason !== 'pause_turn') {
break;
}
$messages[] = ['role' => 'assistant', 'content' => $response->content];
$response = $client->messages->create(
maxTokens: 4096,
messages: $messages,
model: 'claude-opus-5-5',
container: [
'id' => $response->container->id,
'skills' => [
[
'type' => 'custom',
'skillID' => 'skill_01AbCdEfGhIjKlMnOpQrStUv',
'version' => 'latest'
]
]
],
tools: [['type' => 'code_execution_20250825', 'name' => 'code_execution']]
);
}
```
```ruby Ruby
client = Anthropic::Client.new
messages = [
{ role: "user", content: "Generate and process a large sample dataset" }
]
max_retries = 10
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
skills: [
{
type: "custom",
skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv",
version: "latest"
}
]
},
messages: messages,
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
)
max_retries.times do
break if response.stop_reason != :pause_turn
messages << { role: "assistant", content: response.content }
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
id: response.container.id,
skills: [
{
type: "custom",
skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv",
version: "latest"
}
]
},
messages: messages,
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
)
end
```
La risposta può includere uno stop reason `pause_turn`, che indica che l'API ha messo in pausa un'operazione di Skill di lunga durata. Puoi fornire la risposta così com'è in una richiesta successiva per permettere a Claude di continuare il suo turno, oppure modificare il contenuto se vuoi interrompere la conversazione e fornire indicazioni aggiuntive.
### Usare più Skills
Combina più Skills in una singola richiesta per gestire flussi di lavoro complessi:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"container": {
"skills": [
{
"type": "anthropic",
"skill_id": "xlsx",
"version": "latest"
},
{
"type": "anthropic",
"skill_id": "pptx",
"version": "latest"
},
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest"
}
]
},
"messages": [{
"role": "user",
"content": "Analyze sales data and create a presentation"
}],
"tools": [{
"type": "code_execution_20250825",
"name": "code_execution"
}]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-5-5
max_tokens: 4096
container:
skills:
- type: anthropic
skill_id: xlsx
version: latest
- type: anthropic
skill_id: pptx
version: latest
- type: custom
skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
version: latest
messages:
- role: user
content: Analyze sales data and create a presentation
tools:
- type: code_execution_20250825
name: code_execution
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
container={
"skills": [
{"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
{"type": "anthropic", "skill_id": "pptx", "version": "latest"},
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest",
},
]
},
messages=[
{"role": "user", "content": "Analyze sales data and create a presentation"}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
skills: [
{
type: "anthropic",
skill_id: "xlsx",
version: "latest"
},
{
type: "anthropic",
skill_id: "pptx",
version: "latest"
},
{
type: "custom",
skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv",
version: "latest"
}
]
},
messages: [
{
role: "user",
content: "Analyze sales data and create a presentation"
}
],
tools: [
{
type: "code_execution_20250825",
name: "code_execution"
}
]
});
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Container = new ContainerParams
{
Skills =
[
new SkillParams
{
Type = SkillParamsType.Anthropic,
SkillID = "xlsx",
Version = "latest",
},
new SkillParams
{
Type = SkillParamsType.Anthropic,
SkillID = "pptx",
Version = "latest",
},
new SkillParams
{
Type = SkillParamsType.Custom,
SkillID = "skill_01AbCdEfGhIjKlMnOpQrStUv",
Version = "latest",
},
],
},
Messages = [new() { Role = Role.User, Content = "Analyze sales data and create a presentation" }],
Tools = [new CodeExecutionTool20250825()],
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Container: anthropic.MessageCreateParamsContainerUnion{
OfContainers: &anthropic.ContainerParams{
Skills: []anthropic.SkillParams{
{
Type: anthropic.SkillParamsTypeAnthropic,
SkillID: "xlsx",
Version: anthropic.String("latest"),
},
{
Type: anthropic.SkillParamsTypeAnthropic,
SkillID: "pptx",
Version: anthropic.String("latest"),
},
{
Type: anthropic.SkillParamsTypeCustom,
SkillID: "skill_01AbCdEfGhIjKlMnOpQrStUv",
Version: anthropic.String("latest"),
},
},
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze sales data and create a presentation")),
},
Tools: []anthropic.ToolUnionParam{
{OfCodeExecutionTool20250825: &anthropic.CodeExecutionTool20250825Param{}},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
```
```java Java
import com.anthropic.models.messages.ContainerParams;
import com.anthropic.models.messages.SkillParams;
import com.anthropic.models.messages.CodeExecutionTool20250825;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.container(ContainerParams.builder()
.skills(List.of(
SkillParams.builder()
.type(SkillParams.Type.ANTHROPIC)
.skillId("xlsx")
.version("latest")
.build(),
SkillParams.builder()
.type(SkillParams.Type.ANTHROPIC)
.skillId("pptx")
.version("latest")
.build(),
SkillParams.builder()
.type(SkillParams.Type.CUSTOM)
.skillId("skill_01AbCdEfGhIjKlMnOpQrStUv")
.version("latest")
.build()
))
.build())
.addUserMessage("Analyze sales data and create a presentation")
.addTool(CodeExecutionTool20250825.builder().build())
.build();
Message response = client.messages().create(params);
System.out.println(response);
}
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => 'Analyze sales data and create a presentation']
],
model: 'claude-opus-5-5',
container: [
'skills' => [
[
'type' => 'anthropic',
'skillID' => 'xlsx',
'version' => 'latest'
],
[
'type' => 'anthropic',
'skillID' => 'pptx',
'version' => 'latest'
],
[
'type' => 'custom',
'skillID' => 'skill_01AbCdEfGhIjKlMnOpQrStUv',
'version' => 'latest'
]
]
],
tools: [
['type' => 'code_execution_20250825', 'name' => 'code_execution']
]
);
echo $message;
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
skills: [
{
type: "anthropic",
skill_id: "xlsx",
version: "latest"
},
{
type: "anthropic",
skill_id: "pptx",
version: "latest"
},
{
type: "custom",
skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv",
version: "latest"
}
]
},
messages: [
{ role: "user", content: "Analyze sales data and create a presentation" }
],
tools: [
{ type: "code_execution_20250825", name: "code_execution" }
]
)
puts message
```
***
## Gestire le Skills personalizzate
**Le Skills personalizzate sono accessibili all'intero workspace, non limitate a un utente finale, una conversazione o una sessione.** Qualsiasi chiave API con accesso a un workspace può leggere, invocare ed eliminare ogni Skill personalizzata caricata in quel workspace. Ogni service account, e ogni utente il cui ruolo nell'organizzazione consente l'accesso all'API, può usare il Default Workspace oltre a qualsiasi workspace a cui lo aggiungi, quindi mantieni le Skills che devono restare separate nel proprio [workspace](https://platform.claude.com/docs/it/manage-claude/workspaces#api-keys-and-resource-scoping) e accedi a esse solo con chiavi limitate a quel workspace.
Se stai costruendo una piattaforma multi-tenant sulla Skills API, crea un [workspace](https://platform.claude.com/docs/it/manage-claude/workspaces) separato per ogni tenant. Il workspace è il confine di isolamento per le Skills personalizzate, quindi un workspace per tenant garantisce alle Skills di ciascun tenant un isolamento rigido da ogni altro tenant. Ogni organizzazione può avere fino a 100 workspace per impostazione predefinita (vedi [Come funzionano i workspace](https://platform.claude.com/docs/it/manage-claude/workspaces#how-workspaces-work)); se te ne servono di più per l'isolamento dei tenant, contatta il tuo team account.
### Creare una Skill
Un bundle di Skill è una directory contenente un file `SKILL.md` al livello superiore con frontmatter YAML `name` e `description`, più eventuali script o risorse di supporto. Consulta [Inizia con le Agent Skills nell'API](https://platform.claude.com/docs/it/agents-and-tools/agent-skills/quickstart) per crearne una, e l'elenco **Requisiti** che segue gli esempi per i vincoli completi.
Carica la tua Skill personalizzata per renderla disponibile nel tuo workspace. Puoi caricare un archivio zip o singoli oggetti file. L'SDK Python fornisce anche un helper `files_from_dir` che accetta il percorso di una directory, e il comando `ant apply` della CLI carica direttamente la directory.
I file sono identificati dal nome file che alleghi (il suffisso `;filename=` nell'esempio cURL e gli argomenti filename negli esempi SDK). Per la skill della procedura guidata, crea uno zip con `zip -r financial_skill.zip financial_skill/` e sostituiscilo al segnaposto `example_skill.zip` nelle opzioni di caricamento zip.
```bash cURL
curl -X POST "https://api.anthropic.com/v1/skills" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-F "files[]=@financial_skill/SKILL.md;filename=financial_skill/SKILL.md" \
-F "files[]=@financial_skill/analyze.py;filename=financial_skill/analyze.py"
```
```bash CLI
ant apply financial_skill
```
```markdown
---
name: financial-skill
description: Docs example skill.
---
```
```python
print("financial analysis helper")
```
```python Python
from anthropic.lib import files_from_dir
client = anthropic.Anthropic()
# Opzione 1: uso di un file zip
skill = client.skills.create(
files=[open("example_skill.zip", "rb")],
)
# Opzione 2: uso di tuple di file (filename, file_content, mime_type)
skill = client.skills.create(
files=[
(
"financial_skill/SKILL.md",
open("financial_skill/SKILL.md", "rb"),
"text/markdown",
),
(
"financial_skill/analyze.py",
open("financial_skill/analyze.py", "rb"),
"text/x-python",
),
],
)
# Opzione 3: uso dell'helper files_from_dir (solo Python)
skill = client.skills.create(
files=files_from_dir("financial_skill"),
)
print(f"Created skill: {skill.id}")
print(f"Latest version: {skill.latest_version_id}")
```
```typescript TypeScript
import { toFile } from "@anthropic-ai/sdk";
import fs from "node:fs";
// ...
const client = new Anthropic();
// Opzione 1: usando un file zip
const skillFromZip = await client.skills.create({
files: [await toFile(fs.createReadStream("example_skill.zip"), "example_skill.zip")]
});
// Opzione 2: usando singoli oggetti file
const skill = await client.skills.create({
files: [
await toFile(fs.createReadStream("financial_skill/SKILL.md"), "financial_skill/SKILL.md", {
type: "text/markdown"
}),
await toFile(
fs.createReadStream("financial_skill/analyze.py"),
"financial_skill/analyze.py",
{ type: "text/x-python" }
)
]
});
console.log(`Created skill: ${skill.id}`);
console.log(`Latest version: ${skill.latest_version_id}`);
```
```csharp C#
using Anthropic.Core;
// ...
AnthropicClient client = new();
// Opzione 1: utilizzo di un file zip
var parameters = new SkillCreateParams
{
Files = [File.OpenRead("example_skill.zip")],
};
var skill = await client.Skills.Create(parameters);
// Opzione 2: utilizzo di file singoli (i nomi di file con percorso preservano la struttura delle directory della Skill)
var parameters2 = new SkillCreateParams
{
Files =
[
new BinaryContent
{
Stream = File.OpenRead("financial_skill/SKILL.md"),
FileName = "financial_skill/SKILL.md",
},
new BinaryContent
{
Stream = File.OpenRead("financial_skill/analyze.py"),
FileName = "financial_skill/analyze.py",
},
],
};
var skill2 = await client.Skills.Create(parameters2);
Console.WriteLine($"Created skill: {skill.ID}");
Console.WriteLine($"Latest version: {skill.LatestVersionID}");
Console.WriteLine($"Created skill 2: {skill2.ID}");
```
```go Go
client := anthropic.NewClient()
// Opzione 1: usare un file zip
zipFile, err := os.Open("example_skill.zip")
if err != nil {
log.Fatal(err)
}
defer zipFile.Close()
skill, err := client.Skills.New(context.TODO(), anthropic.SkillNewParams{
Files: []io.Reader{zipFile},
})
if err != nil {
log.Fatal(err)
}
// Opzione 2: usare file singoli
skillMd, err := os.Open("financial_skill/SKILL.md")
if err != nil {
log.Fatal(err)
}
defer skillMd.Close()
analyzePy, err := os.Open("financial_skill/analyze.py")
if err != nil {
log.Fatal(err)
}
defer analyzePy.Close()
skill2, err := client.Skills.New(context.TODO(), anthropic.SkillNewParams{
Files: []io.Reader{
anthropic.File(skillMd, "financial_skill/SKILL.md", "text/markdown"),
anthropic.File(analyzePy, "financial_skill/analyze.py", "text/x-python"),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Created skill: %s\n", skill.ID)
fmt.Printf("Latest version: %s\n", skill.LatestVersionID)
fmt.Printf("Created skill 2: %s\n", skill2.ID)
```
```java Java
import com.anthropic.core.MultipartField;
import com.anthropic.models.skills.SkillCreateParams;
import com.anthropic.models.skills.Skill;
// ...
void main() throws Exception {
// ...
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Opzione 1: utilizzo di un file zip
SkillCreateParams params = SkillCreateParams.builder()
.addFile(MultipartField.builder()
.value(Files.newInputStream(Path.of("example_skill.zip")))
.filename("example_skill.zip")
.contentType("application/zip")
.build())
.build();
Skill skill = client.skills().create(params);
// Opzione 2: utilizzo di file singoli (i nomi di file con percorso preservano la struttura delle directory della Skill)
SkillCreateParams params2 = SkillCreateParams.builder()
.addFile(MultipartField.builder()
.value(Files.newInputStream(Path.of("financial_skill/SKILL.md")))
.filename("financial_skill/SKILL.md")
.contentType("text/markdown")
.build())
.addFile(MultipartField.builder()
.value(Files.newInputStream(Path.of("financial_skill/analyze.py")))
.filename("financial_skill/analyze.py")
.contentType("text/x-python")
.build())
.build();
Skill skill2 = client.skills().create(params2);
System.out.println("Created skill: " + skill.id());
System.out.println("Latest version: " + skill.latestVersionId());
System.out.println("Created skill 2: " + skill2.id());
}
```
```php PHP
use Anthropic\Core\FileParam;
// ...
$client = new Client();
// Opzione 1: utilizzo di un file zip
$skill = $client->skills->create(
files: [
FileParam::fromResource(fopen('example_skill.zip', 'r')),
],
);
// Opzione 2: utilizzo di file singoli
$skill = $client->skills->create(
files: [
FileParam::fromResource(
fopen('financial_skill/SKILL.md', 'r'),
filename: 'financial_skill/SKILL.md',
contentType: 'text/markdown',
),
FileParam::fromResource(
fopen('financial_skill/analyze.py', 'r'),
filename: 'financial_skill/analyze.py',
contentType: 'text/x-python',
),
],
);
echo "Created skill: {$skill->id}\n";
echo "Latest version: {$skill->latestVersionID}\n";
```
```ruby Ruby
client = Anthropic::Client.new
# Opzione 1: utilizzo di un file zip
skill = client.skills.create(
files: [
File.open("example_skill.zip", "rb")
]
)
# Opzione 2: utilizzo di file singoli
skill = client.skills.create(
files: [
Anthropic::FilePart.new(
Pathname("financial_skill/SKILL.md"),
filename: "financial_skill/SKILL.md",
content_type: "text/markdown"
),
Anthropic::FilePart.new(
Pathname("financial_skill/analyze.py"),
filename: "financial_skill/analyze.py",
content_type: "text/x-python"
)
]
)
puts "Created skill: #{skill.id}"
puts "Latest version: #{skill.latest_version_id}"
```
**Requisiti:**
* Deve includere un file `SKILL.md` alla radice del caricamento (o al livello superiore di una singola cartella contenitore)
* `display_name` è opzionale: se omesso, viene derivato dal `name` di `SKILL.md`; un valore esplicito può avere fino a 255 caratteri e non deve essere univoco all'interno del workspace
* La dimensione totale del caricamento deve essere inferiore a 30 MB (non compressa)
* Requisiti del frontmatter YAML:
* `name`: massimo 64 caratteri, solo lettere minuscole/numeri/trattini, nessun tag XML, nessuna parola riservata ("anthropic", "claude")
* `description`: massimo 1024 caratteri, non vuoto, nessun tag XML
Per gli schemi completi di richiesta/risposta, consulta il [riferimento API Create Skill](https://platform.claude.com/docs/it/api/skills/create).
### Elencare le Skills
Recupera tutte le Skills disponibili per il tuo workspace, incluse sia le Skills predefinite di Anthropic sia le tue Skills personalizzate. Usa il parametro `source` per filtrare per tipo di skill:
```bash cURL
# Elenca tutte le Skills
curl "https://api.anthropic.com/v1/skills" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01"
# Elenca solo le Skills personalizzate
curl "https://api.anthropic.com/v1/skills?source=custom" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01"
```
```bash CLI
# Elenca tutte le Skill
ant skills list
# Elenca solo le Skill personalizzate
ant skills list --source custom
```
```python Python
client = anthropic.Anthropic()
# Elenca tutte le Skill
for skill in client.skills.list():
print(f"{skill.id}: {skill.display_name} (source: {skill.source.type})")
# Elenca solo le Skill personalizzate
custom_skills = client.skills.list(source="custom")
```
```typescript TypeScript
const client = new Anthropic();
// Elenca tutte le Skill
for await (const skill of client.skills.list()) {
console.log(`${skill.id}: ${skill.display_name} (source: ${skill.source.type})`);
}
// Elenca solo le Skill personalizzate
const customSkills = await client.skills.list({
source: "custom"
});
```
```csharp C#
AnthropicClient client = new();
// Elenca tutte le Skill
await foreach (var skill in (await client.Skills.List()).Paginate())
{
Console.WriteLine($"{skill.ID}: {skill.DisplayName} (source: {skill.Source.Type})");
}
// Elenca solo le Skill personalizzate
var customSkills = await client.Skills.List(new SkillListParams { Source = "custom" });
```
```go Go
client := anthropic.NewClient()
// Elenca tutte le Skill
skills := client.Skills.ListAutoPaging(context.TODO(), anthropic.SkillListParams{})
for skills.Next() {
skill := skills.Current()
fmt.Printf("%s: %s (source: %s)\n", skill.ID, skill.DisplayName, skill.Source.Type)
}
if skills.Err() != nil {
log.Fatal(skills.Err())
}
// Elenca solo le Skill personalizzate
customSkills := client.Skills.ListAutoPaging(context.TODO(), anthropic.SkillListParams{
Source: anthropic.String("custom"),
})
for customSkills.Next() {
skill := customSkills.Current()
fmt.Printf("%s: %s (source: %s)\n", skill.ID, skill.DisplayName, skill.Source.Type)
}
if customSkills.Err() != nil {
log.Fatal(customSkills.Err())
}
```
```java Java
import com.anthropic.models.skills.SkillListParams;
import com.anthropic.models.skills.SkillListPage;
import com.anthropic.models.skills.Skill;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Elenca le Skill (prima pagina)
SkillListPage skills = client.skills().list();
for (Skill skill : skills.data()) {
System.out.println(skill.id() + ": " + skill.displayName() + " (source: " + skill.source().type() + ")");
}
// Elenca solo le Skill personalizzate
SkillListParams customParams = SkillListParams.builder()
.source("custom")
.build();
SkillListPage customSkills = client.skills().list(customParams);
}
```
```php PHP
$client = new Client();
// Elenca le Skill (prima pagina)
foreach ($client->skills->list()->getItems() as $skill) {
echo "{$skill->id}: {$skill->displayName} (source: {$skill->source->type})\n";
}
// Elenca solo le Skill personalizzate
$customSkills = $client->skills->list(
source: 'custom',
);
```
```ruby Ruby
client = Anthropic::Client.new
# Elenca tutte le Skill
client.skills.list.auto_paging_each do |skill|
puts "#{skill.id}: #{skill.display_name} (source: #{skill.source.type})"
end
# Elenca solo le Skill personalizzate
custom_skills = client.skills.list(
source: "custom"
)
```
Consulta il [riferimento API List Skills](https://platform.claude.com/docs/it/api/skills/list) per le opzioni di paginazione e filtro.
### Recuperare una Skill
Ottieni i dettagli di una Skill specifica:
```bash cURL
curl "https://api.anthropic.com/v1/skills/skill_01AbCdEfGhIjKlMnOpQrStUv" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01"
```
```bash CLI
ant skills retrieve --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv
```
```python Python
client = anthropic.Anthropic()
skill = client.skills.retrieve(skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv")
print(f"Skill: {skill.display_name}")
print(f"Latest version: {skill.latest_version_id}")
print(f"Created: {skill.created_at}")
```
```typescript TypeScript
const client = new Anthropic();
const skill = await client.skills.retrieve("skill_01AbCdEfGhIjKlMnOpQrStUv");
console.log(`Skill: ${skill.display_name}`);
console.log(`Latest version: ${skill.latest_version_id}`);
console.log(`Created: ${skill.created_at}`);
```
```csharp C#
AnthropicClient client = new();
var skill = await client.Skills.Retrieve("skill_01AbCdEfGhIjKlMnOpQrStUv");
Console.WriteLine($"Skill: {skill.DisplayName}");
Console.WriteLine($"Latest version: {skill.LatestVersionID}");
Console.WriteLine($"Created: {skill.CreatedAt}");
```
```go Go
client := anthropic.NewClient()
skill, err := client.Skills.Get(
context.TODO(),
"skill_01AbCdEfGhIjKlMnOpQrStUv",
anthropic.SkillGetParams{},
)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Skill: %s\n", skill.DisplayName)
fmt.Printf("Latest version: %s\n", skill.LatestVersionID)
fmt.Printf("Created: %s\n", skill.CreatedAt)
```
```java Java
import com.anthropic.models.skills.Skill;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
Skill skill = client.skills().retrieve("skill_01AbCdEfGhIjKlMnOpQrStUv");
System.out.println("Skill: " + skill.displayName());
System.out.println("Latest version: " + skill.latestVersionId());
System.out.println("Created: " + skill.createdAt());
}
```
```php PHP
$client = new Client();
$skill = $client->skills->retrieve('skill_01AbCdEfGhIjKlMnOpQrStUv');
echo "Skill: {$skill->displayName}\n";
echo "Latest version: {$skill->latestVersionID}\n";
echo "Created: {$skill->createdAt->format(DATE_ATOM)}\n";
```
```ruby Ruby
client = Anthropic::Client.new
skill = client.skills.retrieve("skill_01AbCdEfGhIjKlMnOpQrStUv")
puts "Skill: #{skill.display_name}"
puts "Latest version: #{skill.latest_version_id}"
puts "Created: #{skill.created_at}"
```
### Eliminare una Skill
L'eliminazione di una Skill rimuove anche tutte le sue versioni.
```bash cURL
curl -X DELETE "https://api.anthropic.com/v1/skills/skill_01AbCdEfGhIjKlMnOpQrStUv" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01"
```
```bash CLI
ant skills delete --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null
```
```python Python
client = anthropic.Anthropic()
client.skills.delete(skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv")
```
```typescript TypeScript
const client = new Anthropic();
await client.skills.delete("skill_01AbCdEfGhIjKlMnOpQrStUv");
```
```csharp C#
AnthropicClient client = new();
await client.Skills.Delete("skill_01AbCdEfGhIjKlMnOpQrStUv");
```
```go Go
client := anthropic.NewClient()
_, err := client.Skills.Delete(
context.TODO(),
"skill_01AbCdEfGhIjKlMnOpQrStUv",
anthropic.SkillDeleteParams{},
)
if err != nil {
log.Fatal(err)
}
```
```java Java
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
client.skills().delete("skill_01AbCdEfGhIjKlMnOpQrStUv");
}
```
```php PHP
$client = new Client();
$client->skills->delete('skill_01AbCdEfGhIjKlMnOpQrStUv');
```
```ruby Ruby
client = Anthropic::Client.new
client.skills.delete("skill_01AbCdEfGhIjKlMnOpQrStUv")
```
### Versionamento
Le Skills supportano il versionamento per gestire gli aggiornamenti in sicurezza:
**Skills di Anthropic:**
* Le versioni usano il formato data: `20251013`
* Nuove versioni rilasciate man mano che vengono apportati aggiornamenti
* Specifica versioni esatte per la stabilità
**Skills personalizzate:**
* ID di versione generati automaticamente: `skver_01AbCdEfGhIjKlMnOpQrStUv`
* Usa `"latest"` per ottenere sempre la versione più recente
* Crea nuove versioni quando aggiorni i file della Skill
Una nuova versione è uno snapshot completo, non un delta: carica ogni volta l'intero set di file della Skill. I file che ometti non vengono riportati, e il `name` nel `SKILL.md` della nuova versione deve corrispondere al nome esistente della Skill. Gli esempi seguenti ricaricano il bundle completo `financial_skill/` da [Creare una Skill](https://platform.claude.com/docs/it/build-with-claude/skills-guide#creating-a-skill).
```bash cURL
# Crea una nuova versione
NEW_VERSION=$(curl -X POST "https://api.anthropic.com/v1/skills/skill_01AbCdEfGhIjKlMnOpQrStUv/versions" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-F "files[]=@financial_skill/SKILL.md;filename=financial_skill/SKILL.md" \
-F "files[]=@financial_skill/analyze.py;filename=financial_skill/analyze.py")
VERSION_ID=$(echo "$NEW_VERSION" | jq -r '.id')
# Usa una versione specifica
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d "{
\"model\": \"claude-opus-5-5\",
\"max_tokens\": 4096,
\"container\": {
\"skills\": [{
\"type\": \"custom\",
\"skill_id\": \"skill_01AbCdEfGhIjKlMnOpQrStUv\",
\"version\": \"$VERSION_ID\"
}]
},
\"messages\": [{\"role\": \"user\", \"content\": \"Use updated Skill\"}],
\"tools\": [{\"type\": \"code_execution_20250825\", \"name\": \"code_execution\"}]
}"
# Usa l'ultima versione
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"container": {
"skills": [{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest"
}]
},
"messages": [{"role": "user", "content": "Use latest Skill version"}],
"tools": [{"type": "code_execution_20250825", "name": "code_execution"}]
}'
```
```bash CLI
# Crea una nuova versione
VERSION_ID=$(ant skills:versions create \
--skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
--file financial_skill.zip \
--transform id \
--raw-output)
# Usa una versione specifica
ant messages create <builder()
.value(Files.newInputStream(Path.of("financial_skill.zip")))
.filename("financial_skill.zip")
.contentType("application/zip")
.build())
.build();
SkillVersion newVersion = client.skills().versions()
.create("skill_01AbCdEfGhIjKlMnOpQrStUv", versionParams);
// Usa una versione specifica
MessageCreateParams specificVersionParams = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.container(ContainerParams.builder()
.addSkill(SkillParams.builder()
.type(SkillParams.Type.CUSTOM)
.skillId("skill_01AbCdEfGhIjKlMnOpQrStUv")
.version(newVersion.id())
.build())
.build())
.addUserMessage("Use updated Skill")
.addTool(CodeExecutionTool20250825.builder().build())
.build();
Message response = client.messages().create(specificVersionParams);
System.out.println(response);
// Usa la versione più recente
MessageCreateParams latestVersionParams = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.container(ContainerParams.builder()
.addSkill(SkillParams.builder()
.type(SkillParams.Type.CUSTOM)
.skillId("skill_01AbCdEfGhIjKlMnOpQrStUv")
.version("latest")
.build())
.build())
.addUserMessage("Use latest Skill version")
.addTool(CodeExecutionTool20250825.builder().build())
.build();
Message latestResponse = client.messages().create(latestVersionParams);
System.out.println(latestResponse);
```
```php PHP
use Anthropic\Core\FileParam;
// ...
$client = new Client();
// Crea una nuova versione
$newVersion = $client->skills->versions->create(
skillID: 'skill_01AbCdEfGhIjKlMnOpQrStUv',
files: [
FileParam::fromResource(
fopen('financial_skill/SKILL.md', 'r'),
filename: 'financial_skill/SKILL.md',
contentType: 'text/markdown',
),
FileParam::fromResource(
fopen('financial_skill/analyze.py', 'r'),
filename: 'financial_skill/analyze.py',
contentType: 'text/x-python',
),
],
);
// Usa una versione specifica
$response = $client->messages->create(
maxTokens: 4096,
messages: [['role' => 'user', 'content' => 'Use updated Skill']],
model: 'claude-opus-5-5',
container: [
'skills' => [[
'type' => 'custom',
'skillID' => 'skill_01AbCdEfGhIjKlMnOpQrStUv',
'version' => $newVersion->id
]]
],
tools: [['type' => 'code_execution_20250825', 'name' => 'code_execution']]
);
echo $response;
// Usa l'ultima versione
$latestResponse = $client->messages->create(
maxTokens: 4096,
messages: [['role' => 'user', 'content' => 'Use latest Skill version']],
model: 'claude-opus-5-5',
container: [
'skills' => [[
'type' => 'custom',
'skillID' => 'skill_01AbCdEfGhIjKlMnOpQrStUv',
'version' => 'latest'
]]
],
tools: [['type' => 'code_execution_20250825', 'name' => 'code_execution']]
);
echo $latestResponse;
```
```ruby Ruby
client = Anthropic::Client.new
# Crea una nuova versione
new_version = client.skills.versions.create(
"skill_01AbCdEfGhIjKlMnOpQrStUv",
files: [
Anthropic::FilePart.new(
Pathname("financial_skill/SKILL.md"),
filename: "financial_skill/SKILL.md",
content_type: "text/markdown"
),
Anthropic::FilePart.new(
Pathname("financial_skill/analyze.py"),
filename: "financial_skill/analyze.py",
content_type: "text/x-python"
)
]
)
# Usa una versione specifica
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
skills: [{
type: "custom",
skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv",
version: new_version.id
}]
},
messages: [{ role: "user", content: "Use updated Skill" }],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
)
puts response
# Usa la versione più recente
latest_response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
skills: [{
type: "custom",
skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv",
version: "latest"
}]
},
messages: [{ role: "user", content: "Use latest Skill version" }],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
)
puts latest_response
```
Consulta il [riferimento API Create Skill Version](https://platform.claude.com/docs/it/api/skills/versions/create) per i dettagli completi.
***
## Come vengono caricate le Skills
Quando specifichi Skills in un container:
1. **Individuazione dei metadati:** Claude vede i metadati di ogni Skill (nome, descrizione) nel prompt di sistema.
2. **Caricamento dei file:** i file della Skill vengono copiati nel container in `/skills/{skill-name}/`. La directory è il nome della Skill (`pptx` per una Skill di Anthropic, il `name` di `SKILL.md` per una Skill personalizzata), non il suo ID `skill_01...`.
3. **Uso automatico:** Claude carica e usa automaticamente le Skills quando sono pertinenti alla tua richiesta.
4. **Composizione:** più Skills si compongono insieme per flussi di lavoro complessi.
Claude carica le istruzioni complete della Skill solo quando necessario.
***
## Casi d'uso
Le Skills si adattano sia al lavoro organizzativo sia a quello personale. Le organizzazioni le usano per applicare la formattazione del brand ai documenti, strutturare note e report secondo i template aziendali ed eseguire procedure analitiche specifiche dell'azienda. I singoli le usano per template di documenti personalizzati, pipeline di dati specializzate e convenzioni di generazione del codice o di deployment.
### Esempio: modellazione finanziaria
Combina la Skill Excel con una Skill personalizzata di analisi DCF. Per prima cosa, crea la Skill personalizzata di analisi DCF:
```bash cURL
curl -X POST "https://api.anthropic.com/v1/skills" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-F "files[]=@dcf_skill/SKILL.md;filename=dcf_skill/SKILL.md"
```
```bash CLI
ant apply dcf_skill
```
```python Python
from anthropic.lib import files_from_dir
client = anthropic.Anthropic()
dcf_skill = client.skills.create(
files=files_from_dir("/path/to/dcf_skill"),
)
print(dcf_skill.id)
```
```typescript TypeScript
import Anthropic, { toFile } from "@anthropic-ai/sdk";
import fs from "node:fs";
const client = new Anthropic();
const dcfSkill = await client.skills.create({
files: [await toFile(fs.createReadStream("dcf_skill.zip"), "dcf_skill.zip")]
});
console.log(dcfSkill.id);
```
```csharp C#
using Anthropic.Core;
// ...
AnthropicClient client = new();
var dcfSkill = await client.Skills.Create(new SkillCreateParams
{
Files =
[
new BinaryContent
{
Stream = File.OpenRead("dcf_skill/SKILL.md"),
FileName = "dcf_skill/SKILL.md",
},
],
});
Console.WriteLine(dcfSkill.ID);
```
```go Go
client := anthropic.NewClient()
skillMd, err := os.Open("dcf_skill/SKILL.md")
if err != nil {
log.Fatal(err)
}
defer skillMd.Close()
dcfSkill, err := client.Skills.New(context.TODO(), anthropic.SkillNewParams{
Files: []io.Reader{
anthropic.File(skillMd, "dcf_skill/SKILL.md", "text/markdown"),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(dcfSkill.ID)
```
```java Java
import com.anthropic.core.MultipartField;
import com.anthropic.models.skills.SkillCreateParams;
import com.anthropic.models.skills.Skill;
// ...
void main() throws Exception {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
SkillCreateParams params = SkillCreateParams.builder()
.addFile(MultipartField.builder()
.value(Files.newInputStream(Path.of("dcf_skill/SKILL.md")))
.filename("dcf_skill/SKILL.md")
.contentType("text/markdown")
.build())
.build();
Skill dcfSkill = client.skills().create(params);
System.out.println(dcfSkill.id());
}
```
```php PHP
use Anthropic\Core\FileParam;
$client = new Client();
$dcfSkill = $client->skills->create(
files: [
FileParam::fromResource(
fopen('dcf_skill/SKILL.md', 'r'),
filename: 'dcf_skill/SKILL.md',
contentType: 'text/markdown',
),
],
);
echo "{$dcfSkill->id}\n";
```
```ruby Ruby
client = Anthropic::Client.new
dcf_skill = client.skills.create(
files: [
Anthropic::FilePart.new(
Pathname("dcf_skill/SKILL.md"),
filename: "dcf_skill/SKILL.md",
content_type: "text/markdown"
)
]
)
puts dcf_skill.id
```
Quindi usala insieme alla Skill Excel per creare un modello finanziario. Passa l'ID della Skill che hai creato come `skill_id` della Skill personalizzata:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"container": {
"skills": [
{
"type": "anthropic",
"skill_id": "xlsx",
"version": "latest"
},
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest"
}
]
},
"messages": [{
"role": "user",
"content": "Build a DCF valuation model for a SaaS company"
}],
"tools": [{
"type": "code_execution_20250825",
"name": "code_execution"
}]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-5-5
max_tokens: 4096
container:
skills:
- type: anthropic
skill_id: xlsx
version: latest
- type: custom
skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
version: latest
messages:
- role: user
content: Build a DCF valuation model for a SaaS company
tools:
- type: code_execution_20250825
name: code_execution
YAML
```
```python Python
client = anthropic.Anthropic()
# Skill personalizzata di analisi DCF (ID ottenuto dalla risposta di creazione della Skills API)
dcf_skill_id = "skill_01AbCdEfGhIjKlMnOpQrStUv"
# Usa con Excel per creare un modello finanziario
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
container={
"skills": [
{"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
{"type": "custom", "skill_id": dcf_skill_id, "version": "latest"},
]
},
messages=[
{
"role": "user",
"content": "Build a DCF valuation model for a SaaS company",
}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
print(response)
```
```typescript TypeScript
const client = new Anthropic();
// Skill personalizzata di analisi DCF (ID ottenuto dalla risposta di creazione della Skills API)
const dcfSkillId = "skill_01AbCdEfGhIjKlMnOpQrStUv";
// Usa con Excel per creare un modello finanziario
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
skills: [
{ type: "anthropic", skill_id: "xlsx", version: "latest" },
{ type: "custom", skill_id: dcfSkillId, version: "latest" }
]
},
messages: [
{
role: "user",
content: "Build a DCF valuation model for a SaaS company"
}
],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
});
console.log(response);
```
```csharp C#
AnthropicClient client = new();
// Skill personalizzata di analisi DCF (ID ottenuto dalla risposta di creazione della Skills API)
var dcfSkillId = "skill_01AbCdEfGhIjKlMnOpQrStUv";
// Usa con Excel per creare un modello finanziario
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Container = new ContainerParams
{
Skills =
[
new SkillParams
{
Type = SkillParamsType.Anthropic,
SkillID = "xlsx",
Version = "latest",
},
new SkillParams
{
Type = SkillParamsType.Custom,
SkillID = dcfSkillId,
Version = "latest",
},
],
},
Messages = [new() { Role = Role.User, Content = "Build a DCF valuation model for a SaaS company" }],
Tools = [new CodeExecutionTool20250825()],
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message);
```
```go Go
client := anthropic.NewClient()
// Skill personalizzata di analisi DCF (ID ottenuto dalla risposta di creazione della Skills API)
dcfSkillID := "skill_01AbCdEfGhIjKlMnOpQrStUv"
// Usa con Excel per creare un modello finanziario
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Container: anthropic.MessageCreateParamsContainerUnion{
OfContainers: &anthropic.ContainerParams{
Skills: []anthropic.SkillParams{
{
Type: anthropic.SkillParamsTypeAnthropic,
SkillID: "xlsx",
Version: anthropic.String("latest"),
},
{
Type: anthropic.SkillParamsTypeCustom,
SkillID: dcfSkillID,
Version: anthropic.String("latest"),
},
},
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Build a DCF valuation model for a SaaS company")),
},
Tools: []anthropic.ToolUnionParam{
{OfCodeExecutionTool20250825: &anthropic.CodeExecutionTool20250825Param{}},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
```
```java Java
import com.anthropic.models.messages.ContainerParams;
import com.anthropic.models.messages.SkillParams;
import com.anthropic.models.messages.CodeExecutionTool20250825;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Skill personalizzata di analisi DCF (ID ottenuto dalla risposta di creazione della Skills API)
String dcfSkillId = "skill_01AbCdEfGhIjKlMnOpQrStUv";
// Usa con la Skill Excel per creare un modello finanziario
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.container(ContainerParams.builder()
.skills(List.of(
SkillParams.builder()
.type(SkillParams.Type.ANTHROPIC)
.skillId("xlsx")
.version("latest")
.build(),
SkillParams.builder()
.type(SkillParams.Type.CUSTOM)
.skillId(dcfSkillId)
.version("latest")
.build()
))
.build())
.addUserMessage("Build a DCF valuation model for a SaaS company")
.addTool(CodeExecutionTool20250825.builder().build())
.build();
Message response = client.messages().create(params);
System.out.println(response);
}
```
```php PHP
$client = new Client();
// Skill personalizzata di analisi DCF (ID ottenuto dalla risposta di creazione della Skills API)
$dcfSkillId = 'skill_01AbCdEfGhIjKlMnOpQrStUv';
// Usa con Excel per creare un modello finanziario
$message = $client->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => 'Build a DCF valuation model for a SaaS company']
],
model: 'claude-opus-5-5',
container: [
'skills' => [
['type' => 'anthropic', 'skillID' => 'xlsx', 'version' => 'latest'],
['type' => 'custom', 'skillID' => $dcfSkillId, 'version' => 'latest']
]
],
tools: [
['type' => 'code_execution_20250825', 'name' => 'code_execution']
]
);
echo $message;
```
```ruby Ruby
client = Anthropic::Client.new
# Skill personalizzata di analisi DCF (ID ottenuto dalla risposta di creazione della Skills API)
dcf_skill_id = "skill_01AbCdEfGhIjKlMnOpQrStUv"
# Usala con Excel per creare un modello finanziario
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
skills: [
{ type: "anthropic", skill_id: "xlsx", version: "latest" },
{ type: "custom", skill_id: dcf_skill_id, version: "latest" }
]
},
messages: [
{ role: "user", content: "Build a DCF valuation model for a SaaS company" }
],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
)
puts response
```
***
## Limiti e vincoli
### Limiti delle richieste
* **Numero massimo di Skills per richiesta:** 20
* **Dimensione massima di caricamento di una Skill:** 30 MB (tutti i file combinati, non compressi)
* **Requisiti del frontmatter YAML:**
* `name`: massimo 64 caratteri, solo lettere minuscole/numeri/trattini, nessun tag XML, nessuna parola riservata ("anthropic", "claude")
* `description`: massimo 1024 caratteri, non vuoto, nessun tag XML
### Vincoli dell'ambiente
Le Skills vengono eseguite nel container di esecuzione del codice con queste limitazioni:
* **Nessun accesso alla rete:** non è possibile effettuare chiamate API esterne
* **Nessuna installazione di pacchetti a runtime:** sono disponibili solo i pacchetti preinstallati
* **Ambiente isolato:** viene creato un nuovo container a meno che tu non specifichi l'ID di un container esistente
Consulta [Strumento di esecuzione del codice](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool) per i pacchetti disponibili.
***
## Best practice
### Quando usare più Skills
Combina le Skills quando le attività coinvolgono più tipi di documento o domini:
**Buoni casi d'uso:**
* Analisi dei dati (Excel) + creazione di presentazioni (PowerPoint)
* Generazione di report (Word) + esportazione in PDF
* Logica di dominio personalizzata + generazione di documenti
**Da evitare:**
* Includere Skills non utilizzate (influisce sulle prestazioni)
### Strategia di gestione delle versioni
Le schede SDK in questa sezione mostrano il valore `container` da includere in una richiesta Messages. Le schede cURL e CLI mostrano la richiesta completa.
**Per la produzione:** fissa una versione specifica, in modo che gli aggiornamenti delle Skills non modifichino mai il comportamento distribuito. Se ometti `version` o lo imposti su `"latest"`, le richieste usano la versione più recente della Skill, quindi una versione caricata da chiunque nel [workspace](https://platform.claude.com/docs/it/build-with-claude/skills-guide#workspace-scoped-access) cambia immediatamente ciò che eseguono i tuoi agenti in produzione. L'ID di versione proviene dalla risposta di creazione della versione in [Versionamento](https://platform.claude.com/docs/it/build-with-claude/skills-guide#versioning) o dalla [List Skill Versions API](https://platform.claude.com/docs/it/api/skills/versions/list). L'ID è sempre una stringa, quindi racchiudilo tra virgolette in JSON o YAML anche quando sembra numerico.
```bash cURL
# Fissa versioni specifiche per garantire la stabilità
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"container": {
"skills": [{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "skver_01AbCdEfGhIjKlMnOpQrStUv"
}]
},
"messages": [{"role": "user", "content": "Analyze the sales data"}],
"tools": [{"type": "code_execution_20250825", "name": "code_execution"}]
}'
```
```bash CLI
# Fissa versioni specifiche per garantire la stabilità
ant messages create < [[
'type' => 'custom',
'skillID' => 'skill_01AbCdEfGhIjKlMnOpQrStUv',
'version' => 'skver_01AbCdEfGhIjKlMnOpQrStUv'
]]
];
```
```ruby Ruby
# Fissa versioni specifiche per garantire la stabilità
container = {
skills: [{
type: "custom",
skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv",
version: "skver_01AbCdEfGhIjKlMnOpQrStUv"
}]
}
```
**Per lo sviluppo:** usa `latest` per ottenere automaticamente la versione più recente mentre iteri.
```bash cURL
# Usa latest per lo sviluppo attivo
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"container": {
"skills": [{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest"
}]
},
"messages": [{"role": "user", "content": "Analyze the sales data"}],
"tools": [{"type": "code_execution_20250825", "name": "code_execution"}]
}'
```
```bash CLI
# Usa latest per lo sviluppo attivo
ant messages create < [[
'type' => 'custom',
'skillID' => 'skill_01AbCdEfGhIjKlMnOpQrStUv',
'version' => 'latest'
]]
];
```
```ruby Ruby
# Usa latest per lo sviluppo attivo
container = {
skills: [{
type: "custom",
skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv",
version: "latest"
}]
}
```
### Considerazioni sulla cache dei prompt
Se usi la [cache dei prompt](https://platform.claude.com/docs/it/build-with-claude/prompt-caching) ("prompt caching"), modificare l'elenco delle Skills nel tuo container invalida la cache. Le Skills vengono rese nel prompt di sistema in un ordine fisso, quindi lo stesso elenco produce lo stesso prefisso memorizzabile in cache:
```bash cURL
# Le Skills vengono inserite nel prompt di sistema in un ordine fisso e favorevole alla cache
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"container": {
"skills": [
{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}
]
},
"messages": [{"role": "user", "content": "Analyze sales data"}],
"tools": [{"type": "code_execution_20250825", "name": "code_execution"}]
}'
# Modificare l'elenco delle Skills ([xlsx] vs [xlsx, pptx]) cambia il prefisso: cache miss, mentre un elenco identico è un cache hit
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"container": {
"skills": [
{"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
{"type": "anthropic", "skill_id": "pptx", "version": "latest"}
]
},
"messages": [{"role": "user", "content": "Create a presentation"}],
"tools": [{"type": "code_execution_20250825", "name": "code_execution"}]
}'
```
```bash CLI
# Le Skills vengono inserite nel prompt di sistema in un ordine fisso e adatto alla cache
ant messages create <<'YAML'
model: claude-opus-5-5
max_tokens: 4096
container:
skills:
- type: anthropic
skill_id: xlsx
version: latest
messages:
- role: user
content: Analyze sales data
tools:
- type: code_execution_20250825
name: code_execution
YAML
# Modificare l'elenco delle Skills ([xlsx] vs [xlsx, pptx]) cambia il prefisso: cache miss, mentre un elenco identico è un cache hit
ant messages create <<'YAML'
model: claude-opus-5-5
max_tokens: 4096
container:
skills:
- type: anthropic
skill_id: xlsx
version: latest
- type: anthropic
skill_id: pptx
version: latest
messages:
- role: user
content: Create a presentation
tools:
- type: code_execution_20250825
name: code_execution
YAML
```
```python Python
client = anthropic.Anthropic()
# Le Skills vengono inserite nel prompt di sistema in un ordine fisso e adatto alla cache
response1 = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
container={
"skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
},
messages=[{"role": "user", "content": "Analyze sales data"}],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
# Modificare l'elenco delle Skills ([xlsx] vs [xlsx, pptx]) cambia il prefisso: cache miss, mentre un elenco identico è un cache hit
response2 = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
container={
"skills": [
{"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
{
"type": "anthropic",
"skill_id": "pptx",
"version": "latest",
}, # prefix change: cache miss
]
},
messages=[{"role": "user", "content": "Create a presentation"}],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
```
```typescript TypeScript
const client = new Anthropic();
// Le Skills vengono inserite nel prompt di sistema in un ordine fisso e favorevole alla cache
const response1 = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
skills: [{ type: "anthropic", skill_id: "xlsx", version: "latest" }]
},
messages: [{ role: "user", content: "Analyze sales data" }],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
});
// Modificare l'elenco delle Skills ([xlsx] vs [xlsx, pptx]) cambia il prefisso: cache miss, mentre un elenco identico dà un cache hit
const response2 = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
skills: [
{ type: "anthropic", skill_id: "xlsx", version: "latest" },
{ type: "anthropic", skill_id: "pptx", version: "latest" } // prefix change: cache miss
]
},
messages: [{ role: "user", content: "Create a presentation" }],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
});
```
```csharp C#
AnthropicClient client = new();
// Le Skill vengono inserite nel prompt di sistema in un ordine fisso e favorevole alla cache
var parameters1 = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Container = new ContainerParams
{
Skills =
[
new SkillParams
{
Type = SkillParamsType.Anthropic,
SkillID = "xlsx",
Version = "latest",
},
],
},
Messages = [new() { Role = Role.User, Content = "Analyze sales data" }],
Tools = [new CodeExecutionTool20250825()],
};
var response1 = await client.Messages.Create(parameters1);
Console.WriteLine(response1);
// Un set di Skill diverso ([xlsx] vs [xlsx, pptx]) = un prefisso diverso: cache miss (un set identico è un cache hit)
var parameters2 = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Container = new ContainerParams
{
Skills =
[
new SkillParams
{
Type = SkillParamsType.Anthropic,
SkillID = "xlsx",
Version = "latest",
},
new SkillParams
{
Type = SkillParamsType.Anthropic,
SkillID = "pptx",
Version = "latest",
},
],
},
Messages = [new() { Role = Role.User, Content = "Create a presentation" }],
Tools = [new CodeExecutionTool20250825()],
};
var response2 = await client.Messages.Create(parameters2);
Console.WriteLine(response2);
```
```go Go
client := anthropic.NewClient()
// Le Skills vengono inserite nel prompt di sistema in un ordine fisso e favorevole alla cache
response1, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Container: anthropic.MessageCreateParamsContainerUnion{
OfContainers: &anthropic.ContainerParams{
Skills: []anthropic.SkillParams{
{
Type: anthropic.SkillParamsTypeAnthropic,
SkillID: "xlsx",
Version: anthropic.String("latest"),
},
},
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze sales data")),
},
Tools: []anthropic.ToolUnionParam{
{OfCodeExecutionTool20250825: &anthropic.CodeExecutionTool20250825Param{}},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response1)
// Modificare l'elenco delle Skills ([xlsx] vs [xlsx, pptx]) cambia il prefisso: cache miss, mentre un elenco identico è un cache hit
response2, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Container: anthropic.MessageCreateParamsContainerUnion{
OfContainers: &anthropic.ContainerParams{
Skills: []anthropic.SkillParams{
{
Type: anthropic.SkillParamsTypeAnthropic,
SkillID: "xlsx",
Version: anthropic.String("latest"),
},
{
Type: anthropic.SkillParamsTypeAnthropic,
SkillID: "pptx",
Version: anthropic.String("latest"),
},
},
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Create a presentation")),
},
Tools: []anthropic.ToolUnionParam{
{OfCodeExecutionTool20250825: &anthropic.CodeExecutionTool20250825Param{}},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response2)
```
```java Java
import com.anthropic.models.messages.ContainerParams;
import com.anthropic.models.messages.SkillParams;
import com.anthropic.models.messages.CodeExecutionTool20250825;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Le Skills vengono inserite nel prompt di sistema in un ordine fisso e favorevole alla cache
MessageCreateParams params1 = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.container(ContainerParams.builder()
.skills(List.of(
SkillParams.builder()
.type(SkillParams.Type.ANTHROPIC)
.skillId("xlsx")
.version("latest")
.build()
))
.build())
.addUserMessage("Analyze sales data")
.addTool(CodeExecutionTool20250825.builder().build())
.build();
Message response1 = client.messages().create(params1);
System.out.println(response1);
// Modificare l'elenco delle Skills ([xlsx] vs [xlsx, pptx]) cambia il prefisso: cache miss, mentre un elenco identico dà un cache hit
MessageCreateParams params2 = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.container(ContainerParams.builder()
.skills(List.of(
SkillParams.builder()
.type(SkillParams.Type.ANTHROPIC)
.skillId("xlsx")
.version("latest")
.build(),
SkillParams.builder()
.type(SkillParams.Type.ANTHROPIC)
.skillId("pptx")
.version("latest")
.build()
))
.build())
.addUserMessage("Create a presentation")
.addTool(CodeExecutionTool20250825.builder().build())
.build();
Message response2 = client.messages().create(params2);
System.out.println(response2);
}
```
```php PHP
$client = new Client();
// Le Skills vengono inserite nel prompt di sistema in un ordine fisso e favorevole alla cache
$response1 = $client->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => 'Analyze sales data']
],
model: 'claude-opus-5-5',
container: [
'skills' => [
['type' => 'anthropic', 'skillID' => 'xlsx', 'version' => 'latest']
]
],
tools: [
['type' => 'code_execution_20250825', 'name' => 'code_execution']
]
);
echo $response1;
// Modificare l'elenco delle Skills ([xlsx] vs [xlsx, pptx]) cambia il prefisso: cache miss, mentre un elenco identico è un cache hit
$response2 = $client->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => 'Create a presentation']
],
model: 'claude-opus-5-5',
container: [
'skills' => [
['type' => 'anthropic', 'skillID' => 'xlsx', 'version' => 'latest'],
['type' => 'anthropic', 'skillID' => 'pptx', 'version' => 'latest']
]
],
tools: [
['type' => 'code_execution_20250825', 'name' => 'code_execution']
]
);
echo $response2;
```
```ruby Ruby
client = Anthropic::Client.new
# Le Skills vengono inserite nel prompt di sistema in un ordine fisso, adatto alla cache
response1 = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
skills: [{ type: "anthropic", skill_id: "xlsx", version: "latest" }]
},
messages: [{ role: "user", content: "Analyze sales data" }],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
)
puts response1
# Modificare l'elenco delle Skills ([xlsx] vs [xlsx, pptx]) cambia il prefisso: cache miss, mentre un elenco identico è un cache hit
response2 = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
skills: [
{ type: "anthropic", skill_id: "xlsx", version: "latest" },
{ type: "anthropic", skill_id: "pptx", version: "latest" } # prefix change: cache miss
]
},
messages: [{ role: "user", content: "Create a presentation" }],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
)
puts response2
```
Per le migliori prestazioni di caching, mantieni coerente tra le richieste il tuo elenco di Skills, incluso il suo ordine. Anche fissare le versioni delle Skills personalizzate aiuta: con `"latest"`, la pubblicazione di una nuova versione può invalidare il prefisso in cache se modifica la descrizione della Skill.
### Gestione degli errori
Gestisci con eleganza gli errori relativi alle Skills:
Questo flusso di gestione degli errori richiede più logica di un singolo comando shell, quindi usa il Claude SDK per farlo. Una richiesta che non va a buon fine a causa di un problema con una Skill restituisce HTTP 400. Il campo `error.message` nel corpo della risposta JSON descrive il problema.
```bash CLI
if ! RESULT=$(ant messages create \
--transform-error error.message \
--format-error yaml 2>&1 <<'YAML'
model: claude-opus-5-5
max_tokens: 4096
container:
skills:
- type: custom
skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
version: latest
messages:
- role: user
content: Process data
tools:
- type: code_execution_20250825
name: code_execution
YAML
); then
case "$RESULT" in
*skill*)
printf 'Skill error: %s\n' "$RESULT"
# Gestisci gli errori specifici delle skill
;;
*)
printf '%s\n' "$RESULT" >&2
exit 1
;;
esac
fi
```
```python Python
client = anthropic.Anthropic()
try:
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
container={
"skills": [
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest",
}
]
},
messages=[{"role": "user", "content": "Process data"}],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
except anthropic.BadRequestError as e:
if "skill" in str(e):
print(f"Skill error: {e}")
# Gestisci gli errori specifici delle skill
else:
raise
```
```typescript TypeScript
const client = new Anthropic();
try {
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
skills: [
{ type: "custom", skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv", version: "latest" }
]
},
messages: [{ role: "user", content: "Process data" }],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
});
console.log(response);
} catch (error) {
if (error instanceof Anthropic.BadRequestError && error.message.includes("skill")) {
console.error(`Skill error: ${error.message}`);
// Gestisci gli errori specifici delle skill
} else {
throw error;
}
}
```
```csharp C#
using Anthropic.Exceptions;
// ...
AnthropicClient client = new();
try
{
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Container = new ContainerParams
{
Skills =
[
new SkillParams
{
Type = SkillParamsType.Custom,
SkillID = "skill_01AbCdEfGhIjKlMnOpQrStUv",
Version = "latest",
},
],
},
Messages = [new() { Role = Role.User, Content = "Process data" }],
Tools = [new CodeExecutionTool20250825()],
};
var response = await client.Messages.Create(parameters);
Console.WriteLine(response);
}
catch (AnthropicBadRequestException e) when (e.Message.Contains("skill"))
{
Console.WriteLine($"Skill error: {e.Message}");
}
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Container: anthropic.MessageCreateParamsContainerUnion{
OfContainers: &anthropic.ContainerParams{
Skills: []anthropic.SkillParams{
{
Type: anthropic.SkillParamsTypeCustom,
SkillID: "skill_01AbCdEfGhIjKlMnOpQrStUv",
Version: anthropic.String("latest"),
},
},
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Process data")),
},
Tools: []anthropic.ToolUnionParam{
{OfCodeExecutionTool20250825: &anthropic.CodeExecutionTool20250825Param{}},
},
})
if err != nil {
var apierr *anthropic.Error
if errors.As(err, &apierr) && apierr.Type() == anthropic.ErrorTypeInvalidRequestError &&
strings.Contains(apierr.Error(), "skill") {
fmt.Printf("Skill error: %v\n", apierr)
} else {
log.Fatal(err)
}
return
}
fmt.Println(response)
```
```java Java
import com.anthropic.errors.BadRequestException;
import com.anthropic.models.messages.ContainerParams;
import com.anthropic.models.messages.SkillParams;
import com.anthropic.models.messages.CodeExecutionTool20250825;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
try {
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.container(ContainerParams.builder()
.addSkill(SkillParams.builder()
.type(SkillParams.Type.CUSTOM)
.skillId("skill_01AbCdEfGhIjKlMnOpQrStUv")
.version("latest")
.build())
.build())
.addUserMessage("Process data")
.addTool(CodeExecutionTool20250825.builder().build())
.build();
Message response = client.messages().create(params);
System.out.println(response);
} catch (BadRequestException e) {
if (e.getMessage().contains("skill")) {
System.err.println("Skill error: " + e.getMessage());
} else {
throw e;
}
}
}
```
```php PHP
use Anthropic\Core\Exceptions\BadRequestException;
$client = new Client();
try {
$message = $client->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => 'Process data']
],
model: 'claude-opus-5-5',
container: [
'skills' => [
[
'type' => 'custom',
'skillID' => 'skill_01AbCdEfGhIjKlMnOpQrStUv',
'version' => 'latest'
]
]
],
tools: [
['type' => 'code_execution_20250825', 'name' => 'code_execution']
]
);
echo $message;
} catch (BadRequestException $e) {
if (str_contains($e->getMessage(), 'skill')) {
echo "Skill error: " . $e->getMessage();
} else {
throw $e;
}
}
```
```ruby Ruby
client = Anthropic::Client.new
begin
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
skills: [
{
type: "custom",
skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv",
version: "latest"
}
]
},
messages: [{ role: "user", content: "Process data" }],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
)
rescue Anthropic::Errors::BadRequestError => e
if e.message.include?("skill")
puts "Skill error: #{e.message}"
else
raise
end
end
```
***
## Migrare da `skills-2025-10-02`
La Skills API è uscita dalla beta e non richiede alcun header beta. La migrazione da `skills-2025-10-02` è facoltativa: le richieste che lo inviano ancora continuano a funzionare e continuano a restituire le forme di risposta beta, quindi un'integrazione esistente continua a funzionare finché non la modifichi. Rimuovere l'header fa passare quelle richieste alle forme documentate in questa pagina:
| | Con `skills-2025-10-02` | Senza l'header |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Etichetta della Skill | `display_title` (fino a 64 caratteri, univoco per workspace) | `display_name` (fino a 255 caratteri, non univoco); derivato dal `name` di `SKILL.md` se omesso |
| Puntatore alla versione più recente | `latest_version`, una stringa in microsecondi epoch come `"1759178010641129"` | `latest_version_id`, un ID di versione come `"skver_01AbCdEfGhIjKlMnOpQrStUv"`; `GET /v1/skills/{skill_id}/versions/latest` lo risolve in una sola chiamata |
| Identificatore di versione negli URL | Stringa in microsecondi epoch | ID di versione (`skver_...`). Gli ID acquisiti durante la beta con il prefisso `skill_version_` sono accettati come input. |
| Oggetto versione | Include `directory` (sempre uguale al `name` della Skill) | Nessun campo `directory` |
| `source` | Una stringa, `"custom"` o `"anthropic"` | Un oggetto, ad esempio `{"type": "custom"}`; il valore del catalogo di esempio è `"anthropic_example"` |
| Risposte di elenco | `{ data, has_more, next_page }` | `{ data, next_page }`; `limit` da 1 a 1.000 (predefinito 20) |
| Ordine dell'elenco versioni | Dalla più vecchia | Dalla più recente, `limit` predefinito 20. I cursori di pagina di una forma non sono validi sull'altra. |
| Eliminazione di una Skill | Restituisce un errore 400 finché esiste una qualsiasi versione | Elimina la Skill e tutte le sue versioni |
| Eliminazione dell'unica versione di una Skill | Consentita, lasciando una Skill senza versioni | Restituisce un errore 400; carica prima una versione sostitutiva, oppure elimina la Skill |
| Layout del caricamento | I file devono trovarsi all'interno di una directory di primo livello il cui nome corrisponde al `name` della Skill | `SKILL.md` può trovarsi alla radice del caricamento; i percorsi memorizzati sono gli stessi in entrambi i casi |
| Tipi di risposta | `CreateSkillResponse`, `GetSkillResponse` e un tipo per operazione | `Skill`, `SkillVersion`, `DeletedSkill`, `DeletedSkillVersion` |
Per migrare:
1. **Rimuovi l'header beta.** Elimina `anthropic-beta: skills-2025-10-02` dalle tue richieste. Negli SDK, chiama `client.skills` invece di `client.beta.skills`; mantenere `client.beta.skills` funziona solo sulle [versioni degli SDK che non inviano più l'header](https://platform.claude.com/docs/it/build-with-claude/skills-guide#sdk-beta-namespace). Le versioni precedenti lo inviano da `client.beta.skills` anche senza argomento `betas`.
2. **Rinomina i campi** nel tuo codice: `display_title` in `display_name`, `latest_version` in `latest_version_id`, e leggi `source.type` invece di confrontare `source` con una stringa.
3. **Usa gli ID di versione.** Ovunque tu abbia memorizzato una versione in microsecondi epoch, memorizza invece l'`id` della versione, oppure usa `latest`. I riferimenti alle Skills nelle richieste Messages accettano un ID di versione, `latest` o (per le Skills di Anthropic) la versione del catalogo.
4. **Rivedi le chiamate di eliminazione.** `DELETE /v1/skills/{skill_id}` ora rimuove ogni versione insieme alla Skill. Se facevi affidamento sul rifiuto della beta come salvaguardia, aggiungi un tuo controllo.
Dopo la migrazione, `client.skills.delete(skill_id)` e `client.beta.skills.delete(skill_id)` eliminano la Skill insieme a tutte le sue versioni in una sola chiamata.
Una Skill le cui versioni sono state tutte eliminate durante la beta non ha una versione corrente da restituire: `GET /v1/skills/{skill_id}` restituisce un errore 400 e la Skill viene omessa dalle risposte di elenco finché non vi carichi una versione. Puoi comunque eliminarla.
### Namespace beta degli SDK
A partire da Python SDK 1.2.0, TypeScript SDK 0.122.0, Go SDK 1.68.0, Java SDK 2.59.0, Ruby SDK 1.67.0 e C# SDK 12.44.0, `client.beta.skills` non invia più `skills-2025-10-02` e restituisce le stesse forme di `client.skills`, con nomi di tipo con prefisso `Beta` (`BetaSkill`, `BetaSkillVersion`, `BetaDeletedSkill`, `BetaDeletedSkillVersion`). Accetta un argomento `betas` per le funzionalità delle Skills ancora in beta. Nei tipi beta di Messages, il tipo di riferimento alla Skill del container è rinominato da `BetaSkill` a `BetaContainerSkill` (stessi campi: `type`, `skill_id`, `version`); `BetaSkill` ora indica la risorsa Skill, in corrispondenza con `Skill` e `ContainerSkill` nei tipi non beta. Le versioni precedenti degli SDK sono tipizzate sulle forme beta; se dipendi da quei tipi, resta su una versione precedente finché non migri.
## Conservazione dei dati
Le Agent Skills non sono coperte dagli accordi ZDR. Le definizioni delle Skills e i dati di esecuzione vengono conservati secondo la politica standard di conservazione dei dati di Anthropic.
Per l'idoneità ZDR di tutte le funzionalità, consulta [API e conservazione dei dati](https://platform.claude.com/docs/it/manage-claude/api-and-data-retention).
## Registrazione di audit
Se la tua organizzazione ha abilitato la [Compliance API](https://platform.claude.com/docs/it/manage-claude/compliance-api), il suo [Activity Feed](https://platform.claude.com/docs/it/manage-claude/compliance-activity-feed) registra la creazione e l'eliminazione di Skills e versioni di Skills effettuate con una chiave API di Claude o dalla Claude Console. Le operazioni che avvengono mentre la Compliance API è disattivata non vengono registrate e non possono essere recuperate in seguito, quindi [configura la Compliance API](https://platform.claude.com/docs/it/manage-claude/compliance-api-access) prima di fare affidamento su questa traccia di audit.
## Passaggi successivi
Riferimento API completo con tutti gli endpoint
Scopri come scrivere Skills efficaci che Claude possa individuare e usare con successo.
Esegui codice Python e bash in un container sandbox per analizzare dati, generare file e iterare sulle soluzioni.