Agent Skills

Por qué usar Skills

Skills son recursos reutilizables basados en el sistema de archivos que proporcionan a Claude experiencia específica del 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), Skills se cargan bajo demanda y eliminan la necesidad de proporcionar repetidamente la misma orientación en múltiples conversaciones.

Beneficios clave:

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

Usar Skills

Anthropic proporciona Agent Skills pre-construidas para tareas comunes de documentos (PowerPoint, Excel, Word, PDF), y puedes crear tus propias Skills personalizadas. Ambas funcionan de la misma manera. Claude las utiliza automáticamente cuando son relevantes para tu solicitud.

Agent Skills pre-construidas están disponibles para todos los usuarios en claude.ai y a través de la API de Claude. Consulta la sección Available Skills a continuación para obtener la lista completa.

Custom Skills te permiten empaquetar experiencia de dominio y conocimiento organizacional. Están disponibles en todos los productos de Claude: créalas en Claude Code, cárgalas a través de la API, o agrégalas en la configuración de claude.ai.

Cómo funcionan las Skills

Skills 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, permitiendo que Skills existan como directorios que contienen instrucciones, código ejecutable y materiales de referencia, organizados como una guía de incorporación que crearías para un nuevo miembro del equipo.

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

Tres tipos de contenido de Skill, tres niveles de carga

Las Skills 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 Skill 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 e los incluye en el prompt del sistema. Este enfoque ligero significa que puedes instalar muchas Skills sin penalización de contexto; Claude solo sabe que cada Skill existe y cuándo usarla.

Nivel 2: Instrucciones (cargadas cuando se activan)

Tipo de contenido: Instrucciones. El cuerpo principal de SKILL.md contiene conocimiento procedural: 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 solicitas algo que coincide con la descripción de una Skill, Claude lee SKILL.md del 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 Skills pueden agrupar 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 del 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 de hechos.

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

La arquitectura de Skills

Las Skills 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énsalo así: Las Skills existen como directorios en una máquina virtual, y Claude interactúa con ellas usando los mismos comandos bash que usarías para navegar archivos en tu computadora.

Cómo Claude accede al contenido de Skill:

Cuando se activa una Skill, Claude usa bash para leer SKILL.md del sistema de archivos, trayendo sus instrucciones a 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 nunca entra en contexto).

Lo que esta arquitectura permite:

Acceso a archivos bajo demanda: Claude lee solo los archivos necesarios para cada tarea específica. Una Skill puede incluir docenas de archivos de referencia, pero si tu 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 "Validation passed" 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 contenido agrupado: Debido a que los archivos no consumen contexto hasta que se accede a ellos, las Skills pueden incluir documentación completa de API, conjuntos de datos grandes, ejemplos extensos o cualquier material de referencia que necesites. No hay penalización de contexto para contenido agrupado que no se usa.

Este modelo basado en el sistema de archivos es lo que hace que funcione la divulgación progresiva. Claude navega tu Skill como referirías secciones específicas de una guía de incorporación, accediendo exactamente a lo que cada tarea requiere.

Ejemplo: Cargando una skill de procesamiento de PDF

Así es cómo Claude carga y usa una skill 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: "Extract the text from this PDF and summarize it"
3. Claude invoca: bash: read pdf-skill/SKILL.md → Instrucciones cargadas en contexto
4. Claude determina: El relleno de formularios no es necesario, por lo que FORMS.md no se lee
5. Claude ejecuta: Usa instrucciones de SKILL.md para completar la tarea

El diagrama muestra:

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

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

Dónde funcionan las Skills

Las Skills están disponibles en todos los productos de agentes de Claude:

Claude API

La API de Claude admite tanto Agent Skills pre-construidas como Custom Skills. Ambas funcionan de manera idéntica: especifica el skill_id relevante en el parámetro container junto con la herramienta de ejecución de código.

Requisitos previos: Usar Skills a través de la API requiere tres encabezados beta:

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

Usa Agent Skills pre-construidas haciendo referencia a su skill_id (por ejemplo, pptx, xlsx), o crea y carga las tuyas propias a través de la API de Skills (puntos finales /v1/skills). Las Custom Skills se comparten en toda la organización.

Para obtener más información, consulta Use Skills with the Claude API.

Claude Code

Claude Code admite solo Custom Skills.

Custom Skills: Crea Skills como directorios con archivos SKILL.md. Claude los descubre y utiliza automáticamente.

Las Custom Skills en Claude Code están basadas en el sistema de archivos y no requieren cargas de API.

Para obtener más información, consulta Use Skills in Claude Code.

Claude Agent SDK

El Claude Agent SDK admite Custom Skills a través de configuración basada en el sistema de archivos.

Custom Skills: Crea Skills como directorios con archivos SKILL.md en .claude/skills/. Habilita Skills incluyendo "Skill" en tu configuración allowed_tools.

Las Skills en el Agent SDK se descubren automáticamente cuando se ejecuta el SDK.

Para obtener más información, consulta Agent Skills in the SDK.

Claude.ai

Claude.ai admite tanto Agent Skills pre-construidas como Custom Skills.

Agent Skills pre-construidas: Estas Skills ya están funcionando detrás de escenas cuando creas documentos. Claude las utiliza sin requerir ninguna configuración.

Custom Skills: Carga tus propias Skills como archivos zip a través de Settings > Features. Disponible en planes Pro, Max, Team y Enterprise con ejecución de código habilitada. Las Custom Skills son individuales para cada usuario; no se comparten en toda la organización y no pueden ser administradas centralmente por administradores.

Para obtener más información sobre el uso de Skills en Claude.ai, consulta los siguientes recursos en el Centro de Ayuda de Claude:

• What are Skills?
• Using Skills in Claude
• How to create custom Skills
• Teach Claude your way of working using Skills

Estructura de Skill

Cada Skill 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 campo:

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:

• Debe ser no vacío
• Máximo 1024 caracteres
• No puede contener etiquetas XML

La description debe incluir tanto qué hace la Skill como cuándo Claude debe usarla. Para orientación completa de autoría, consulta la guía de mejores prácticas.

Consideraciones de seguridad

Recomendamos encarecidamente usar Skills solo de fuentes confiables: aquellas que creaste tú mismo u obtuviste de Anthropic. Las Skills proporcionan a Claude nuevas capacidades a través de instrucciones y código, y aunque esto las hace poderosas, también significa que una Skill maliciosa puede dirigir a Claude a invocar herramientas o ejecutar código de formas que no coincidan con el propósito declarado de la Skill.

Consideraciones clave de seguridad:

• Auditar minuciosamente: Revisa todos los archivos agrupados en la Skill: SKILL.md, scripts, imágenes y otros recursos. Busca patrones inusuales como llamadas de red inesperadas, patrones de acceso a archivos u operaciones que no coincidan con el propósito declarado de la Skill
• Las fuentes externas son riesgosas: Las Skills que obtienen datos de URLs externas presentan un riesgo particular, ya que el contenido obtenido puede contener instrucciones maliciosas. Incluso las Skills confiables pueden ser comprometidas si sus dependencias externas cambian con el tiempo
• Mal uso de herramientas: Las Skills maliciosas pueden invocar herramientas (operaciones de archivo, comandos bash, ejecución de código) de formas dañinas
• Exposición de datos: Las Skills con acceso a datos sensibles podrían estar diseñadas para filtrar información a sistemas externos
• Tratar como instalar software: Solo usa Skills de fuentes confiables. Ten especial cuidado al integrar Skills en sistemas de producción con acceso a datos sensibles u operaciones críticas

Available Skills

Agent Skills pre-construidas

Las siguientes Agent Skills pre-construidas 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, formatear texto
• PDF (pdf): Generar documentos PDF formateados e informes

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

Ejemplos de Custom Skills

Para ejemplos completos de Custom Skills, consulta el Skills cookbook.

Limitaciones y restricciones

Comprender estas limitaciones te ayuda a planificar tu implementación de Skills de manera efectiva.

Disponibilidad entre superficies

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

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

Necesitarás administrar y cargar Skills por separado para cada superficie donde desees usarlas.

Alcance de compartición

Las Skills tienen diferentes modelos de compartición dependiendo de dónde las uses:

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

Claude.ai actualmente no admite administración centralizada de administrador o distribución en toda la organización de Custom Skills.

Restricciones del entorno de ejecución

El entorno de ejecución exacto disponible para tu skill depende de la superficie del producto donde la uses.

• Claude.ai:
  • Acceso de red variable: Dependiendo de la configuración del usuario/administrador, las Skills pueden tener acceso de red completo, parcial o nulo. Para más detalles, consulta el artículo de soporte Create and Edit Files.
• Claude API:
  • Sin acceso de red: Las Skills no pueden hacer llamadas de API externas ni acceder a internet
  • Sin instalación de paquetes en tiempo de ejecución: Solo están disponibles paquetes preinstalados. No puedes instalar nuevos paquetes durante la ejecución.
  • Solo dependencias preconfiguradas: Consulta la documentación de la herramienta de ejecución de código para obtener la lista de paquetes disponibles
• Claude Code:
  • Acceso de red completo: Las Skills tienen el mismo acceso de red que cualquier otro programa en la computadora del usuario
  • Instalación de paquetes global desaconsejada: Las Skills solo deben instalar paquetes localmente para evitar interferir con la computadora del usuario

Planifica tus Skills para que funcionen dentro de estas restricciones.

Próximos pasos