Habilidades de Agente

Por qué usar Habilidades

Las Habilidades son recursos reutilizables basados en el sistema de archivos que proporcionan a Claude experiencia específica de dominio: flujos de trabajo, contexto y mejores prácticas que transforman agentes de propósito general en especialistas. A diferencia de los prompts (instrucciones a nivel de conversación para tareas puntuales), las Habilidades se cargan bajo demanda y eliminan la necesidad de proporcionar repetidamente la misma orientación en múltiples conversaciones.

Beneficios clave:

• Especializar a Claude: Adaptar capacidades para tareas específicas de dominio
• Reducir la repetición: Crear una vez, usar automáticamente
• Componer capacidades: Combinar Habilidades para construir flujos de trabajo complejos

Usar Habilidades

Anthropic proporciona Habilidades de Agente prediseñadas para tareas comunes de documentos (PowerPoint, Excel, Word, PDF), y puede crear sus propias Habilidades personalizadas. Ambas funcionan de la misma manera. Claude las usa automáticamente cuando son relevantes para su solicitud.

Las Habilidades de Agente prediseñadas están disponibles para todos los usuarios en claude.ai y a través de la API de Claude. Consulte la sección Habilidades disponibles a continuación para ver la lista completa.

Las Habilidades personalizadas le permiten empaquetar experiencia de dominio y conocimiento organizacional. Están disponibles en todos los productos de Claude: créelas en Claude Code, cárguelas a través de la API o agréguelas en la configuración de claude.ai.

Cómo funcionan las Habilidades

Las Habilidades aprovechan el entorno de VM de Claude para proporcionar capacidades más allá de lo que es posible solo con prompts. Claude opera en una máquina virtual con acceso al sistema de archivos, lo que permite que las Habilidades existan como directorios que contienen instrucciones, código ejecutable y materiales de referencia, organizados como una guía de incorporación que crearía para un nuevo miembro del equipo.

Esta arquitectura basada en el sistema de archivos permite la divulgación progresiva: Claude carga información en etapas según sea necesario, en lugar de consumir contexto de antemano.

Tres tipos de contenido de Habilidades, tres niveles de carga

Las Habilidades pueden contener tres tipos de contenido, cada uno cargado en diferentes momentos:

Nivel 1: Metadatos (siempre cargados)

Tipo de contenido: Instrucciones. El frontmatter YAML de la Habilidad proporciona información de descubrimiento:

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---

Claude carga estos metadatos al inicio y los incluye en el prompt del sistema. Este enfoque ligero significa que puede instalar muchas Habilidades sin penalización de contexto; Claude solo sabe que cada Habilidad existe y cuándo usarla.

Nivel 2: Instrucciones (cargadas cuando se activan)

Tipo de contenido: Instrucciones. El cuerpo principal de SKILL.md contiene conocimiento procedimental: flujos de trabajo, mejores prácticas y orientación:

# PDF Processing

## Quick start

Use pdfplumber to extract text from PDFs:

```python
import pdfplumber

with pdfplumber.open("document.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

For advanced form filling, see [FORMS.md](FORMS.md).

Cuando solicita algo que coincide con la descripción de una Habilidad, Claude lee SKILL.md desde el sistema de archivos a través de bash. Solo entonces este contenido entra en la ventana de contexto.

Nivel 3: Recursos y código (cargados según sea necesario)

Tipos de contenido: Instrucciones, código y recursos. Las Habilidades pueden incluir materiales adicionales:

pdf-skill/
├── SKILL.md (main instructions)
├── FORMS.md (form-filling guide)
├── REFERENCE.md (detailed API reference)
└── scripts/
    └── fill_form.py (utility script)

Instrucciones: Archivos markdown adicionales (FORMS.md, REFERENCE.md) que contienen orientación especializada y flujos de trabajo

Código: Scripts ejecutables (fill_form.py, validate.py) que Claude ejecuta a través de bash; los scripts proporcionan operaciones deterministas sin consumir contexto

Recursos: Materiales de referencia como esquemas de bases de datos, documentación de API, plantillas o ejemplos

Claude accede a estos archivos solo cuando se hace referencia a ellos. El modelo de sistema de archivos significa que cada tipo de contenido tiene diferentes fortalezas: instrucciones para orientación flexible, código para confiabilidad, recursos para búsqueda factual.

La divulgación progresiva garantiza que solo el contenido relevante ocupe la ventana de contexto en un momento dado.

La arquitectura de Habilidades

Las Habilidades se ejecutan en un entorno de ejecución de código donde Claude tiene acceso al sistema de archivos, comandos bash y capacidades de ejecución de código. Piénselo así: las Habilidades existen como directorios en una máquina virtual, y Claude interactúa con ellas usando los mismos comandos bash que usaría para navegar por archivos en su computadora.

Cómo Claude accede al contenido de las Habilidades:

Cuando se activa una Habilidad, Claude usa bash para leer SKILL.md desde el sistema de archivos, incorporando sus instrucciones en la ventana de contexto. Si esas instrucciones hacen referencia a otros archivos (como FORMS.md o un esquema de base de datos), Claude también lee esos archivos usando comandos bash adicionales. Cuando las instrucciones mencionan scripts ejecutables, Claude los ejecuta a través de bash y recibe solo la salida (el código del script en sí nunca entra en el contexto).

Lo que esta arquitectura permite:

Acceso a archivos bajo demanda: Claude lee solo los archivos necesarios para cada tarea específica. Una Habilidad puede incluir docenas de archivos de referencia, pero si su tarea solo necesita el esquema de ventas, Claude carga solo ese archivo. El resto permanece en el sistema de archivos consumiendo cero tokens.

Ejecución eficiente de scripts: Cuando Claude ejecuta validate_form.py, el código del script nunca se carga en la ventana de contexto. Solo la salida del script (como "Validación aprobada" o mensajes de error específicos) consume tokens. Esto hace que los scripts sean mucho más eficientes que hacer que Claude genere código equivalente sobre la marcha.

Sin límite práctico en el contenido incluido: Debido a que los archivos no consumen contexto hasta que se accede a ellos, las Habilidades pueden incluir documentación completa de API, grandes conjuntos de datos, ejemplos extensos o cualquier material de referencia que necesite. No hay penalización de contexto para el contenido incluido que no se usa.

Este modelo basado en el sistema de archivos es lo que hace que la divulgación progresiva funcione. Claude navega por su Habilidad como usted haría referencia a secciones específicas de una guía de incorporación, accediendo exactamente a lo que cada tarea requiere.

Ejemplo: Carga de una habilidad de procesamiento de PDF

Así es como Claude carga y usa una habilidad de procesamiento de PDF:

1. Inicio: El prompt del sistema incluye: PDF Processing - Extract text and tables from PDF files, fill forms, merge documents
2. Solicitud del usuario: "Extrae el texto de este PDF y resúmelo"
3. Claude invoca: bash: read pdf-skill/SKILL.md → Instrucciones cargadas en el contexto
4. Claude determina: El llenado de formularios no es necesario, por lo que FORMS.md no se lee
5. Claude ejecuta: Usa las instrucciones de SKILL.md para completar la tarea

El diagrama muestra:

1. Estado predeterminado con el prompt del sistema y los metadatos de habilidades precargados
2. Claude activa la habilidad leyendo SKILL.md a través de bash
3. Claude opcionalmente lee archivos adicionales incluidos como FORMS.md según sea necesario
4. Claude procede con la tarea

Esta carga dinámica garantiza que solo el contenido relevante de la habilidad ocupe la ventana de contexto.

Dónde funcionan las Habilidades

Las Habilidades están disponibles en todos los productos de agente de Claude:

API de Claude

La API de Claude admite tanto Habilidades de Agente prediseñadas como Habilidades personalizadas. Ambas funcionan de manera idéntica: especifique el skill_id relevante en el parámetro container junto con la herramienta de ejecución de código.

Requisitos previos: El uso de Habilidades a través de la API requiere tres encabezados beta:

• code-execution-2025-08-25 - Las Habilidades se ejecutan en el contenedor de ejecución de código
• skills-2025-10-02 - Habilita la funcionalidad de Habilidades
• files-api-2025-04-14 - Necesario para cargar/descargar archivos hacia/desde el contenedor

Use Habilidades de Agente prediseñadas haciendo referencia a su skill_id (por ejemplo, pptx, xlsx), o cree y cargue las suyas propias a través de la API de Habilidades (endpoints /v1/skills). Las Habilidades personalizadas se comparten en toda la organización.

Para obtener más información, consulte Usar Habilidades con la API de Claude.

Claude Code

Claude Code solo admite Habilidades personalizadas.

Habilidades personalizadas: Cree Habilidades como directorios con archivos SKILL.md. Claude las descubre y las usa automáticamente.

Las Habilidades personalizadas en Claude Code están basadas en el sistema de archivos y no requieren cargas a través de la API.

Para obtener más información, consulte Usar Habilidades en Claude Code.

SDK de Agente de Claude

El SDK de Agente de Claude admite Habilidades personalizadas a través de la configuración basada en el sistema de archivos.

Habilidades personalizadas: Cree Habilidades como directorios con archivos SKILL.md en .claude/skills/. Habilite las Habilidades incluyendo "Skill" en su configuración de allowed_tools.

Las Habilidades en el SDK de Agente se descubren automáticamente cuando se ejecuta el SDK.

Para obtener más información, consulte Habilidades de Agente en el SDK.

Claude.ai

Claude.ai admite tanto Habilidades de Agente prediseñadas como Habilidades personalizadas.

Habilidades de Agente prediseñadas: Estas Habilidades ya funcionan en segundo plano cuando crea documentos. Claude las usa sin requerir ninguna configuración.

Habilidades personalizadas: Cargue sus propias Habilidades como archivos zip a través de Configuración > Funciones. Disponible en los planes Pro, Max, Team y Enterprise con ejecución de código habilitada. Las Habilidades personalizadas son individuales para cada usuario; no se comparten en toda la organización y los administradores no pueden gestionarlas de forma centralizada.

Para obtener más información sobre el uso de Habilidades en Claude.ai, consulte los siguientes recursos en el Centro de ayuda de Claude:

• ¿Qué son las Habilidades?
• Usar Habilidades en Claude
• Cómo crear Habilidades personalizadas
• Enseña a Claude tu forma de trabajar usando Habilidades

Estructura de una Habilidad

Cada Habilidad requiere un archivo SKILL.md con frontmatter YAML:

---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
---

# Your Skill Name

## Instructions
[Clear, step-by-step guidance for Claude to follow]

## Examples
[Concrete examples of using this Skill]

Campos requeridos: name y description

Requisitos de los campos:

name:

• Máximo 64 caracteres
• Debe contener solo letras minúsculas, números y guiones
• No puede contener etiquetas XML
• No puede contener palabras reservadas: "anthropic", "claude"

description:

• No debe estar vacío
• Máximo 1024 caracteres
• No puede contener etiquetas XML

La description debe incluir tanto lo que hace la Habilidad como cuándo Claude debe usarla. Para obtener orientación completa sobre la creación, consulte la guía de mejores prácticas.

Consideraciones de seguridad

Recomendamos encarecidamente usar Habilidades solo de fuentes confiables: las que usted mismo creó u obtuvo de Anthropic. Las Habilidades proporcionan a Claude nuevas capacidades a través de instrucciones y código, y aunque esto las hace poderosas, también significa que una Habilidad maliciosa puede dirigir a Claude a invocar herramientas o ejecutar código de maneras que no coinciden con el propósito declarado de la Habilidad.

Consideraciones clave de seguridad:

• Auditar exhaustivamente: Revise todos los archivos incluidos en la Habilidad: SKILL.md, scripts, imágenes y otros recursos. Busque patrones inusuales como llamadas de red inesperadas, patrones de acceso a archivos u operaciones que no coincidan con el propósito declarado de la Habilidad
• Las fuentes externas son arriesgadas: Las Habilidades que obtienen datos de URLs externas representan un riesgo particular, ya que el contenido obtenido puede contener instrucciones maliciosas. Incluso las Habilidades confiables pueden verse comprometidas si sus dependencias externas cambian con el tiempo
• Uso indebido de herramientas: Las Habilidades maliciosas pueden invocar herramientas (operaciones de archivos, comandos bash, ejecución de código) de maneras dañinas
• Exposición de datos: Las Habilidades con acceso a datos sensibles podrían estar diseñadas para filtrar información a sistemas externos
• Trátelas como la instalación de software: Use Habilidades solo de fuentes confiables. Sea especialmente cuidadoso al integrar Habilidades en sistemas de producción con acceso a datos sensibles u operaciones críticas

Habilidades disponibles

Habilidades de Agente prediseñadas

Las siguientes Habilidades de Agente prediseñadas están disponibles para uso inmediato:

• PowerPoint (pptx): Crear presentaciones, editar diapositivas, analizar contenido de presentaciones
• Excel (xlsx): Crear hojas de cálculo, analizar datos, generar informes con gráficos
• Word (docx): Crear documentos, editar contenido, dar formato al texto
• PDF (pdf): Generar documentos PDF formateados e informes

Estas Habilidades están disponibles en la API de Claude y claude.ai. Consulte el tutorial de inicio rápido para comenzar a usarlas en la API.

Ejemplos de Habilidades personalizadas

Para ver ejemplos completos de Habilidades personalizadas, consulte el cookbook de Habilidades.

Retención de datos

Las Habilidades de Agente no están cubiertas por los acuerdos ZDR. Las definiciones de Habilidades 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 en todas las funciones, consulte API y retención de datos.

Limitaciones y restricciones

Comprender estas limitaciones le ayuda a planificar su implementación de Habilidades de manera efectiva.

Disponibilidad entre superficies

Las Habilidades personalizadas no se sincronizan entre superficies. Las Habilidades cargadas en una superficie no están disponibles automáticamente en otras:

• Las Habilidades cargadas en Claude.ai deben cargarse por separado en la API
• Las Habilidades cargadas a través de la API no están disponibles en Claude.ai
• Las Habilidades de Claude Code están basadas en el sistema de archivos y son independientes tanto de Claude.ai como de la API

Deberá gestionar y cargar las Habilidades por separado para cada superficie donde desee usarlas.

Alcance de compartición

Las Habilidades tienen diferentes modelos de compartición dependiendo de dónde las use:

• Claude.ai: Solo usuario individual; cada miembro del equipo debe cargarlas por separado
• API de Claude: En todo el espacio de trabajo; todos los miembros del espacio de trabajo pueden acceder a las Habilidades cargadas
• Claude Code: Personal (~/.claude/skills/) o basado en proyectos (.claude/skills/); también se puede compartir a través de los Plugins de Claude Code

Claude.ai actualmente no admite la gestión centralizada de administradores ni la distribución de Habilidades personalizadas en toda la organización.

Restricciones del entorno de ejecución

El entorno de ejecución exacto disponible para su habilidad depende de la superficie del producto donde la use.

• Claude.ai:
  • Acceso a red variable: Dependiendo de la configuración del usuario/administrador, las Habilidades pueden tener acceso completo, parcial o ningún acceso a la red. Para más detalles, consulte el artículo de soporte Crear y editar archivos.
• API de Claude:
  • Sin acceso a red: Las Habilidades no pueden realizar llamadas a API externas ni acceder a Internet
  • Sin instalación de paquetes en tiempo de ejecución: Solo están disponibles los paquetes preinstalados. No puede instalar nuevos paquetes durante la ejecución.
  • Solo dependencias preconfiguradas: Consulte la documentación de la herramienta de ejecución de código para ver la lista de paquetes disponibles
• Claude Code:
  • : Las Habilidades tienen el mismo acceso a la red que cualquier otro programa en la computadora del usuario

Planifique sus Habilidades para que funcionen dentro de estas restricciones.

Próximos pasos