---
title: Uso de Agent Skills con la API
url: https://platform.claude.com/docs/es/build-with-claude/skills-guide
description: Aprende a usar Agent Skills para ampliar las capacidades de Claude a través de la API.
---
Las Agent Skills amplían las capacidades de Claude mediante carpetas organizadas de instrucciones, scripts y recursos. Esta guía te muestra cómo usar tanto Skills predefinidas como Skills personalizadas con la Claude API.
Para la referencia completa de la API, incluidos los esquemas de solicitud/respuesta y todos los parámetros, consulta:
* [Referencia de la API de gestión de Skills](https://platform.claude.com/docs/es/api/skills/list) - Operaciones CRUD para Skills
* [Referencia de la API de versiones de Skills](https://platform.claude.com/docs/es/api/skills/versions/list) - Gestión de versiones
Para saber cómo se aplica la "zero data retention" (retención cero de datos), o ZDR, a esta función, consulta [API y retención de datos](https://platform.claude.com/docs/es/manage-claude/api-and-data-retention).
## Enlaces rápidos
Aprende a usar Agent Skills para crear documentos con la Claude API en menos de 10 minutos.
Aprende a escribir Skills efectivas que Claude pueda descubrir y usar con éxito.
## Descripción general
Para un análisis detallado de la arquitectura y las aplicaciones reales de Agent Skills, lee la publicación del blog de ingeniería: [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills).
Las Skills se integran con la Messages API a través de la [herramienta de ejecución de código](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool). Ya sea que uses Skills predefinidas gestionadas por Anthropic o Skills personalizadas que hayas subido, la forma de integración es idéntica: ambas requieren ejecución de código y usan la misma estructura `container`.
### Uso de Skills
Las Skills se integran de forma idéntica en la Messages API independientemente de su origen. Especificas las Skills en el parámetro `container` con un `skill_id`, un `type` y una `version` opcional, y se ejecutan en el entorno de ejecución de código.
Puedes usar Skills de dos orígenes:
| Aspecto | Skills de Anthropic | Skills personalizadas |
| ---------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| **Valor de type** | `anthropic` | `custom` |
| **IDs de Skill** | Nombres cortos: `pptx`, `xlsx`, `docx`, `pdf` | Generados: `skill_01AbCdEfGhIjKlMnOpQrStUv` |
| **Formato de versión** | Basado en fecha: `20251013` o `latest` | ID de versión: `skver_01AbCdEfGhIjKlMnOpQrStUv` o `latest` |
| **Gestión** | Predefinidas y mantenidas por Anthropic | Se suben y gestionan a través de la [Skills API](https://platform.claude.com/docs/es/api/skills/create) |
| **Disponibilidad** | Disponibles para todos los usuarios | Privadas para tu workspace |
Ambos orígenes de skills son devueltos por el [endpoint List Skills](https://platform.claude.com/docs/es/api/skills/list) (usa el parámetro `source` para filtrar). La forma de integración y el entorno de ejecución son idénticos. La única diferencia es de dónde provienen las Skills y cómo se gestionan.
### Requisitos previos
Para usar Skills, necesitas:
1. **Clave de API de Claude** desde la [Claude Console](https://platform.claude.com/settings/keys)
2. **[Herramienta de ejecución de código](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool)** habilitada en tus solicitudes
Las Skills requieren la herramienta de ejecución de código, así que usa un modelo de su [lista de compatibilidad de modelos](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool#compatibility).
***
## Uso de Skills en Messages
### Parámetro container
Las Skills se especifican mediante el parámetro `container` en la Messages API. Puedes incluir hasta 20 Skills en cada solicitud.
La estructura es idéntica tanto para las Skills de Anthropic como para las personalizadas. Especifica los campos obligatorios `type` y `skill_id` y, opcionalmente, incluye `version` para fijar una versión específica:
```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
```
### Descarga de archivos generados
Cuando las Skills crean documentos (Excel, PowerPoint, PDF, Word), devuelven atributos `file_id` en la respuesta. Debes usar la Files API para descargar estos archivos.
**Cómo funciona:**
1. Las Skills crean archivos durante la ejecución de código.
2. La respuesta incluye un `file_id` para cada archivo creado, dentro de los bloques de resultado de la herramienta de ejecución de código (consulta [Formato de respuesta](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool#response-format)).
3. Usa la Files API para descargar el contenido real del archivo.
4. Guárdalo localmente o procésalo según sea necesario.
Para proporcionar archivos de entrada con los que trabajen las Skills, [súbelos con la Files API](https://platform.claude.com/docs/es/build-with-claude/files#uploading-a-file) y haz referencia a ellos en tu solicitud con un ["container upload block" (bloque de carga a contenedor)](https://platform.claude.com/docs/es/build-with-claude/files#container-upload-blocks).
**Ejemplo: crear y descargar un archivo de Excel**
```bash cURL
# Paso 1: Usa una Skill para crear un archivo
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"
}]
}')
# Paso 2: Extrae file_id de la respuesta (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')
# Paso 3: Obtén el nombre del archivo de los metadatos
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')
# Paso 4: Descarga el archivo 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
# Paso 1: Usa la Skill xlsx para crear un archivo
# Paso 2: Extrae file_id de la respuesta con --transform (ruta 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
)
# Paso 3: Obtén el nombre del archivo a partir de sus metadatos
FILENAME=$(ant files retrieve-metadata \
--file-id "$FILE_ID" \
--transform filename \
--raw-output)
# Paso 4: Descarga el archivo con la Files API
ant files download --file-id "$FILE_ID" --output "$FILENAME" > /dev/null
printf 'Downloaded: %s\n' "$FILENAME"
```
```python Python
client = anthropic.Anthropic()
# Paso 1: Usa una Skill para crear un archivo
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"}],
)
# Paso 2: Extrae los IDs de archivo de la respuesta
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":
# cada elemento de contenido es un bloque bash_code_execution_output que lleva un file_id
for file in content_item.content:
file_ids.append(file.file_id)
return file_ids
# Paso 3: Descarga el archivo con 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)
# Paso 4: Guarda en 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();
// Paso 1: Usa una Skill para crear un archivo
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" }]
});
// Paso 2: Extrae los IDs de archivo de la respuesta
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);
}
}
}
// Paso 3: Descarga cada archivo y guárdalo en 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();
// Paso 1: Usa una Skill para crear un archivo
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);
// Paso 2: Extrae los IDs de archivo de la respuesta
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);
}
}
}
// Paso 3: Descarga cada archivo y guárdalo en el 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()
// Paso 1: Usa una Skill para crear un archivo
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)
}
// Paso 2: Extrae los IDs de archivo de la respuesta
fileIDs := extractFileIDs(response)
// Paso 3: Descarga el archivo con 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)
}
// Paso 4: Guarda en el 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();
// Paso 1: Usa una Skill para crear un archivo
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);
// Paso 2: Extrae los IDs de archivo de la respuesta
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());
}
}
}
}
// Paso 3: Descarga el archivo con la Files API
for (String fileId : fileIds) {
FileMetadata fileMetadata = client.files().retrieveMetadata(fileId);
HttpResponse fileContent = client.files().download(fileId);
// Paso 4: Guarda en el 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();
// Paso 1: Usa una Skill para crear un archivo
$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']
]
);
// Paso 2: Extrae los IDs de archivo de la respuesta
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;
}
// Paso 3: Descarga el archivo con la Files API
foreach (extractFileIds($response) as $fileId) {
$fileMetadata = $client->files->retrieveMetadata($fileId);
$fileContent = $client->files->download($fileId);
// Paso 4: Guarda en el disco
file_put_contents($fileMetadata->filename, $fileContent);
echo "Downloaded: {$fileMetadata->filename}\n";
}
```
```ruby Ruby
client = Anthropic::Client.new
# Paso 1: Usa una Skill para crear un archivo
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" }]
)
# Paso 2: Extrae los ID de archivo de la respuesta
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
# Paso 3: Descarga el archivo con 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)
# Paso 4: Guarda en el disco
File.binwrite(file_metadata.filename, file_content.read)
puts "Downloaded: #{file_metadata.filename}"
end
```
**Operaciones adicionales de la Files API:**
```bash cURL
# Obtener los metadatos del archivo
curl "https://api.anthropic.com/v1/files/$FILE_ID" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01"
# Listar todos los archivos
curl "https://api.anthropic.com/v1/files" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01"
# Eliminar un archivo
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
# Obtener los metadatos del archivo
ant files retrieve-metadata \
--file-id "$FILE_ID" \
--transform '{filename,size_bytes}' \
--format yaml
# Listar todos los archivos
ant files list --transform '{filename,created_at}' --format yaml
# Eliminar un archivo
ant files delete --file-id "$FILE_ID" >/dev/null
```
```python Python
client = anthropic.Anthropic()
file_id = "file_011CNha8iCJcU1wXNR6q4V8w"
# Obtener los metadatos del archivo
file_info = client.files.retrieve_metadata(file_id=file_id)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")
# Listar todos los archivos
for file in client.files.list():
print(f"{file.filename} - {file.created_at}")
# Eliminar un archivo
client.files.delete(file_id=file_id)
```
```typescript TypeScript
const client = new Anthropic();
const fileId = "file_011CNha8iCJcU1wXNR6q4V8w";
// Obtener los metadatos del archivo
const fileInfo = await client.files.retrieveMetadata(fileId);
console.log(`Filename: ${fileInfo.filename}, Size: ${fileInfo.size_bytes} bytes`);
// Listar todos los archivos
for await (const file of client.files.list()) {
console.log(`${file.filename} - ${file.created_at}`);
}
// Eliminar un archivo
await client.files.delete(fileId);
```
```csharp C#
AnthropicClient client = new();
var fileId = "file_011CNha8iCJcU1wXNR6q4V8w";
// Obtener los metadatos del archivo
var fileInfo = await client.Files.RetrieveMetadata(fileId);
Console.WriteLine($"Filename: {fileInfo.Filename}, Size: {fileInfo.SizeBytes} bytes");
// Listar archivos
await foreach (var file in (await client.Files.List()).Paginate())
{
Console.WriteLine($"{file.Filename} - {file.CreatedAt}");
}
// Eliminar el archivo
await client.Files.Delete(fileId);
```
```go Go
client := anthropic.NewClient()
fileID := "file_011CNha8iCJcU1wXNR6q4V8w"
// Obtener los metadatos del archivo
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)
// Listar todos los archivos
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())
}
// Eliminar un archivo
_, 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";
// Obtener los metadatos del archivo
FileMetadata fileInfo = client.files().retrieveMetadata(fileId);
System.out.println("Filename: " + fileInfo.filename() + ", Size: " + fileInfo.sizeBytes() + " bytes");
// Listar archivos (primera página)
FileListPage files = client.files().list();
for (var file : files.data()) {
System.out.println(file.filename() + " - " + file.createdAt());
}
// Eliminar un archivo
client.files().delete(fileId);
}
```
```php PHP
$client = new Client();
$fileId = 'file_011CNha8iCJcU1wXNR6q4V8w';
// Obtener los metadatos del archivo
$fileInfo = $client->files->retrieveMetadata($fileId);
echo "Filename: {$fileInfo->filename}, Size: {$fileInfo->sizeBytes} bytes\n";
// Listar archivos (primera página)
foreach ($client->files->list()->getItems() as $file) {
echo "{$file->filename} - {$file->createdAt->format(DATE_ATOM)}\n";
}
// Eliminar un archivo
$client->files->delete($fileId);
```
```ruby Ruby
client = Anthropic::Client.new
file_id = "file_011CNha8iCJcU1wXNR6q4V8w"
# Obtener los metadatos del archivo
file_info = client.files.retrieve_metadata(file_id)
puts "Filename: #{file_info.filename}, Size: #{file_info.size_bytes} bytes"
# Listar todos los archivos
client.files.list.auto_paging_each do |file|
puts "#{file.filename} - #{file.created_at}"
end
# Eliminar un archivo
client.files.delete(file_id)
```
Para obtener todos los detalles, consulta [Files API](https://platform.claude.com/docs/es/build-with-claude/files).
### Conversaciones de múltiples turnos
El objeto `container` de la respuesta contiene el `id` del contenedor y la marca de tiempo `expires_at` (consulta [Reutilización de contenedores](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool#container-reuse) para conocer los detalles sobre su duración). Reutiliza el mismo contenedor en varios mensajes especificando el ID del contenedor:
La reutilización de contenedores en varios turnos requiere más lógica que un solo comando de shell, así que usa el SDK de Claude para ello. Para construir las solicitudes tú mismo, captura `container.id` de la primera respuesta. Luego pásalo en la siguiente solicitud como `"container": {"id": "...", "skills": [...]}`, junto con el historial de la conversación.
```bash CLI
# La primera solicitud crea el contenedor
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
)
# Continúa la conversación con el mismo contenedor
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();
// Primera solicitud 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);
// Continúa la conversación en el mismo contenedor
// Conserva el texto del asistente; container.id conserva el estado de ejecución
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)
}
// Conserva el texto del asistente; container.id conserva el estado de ejecución
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")
// Conserva el texto del asistente; container.id conserva el estado de ejecución
.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'],
// Conserva el texto del asistente; container.id conserva el estado de ejecución
['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" },
{
# Conserva el texto del asistente; container.id conserva el estado de ejecución
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
```
### Operaciones de larga duración
Las Skills pueden realizar operaciones que requieren varios turnos. Gestiona los "stop reasons" (motivos de detención) `pause_turn`:
```bash cURL
# Solicitud inicial
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"
}]
}')
# Si stop_reason es "pause_turn", continúa en el mismo contenedor y agrega
# el arreglo content de la respuesta anterior a messages como turno del asistente.
# Repite esta solicitud de continuación hasta que stop_reason ya no sea "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)
# Solicitud inicial: guarda la respuesta JSON completa en un archivo temporal
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
# Si stop_reason es "pause_turn", continúa en el mismo contenedor,
# agregando el arreglo content de la respuesta anterior a messages como
# turno del asistente. Repite hasta que stop_reason ya no sea "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;
}
// Agrega el contenido del turno pausado y continúa
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 respuesta puede incluir un motivo de detención `pause_turn`, que indica que la API pausó una operación de Skill de larga duración. Puedes devolver la respuesta tal cual en una solicitud posterior para que Claude continúe su turno, o modificar el contenido si quieres interrumpir la conversación y proporcionar orientación adicional.
### Uso de múltiples Skills
Combina varias Skills en una sola solicitud para gestionar flujos de trabajo complejos:
```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
```
***
## Gestión de Skills personalizadas
**Las Skills personalizadas son accesibles para todo tu workspace, no están limitadas a un usuario final, conversación o sesión.** Cualquier clave de API con acceso a un workspace puede leer, invocar y eliminar todas las Skills personalizadas subidas a ese workspace. Cada cuenta de servicio, y cada usuario cuyo rol en la organización permita el acceso a la API, puede usar el Default Workspace además de cualquier workspace al que lo agregues, así que mantén las Skills que deban permanecer separadas en su propio [workspace](https://platform.claude.com/docs/es/manage-claude/workspaces#api-keys-and-resource-scoping) y accede a ellas solo con claves limitadas a ese workspace.
Si estás construyendo una plataforma multi-tenant sobre la Skills API, crea un [workspace](https://platform.claude.com/docs/es/manage-claude/workspaces) separado para cada tenant. El workspace es el límite de aislamiento para las Skills personalizadas, por lo que un workspace por tenant proporciona a las Skills de cada tenant un aislamiento estricto respecto de todos los demás tenants. Cada organización puede tener hasta 100 workspaces de forma predeterminada (consulta [Cómo funcionan los workspaces](https://platform.claude.com/docs/es/manage-claude/workspaces#how-workspaces-work)); si necesitas más para el aislamiento de tenants, contacta a tu equipo de cuenta.
### Creación de una Skill
Un paquete de Skill es un directorio que contiene un archivo `SKILL.md` en el nivel superior con frontmatter YAML `name` y `description`, además de cualquier script o recurso de apoyo. Consulta [Comienza con Agent Skills en la API](https://platform.claude.com/docs/es/agents-and-tools/agent-skills/quickstart) para crear uno, y la lista de **Requisitos** que sigue a los ejemplos para conocer todas las restricciones.
Sube tu Skill personalizada para que esté disponible en tu workspace. Puedes subir un archivo zip u objetos de archivo individuales. El SDK de Python también proporciona un helper `files_from_dir` que acepta una ruta de directorio, y el comando `ant apply` de la CLI sube el propio directorio.
Los archivos se identifican por el nombre de archivo que adjuntas (el sufijo `;filename=` en el ejemplo de cURL y los argumentos de nombre de archivo en los ejemplos del SDK). Para la Skill del tutorial, crea un zip con `zip -r financial_skill.zip financial_skill/` y úsalo en lugar del marcador de posición `example_skill.zip` en las opciones de subida de 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()
# Opción 1: Usar un archivo zip
skill = client.skills.create(
files=[open("example_skill.zip", "rb")],
)
# Opción 2: Usar tuplas de archivo (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",
),
],
)
# Opción 3: Usar el 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();
// Opción 1: Usar un archivo zip
const skillFromZip = await client.skills.create({
files: [await toFile(fs.createReadStream("example_skill.zip"), "example_skill.zip")]
});
// Opción 2: Usar objetos de archivo individuales
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();
// Opción 1: Usar un archivo zip
var parameters = new SkillCreateParams
{
Files = [File.OpenRead("example_skill.zip")],
};
var skill = await client.Skills.Create(parameters);
// Opción 2: Usar archivos individuales (los nombres de archivo con ruta conservan la estructura de directorios de la 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()
// Opción 1: Usar un archivo 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)
}
// Opción 2: Usar archivos individuales
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();
// Opción 1: Usar un archivo 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);
// Opción 2: Usar archivos individuales (los nombres con ruta conservan la estructura de directorios del 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();
// Opción 1: Usar un archivo zip
$skill = $client->skills->create(
files: [
FileParam::fromResource(fopen('example_skill.zip', 'r')),
],
);
// Opción 2: Usar archivos individuales
$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
# Opción 1: Usar un archivo zip
skill = client.skills.create(
files: [
File.open("example_skill.zip", "rb")
]
)
# Opción 2: Usar archivos individuales
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}"
```
**Requisitos:**
* Debe incluir un archivo `SKILL.md` en la raíz de la subida (o en el nivel superior de una única carpeta contenedora)
* `display_name` es opcional: si se omite, se deriva del `name` de `SKILL.md`; un valor explícito puede tener hasta 255 caracteres y no necesita ser único dentro del workspace
* El tamaño total de la subida debe ser inferior a 30 MB (sin comprimir)
* Requisitos del frontmatter YAML:
* `name`: máximo 64 caracteres, solo letras minúsculas/números/guiones, sin etiquetas XML, sin palabras reservadas ("anthropic", "claude")
* `description`: máximo 1024 caracteres, no vacío, sin etiquetas XML
Para consultar los esquemas completos de solicitud/respuesta, consulta la [referencia de la API Create Skill](https://platform.claude.com/docs/es/api/skills/create).
### Listado de Skills
Recupera todas las Skills disponibles para tu workspace, incluidas tanto las Skills predefinidas de Anthropic como tus Skills personalizadas. Usa el parámetro `source` para filtrar por tipo de skill:
```bash cURL
# Lista todas las Skills
curl "https://api.anthropic.com/v1/skills" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01"
# Lista solo las Skills personalizadas
curl "https://api.anthropic.com/v1/skills?source=custom" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01"
```
```bash CLI
# Listar todas las Skills
ant skills list
# Listar solo las Skills personalizadas
ant skills list --source custom
```
```python Python
client = anthropic.Anthropic()
# Listar todas las Skills
for skill in client.skills.list():
print(f"{skill.id}: {skill.display_name} (source: {skill.source.type})")
# Listar solo las Skills personalizadas
custom_skills = client.skills.list(source="custom")
```
```typescript TypeScript
const client = new Anthropic();
// Listar todas las Skills
for await (const skill of client.skills.list()) {
console.log(`${skill.id}: ${skill.display_name} (source: ${skill.source.type})`);
}
// Listar solo las Skills personalizadas
const customSkills = await client.skills.list({
source: "custom"
});
```
```csharp C#
AnthropicClient client = new();
// Listar todas las Skills
await foreach (var skill in (await client.Skills.List()).Paginate())
{
Console.WriteLine($"{skill.ID}: {skill.DisplayName} (source: {skill.Source.Type})");
}
// Listar solo las Skills personalizadas
var customSkills = await client.Skills.List(new SkillListParams { Source = "custom" });
```
```go Go
client := anthropic.NewClient()
// Listar todas las Skills
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())
}
// Listar solo las Skills personalizadas
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();
// Listar Skills (primera página)
SkillListPage skills = client.skills().list();
for (Skill skill : skills.data()) {
System.out.println(skill.id() + ": " + skill.displayName() + " (source: " + skill.source().type() + ")");
}
// Listar solo Skills personalizadas
SkillListParams customParams = SkillListParams.builder()
.source("custom")
.build();
SkillListPage customSkills = client.skills().list(customParams);
}
```
```php PHP
$client = new Client();
// Listar Skills (primera página)
foreach ($client->skills->list()->getItems() as $skill) {
echo "{$skill->id}: {$skill->displayName} (source: {$skill->source->type})\n";
}
// Listar solo Skills personalizadas
$customSkills = $client->skills->list(
source: 'custom',
);
```
```ruby Ruby
client = Anthropic::Client.new
# Listar todas las Skills
client.skills.list.auto_paging_each do |skill|
puts "#{skill.id}: #{skill.display_name} (source: #{skill.source.type})"
end
# Listar solo las Skills personalizadas
custom_skills = client.skills.list(
source: "custom"
)
```
Consulta la [referencia de la API List Skills](https://platform.claude.com/docs/es/api/skills/list) para ver las opciones de paginación y filtrado.
### Recuperación de una Skill
Obtén los detalles de una Skill específica:
```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}"
```
### Eliminación de una Skill
Eliminar una Skill también elimina todas sus versiones.
```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")
```
### Versionado
Las Skills admiten versionado para gestionar las actualizaciones de forma segura:
**Skills de Anthropic:**
* Las versiones usan formato de fecha: `20251013`
* Se publican nuevas versiones a medida que se realizan actualizaciones
* Especifica versiones exactas para mayor estabilidad
**Skills personalizadas:**
* IDs de versión generados automáticamente: `skver_01AbCdEfGhIjKlMnOpQrStUv`
* Usa `"latest"` para obtener siempre la versión más reciente
* Crea nuevas versiones al actualizar los archivos de la Skill
Una nueva versión es un "snapshot" (instantánea) completo, no un delta: sube el conjunto completo de archivos de la Skill cada vez. Los archivos que omitas no se conservan, y el `name` en el `SKILL.md` de la nueva versión debe coincidir con el nombre existente de la Skill. Los siguientes ejemplos vuelven a subir el paquete completo `financial_skill/` de [Creación de una Skill](https://platform.claude.com/docs/es/build-with-claude/skills-guide#creating-a-skill).
```bash cURL
# Crea una nueva versión
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 versión específica
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 la versión más reciente
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 nueva versión
VERSION_ID=$(ant skills:versions create \
--skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
--file financial_skill.zip \
--transform id \
--raw-output)
# Usa una versión específica
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 versión específica
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 versión más reciente
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 nueva versión
$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 versión específica
$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 la versión más reciente
$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 nueva versión
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 versión específica
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 versión más reciente
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 la [referencia de la API Create Skill Version](https://platform.claude.com/docs/es/api/skills/versions/create) para obtener todos los detalles.
***
## Cómo se cargan las Skills
Cuando especificas Skills en un contenedor:
1. **Descubrimiento de metadatos:** Claude ve los metadatos de cada Skill (nombre, descripción) en la indicación del sistema.
2. **Carga de archivos:** Los archivos de la Skill se copian en el contenedor en `/skills/{skill-name}/`. El directorio es el nombre de la Skill (`pptx` para una Skill de Anthropic, el `name` de `SKILL.md` para una Skill personalizada), no su ID `skill_01...`.
3. **Uso automático:** Claude carga y usa automáticamente las Skills cuando son relevantes para tu solicitud.
4. **Composición:** Múltiples Skills se combinan entre sí para flujos de trabajo complejos.
Claude carga las instrucciones completas de la Skill solo cuando es necesario.
***
## Casos de uso
Las Skills se adaptan tanto al trabajo organizacional como al personal. Las organizaciones las usan para aplicar formato de marca a documentos, estructurar notas e informes en torno a plantillas de la empresa y ejecutar procedimientos analíticos específicos de la empresa. Las personas las usan para plantillas de documentos personalizadas, pipelines de datos especializados y convenciones de generación de código o despliegue.
### Ejemplo: modelado financiero
Combina la Skill de Excel con una Skill personalizada de análisis DCF. Primero, crea la Skill personalizada de análisis 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
```
Luego úsala junto con la Skill de Excel para crear un modelo financiero. Pasa el ID de la Skill que creaste como el `skill_id` de la Skill personalizada:
```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 personalizada de análisis DCF (ID obtenido de la respuesta de creación de la API de Skills)
dcf_skill_id = "skill_01AbCdEfGhIjKlMnOpQrStUv"
# Úsala con Excel para crear un modelo financiero
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 personalizada de análisis DCF (ID obtenido de la respuesta de creación de la Skills API)
const dcfSkillId = "skill_01AbCdEfGhIjKlMnOpQrStUv";
// Úsala con Excel para crear un modelo financiero
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 personalizada de análisis DCF (ID obtenido de la respuesta de creación de la Skills API)
var dcfSkillId = "skill_01AbCdEfGhIjKlMnOpQrStUv";
// Úsala con Excel para crear un modelo financiero
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 personalizada de análisis DCF (ID obtenido de la respuesta de creación de la Skills API)
dcfSkillID := "skill_01AbCdEfGhIjKlMnOpQrStUv"
// Úsala con Excel para crear un modelo financiero
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 personalizada de análisis DCF (ID obtenido de la respuesta de creación de la Skills API)
String dcfSkillId = "skill_01AbCdEfGhIjKlMnOpQrStUv";
// Úsala con la Skill de Excel para crear un modelo financiero
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 personalizada de análisis DCF (ID obtenido de la respuesta de creación de la Skills API)
$dcfSkillId = 'skill_01AbCdEfGhIjKlMnOpQrStUv';
// Úsala con Excel para crear un modelo financiero
$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 personalizada de análisis DCF (ID obtenido de la respuesta de creación de la Skills API)
dcf_skill_id = "skill_01AbCdEfGhIjKlMnOpQrStUv"
# Úsala con Excel para crear un modelo financiero
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
```
***
## Límites y restricciones
### Límites de solicitud
* **Máximo de Skills por solicitud:** 20
* **Tamaño máximo de subida de una Skill:** 30 MB (todos los archivos combinados, sin comprimir)
* **Requisitos del frontmatter YAML:**
* `name`: Máximo 64 caracteres, solo letras minúsculas/números/guiones, sin etiquetas XML, sin palabras reservadas ("anthropic", "claude")
* `description`: Máximo 1024 caracteres, no vacío, sin etiquetas XML
### Restricciones del entorno
Las Skills se ejecutan en el contenedor de ejecución de código con estas limitaciones:
* **Sin acceso a la red:** No pueden realizar llamadas a API externas
* **Sin instalación de paquetes en tiempo de ejecución:** Solo están disponibles los paquetes preinstalados
* **Entorno aislado:** Se crea un contenedor nuevo a menos que especifiques un ID de contenedor existente
Consulta [Herramienta de ejecución de código](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool) para ver los paquetes disponibles.
***
## Mejores prácticas
### Cuándo usar múltiples Skills
Combina Skills cuando las tareas involucren múltiples tipos de documentos o dominios:
**Buenos casos de uso:**
* Análisis de datos (Excel) + creación de presentaciones (PowerPoint)
* Generación de informes (Word) + exportación a PDF
* Lógica de dominio personalizada + generación de documentos
**Evita:**
* Incluir Skills no utilizadas (afecta el rendimiento)
### Estrategia de gestión de versiones
Las pestañas de SDK de esta sección muestran el valor de `container` que debes incluir en una solicitud de Messages. Las pestañas de cURL y CLI muestran la solicitud completa.
**Para producción:** fija una versión específica para que las actualizaciones de la Skill nunca cambien el comportamiento de lo que ya tienes desplegado. Si omites `version` o lo estableces en `"latest"`, las solicitudes usan la versión más reciente de la Skill. En ese caso, una versión que suba cualquier persona del [workspace](https://platform.claude.com/docs/es/build-with-claude/skills-guide#workspace-scoped-access) cambia de inmediato lo que ejecutan tus agentes en producción. El ID de versión proviene de la respuesta de creación de versión en [Versionado](https://platform.claude.com/docs/es/build-with-claude/skills-guide#versioning) o de la [API List Skill Versions](https://platform.claude.com/docs/es/api/skills/versions/list). El ID siempre es una cadena, así que ponlo entre comillas en JSON o YAML aunque parezca numérico.
```bash cURL
# Fija versiones específicas para mayor estabilidad
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
# Fija versiones específicas para mayor estabilidad
ant messages create < [[
'type' => 'custom',
'skillID' => 'skill_01AbCdEfGhIjKlMnOpQrStUv',
'version' => 'skver_01AbCdEfGhIjKlMnOpQrStUv'
]]
];
```
```ruby Ruby
# Fija versiones específicas para mayor estabilidad
container = {
skills: [{
type: "custom",
skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv",
version: "skver_01AbCdEfGhIjKlMnOpQrStUv"
}]
}
```
**Para desarrollo:** usa `latest` para obtener automáticamente la versión más reciente mientras iteras.
```bash cURL
# Usa latest para el desarrollo activo
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 para el desarrollo activo
ant messages create < [[
'type' => 'custom',
'skillID' => 'skill_01AbCdEfGhIjKlMnOpQrStUv',
'version' => 'latest'
]]
];
```
```ruby Ruby
# Usa latest para el desarrollo activo
container = {
skills: [{
type: "custom",
skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv",
version: "latest"
}]
}
```
### Consideraciones sobre el almacenamiento en caché de prompts
Si usas el ["prompt caching" (almacenamiento en caché de prompts)](https://platform.claude.com/docs/es/build-with-claude/prompt-caching), cambiar la lista de Skills de tu contenedor invalida la caché. Las Skills se insertan en el "system prompt" (indicación del sistema) en un orden fijo, por lo que la misma lista produce el mismo prefijo almacenable en caché:
```bash cURL
# Las Skills se renderizan en la indicación del sistema en un orden fijo y compatible con la caché
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"}]
}'
# Cambiar la lista de Skills ([xlsx] vs [xlsx, pptx]) cambia el prefijo: un fallo de caché; una lista idéntica es un acierto de caché
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
# Las Skills se renderizan en la indicación del sistema en un orden fijo y compatible con la caché
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
# Cambiar la lista de Skills ([xlsx] vs [xlsx, pptx]) cambia el prefijo: fallo de caché; una lista idéntica es un acierto de caché
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()
# Las Skills se renderizan en la indicación del sistema en un orden fijo y compatible con la caché
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"}],
)
# Cambiar la lista de Skills ([xlsx] vs [xlsx, pptx]) cambia el prefijo: fallo de caché; una lista idéntica es un acierto de caché
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();
// Las Skills se renderizan en la indicación del sistema en un orden fijo y compatible con la caché
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" }]
});
// Cambiar la lista de Skills ([xlsx] vs [xlsx, pptx]) cambia el prefijo: fallo de caché; una lista idéntica es un acierto de caché
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();
// Las Skills se renderizan en la indicación del sistema en un orden fijo y compatible con la caché
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 conjunto de Skills distinto ([xlsx] vs [xlsx, pptx]) = un prefijo distinto: fallo de caché (un conjunto idéntico es un acierto de caché)
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()
// Las Skills se renderizan en la indicación del sistema en un orden fijo y compatible con la caché
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)
// Cambiar la lista de Skills ([xlsx] vs [xlsx, pptx]) cambia el prefijo: fallo de caché; una lista idéntica es un acierto de caché
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();
// Las Skills se renderizan en la indicación del sistema en un orden fijo y compatible con la caché
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);
// Cambiar la lista de Skills ([xlsx] vs [xlsx, pptx]) cambia el prefijo: fallo de caché; una lista idéntica es un acierto de caché
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();
// Las Skills se renderizan en la indicación del sistema en un orden fijo y compatible con la caché
$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;
// Cambiar la lista de Skills ([xlsx] vs [xlsx, pptx]) cambia el prefijo: fallo de caché; una lista idéntica es un acierto de caché
$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
# Las Skills se renderizan en la indicación del sistema en un orden fijo y compatible con la caché
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
# Cambiar la lista de Skills ([xlsx] vs [xlsx, pptx]) cambia el prefijo: fallo de caché; una lista idéntica es un acierto de caché
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
```
Para obtener el mejor rendimiento de la caché, mantén tu lista de Skills, incluido su orden, igual en todas las solicitudes. Fijar las versiones de las Skills personalizadas también ayuda: con `"latest"`, publicar una nueva versión puede invalidar el prefijo almacenado en caché si cambia la descripción de la Skill.
### Manejo de errores
Maneja correctamente los errores relacionados con las Skills:
Este flujo de manejo de errores requiere más lógica que un solo comando de shell, así que usa el SDK de Claude para ello. Una solicitud que falla debido a un problema con una Skill devuelve HTTP 400. El campo `error.message` en el cuerpo de la respuesta JSON describe el 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"
# Maneja los errores específicos de las skills
;;
*)
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}")
# Gestiona los errores específicos de las skills
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}`);
// Maneja los errores específicos de las skills
} 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
```
***
## Migrar desde `skills-2025-10-02`
La Skills API ya no está en beta y no necesita encabezado beta. Migrar desde `skills-2025-10-02` es opcional: las solicitudes que aún lo envían siguen funcionando y siguen devolviendo las formas de respuesta beta, por lo que una integración existente sigue funcionando hasta que la cambies. Eliminar el encabezado cambia esas solicitudes a las formas documentadas en esta página:
| | Con `skills-2025-10-02` | Sin el encabezado |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Etiqueta de la Skill | `display_title` (hasta 64 caracteres, único por workspace) | `display_name` (hasta 255 caracteres, no único); se deriva del `name` de `SKILL.md` cuando se omite |
| Puntero a la versión más reciente | `latest_version`, una cadena de microsegundos epoch como `"1759178010641129"` | `latest_version_id`, un ID de versión como `"skver_01AbCdEfGhIjKlMnOpQrStUv"`; `GET /v1/skills/{skill_id}/versions/latest` lo resuelve en una sola llamada |
| Identificador de versión en URLs | Cadena de microsegundos epoch | ID de versión (`skver_...`). Los IDs capturados bajo la beta con el prefijo `skill_version_` se aceptan como entrada. |
| Objeto de versión | Incluye `directory` (siempre igual al `name` de la Skill) | Sin campo `directory` |
| `source` | Una cadena, `"custom"` o `"anthropic"` | Un objeto, por ejemplo `{"type": "custom"}`; el valor del catálogo de ejemplos es `"anthropic_example"` |
| Respuestas de listado | `{ data, has_more, next_page }` | `{ data, next_page }`; `limit` de 1 a 1,000 (predeterminado 20) |
| Orden del listado de versiones | La más antigua primero | La más reciente primero, `limit` predeterminado 20. Los cursores de página de una forma no son válidos en la otra. |
| Eliminar una Skill | Devuelve un error 400 mientras exista alguna versión | Elimina la Skill y todas sus versiones |
| Eliminar la única versión de una Skill | Permitido, dejando una Skill sin versiones | Devuelve un error 400; sube primero una versión de reemplazo, o elimina la Skill |
| Estructura de la subida | Los archivos deben estar dentro de un directorio de nivel superior cuyo nombre coincida con el `name` de la Skill | `SKILL.md` puede estar en la raíz de la subida; las rutas almacenadas son las mismas en ambos casos |
| Tipos de respuesta | `CreateSkillResponse`, `GetSkillResponse` y un tipo por operación | `Skill`, `SkillVersion`, `DeletedSkill`, `DeletedSkillVersion` |
Para migrar:
1. **Elimina el encabezado beta.** Quita `anthropic-beta: skills-2025-10-02` de tus solicitudes. En los SDK, llama a `client.skills` en lugar de `client.beta.skills`; mantener `client.beta.skills` funciona solo en las [versiones del SDK que ya no envían el encabezado](https://platform.claude.com/docs/es/build-with-claude/skills-guide#sdk-beta-namespace). Las versiones anteriores lo envían desde `client.beta.skills` incluso sin argumento `betas`.
2. **Renombra los campos** en tu código: `display_title` a `display_name`, `latest_version` a `latest_version_id`, y lee `source.type` en lugar de comparar `source` con una cadena.
3. **Usa IDs de versión.** Dondequiera que hayas almacenado una versión en microsegundos epoch, almacena en su lugar el `id` de la versión, o usa `latest`. Las referencias a Skills en las solicitudes de Messages aceptan un ID de versión, `latest` o (para las Skills de Anthropic) la versión del catálogo.
4. **Revisa las llamadas de eliminación.** `DELETE /v1/skills/{skill_id}` ahora elimina todas las versiones junto con la Skill. Si dependías del rechazo de la beta como protección, agrega tu propia verificación.
Después de migrar, `client.skills.delete(skill_id)` y `client.beta.skills.delete(skill_id)` eliminan la Skill junto con todas sus versiones en una sola llamada.
Una Skill cuyas versiones fueron todas eliminadas bajo la beta no tiene una versión actual que devolver: `GET /v1/skills/{skill_id}` devuelve un error 400 y la Skill se omite de las respuestas de listado hasta que le subas una versión. Aún puedes eliminarla.
### Espacio de nombres beta del SDK
A partir de 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 y C# SDK 12.44.0, `client.beta.skills` ya no envía `skills-2025-10-02` y devuelve las mismas formas que `client.skills`, con nombres de tipo con prefijo `Beta` (`BetaSkill`, `BetaSkillVersion`, `BetaDeletedSkill`, `BetaDeletedSkillVersion`). Acepta un argumento `betas` para las funciones de Skills que aún están en beta. En los tipos beta de Messages, el tipo de referencia a Skill del contenedor se renombra de `BetaSkill` a `BetaContainerSkill` (mismos campos: `type`, `skill_id`, `version`); `BetaSkill` ahora nombra el recurso Skill, en correspondencia con `Skill` y `ContainerSkill` en los tipos no beta. Las versiones anteriores del SDK están tipadas con las formas beta; si dependes de esos tipos, permanece en una versión anterior hasta que migres.
## Retención de datos
Las Agent Skills no están cubiertas por los acuerdos ZDR. Las definiciones de Skills y los datos de ejecución se retienen de acuerdo con la política estándar de retención de datos de Anthropic.
Para conocer la elegibilidad ZDR de todas las funciones, consulta [API y retención de datos](https://platform.claude.com/docs/es/manage-claude/api-and-data-retention).
## Registro de auditoría
Si tu organización tiene habilitada la [Compliance API](https://platform.claude.com/docs/es/manage-claude/compliance-api), su [Activity Feed](https://platform.claude.com/docs/es/manage-claude/compliance-activity-feed) registra la creación y eliminación de Skills y versiones de Skills realizadas con una clave de API de Claude o desde la Claude Console. Las operaciones que ocurren mientras la Compliance API está desactivada no se registran y no pueden recuperarse posteriormente, así que [configura la Compliance API](https://platform.claude.com/docs/es/manage-claude/compliance-api-access) antes de depender de este registro de auditoría.
## Próximos pasos
Referencia completa de la API con todos los endpoints
Aprende a escribir Skills efectivas que Claude pueda descubrir y usar con éxito.
Ejecuta código Python y bash en un contenedor aislado para analizar datos, generar archivos e iterar sobre soluciones.