Skills

Skills vs. herramientas

Vale la pena tener claro la diferencia, porque ambas resuelven problemas distintos:

• Las herramientas conectan a Claude con datos y acciones. "Busca esta sección de código", "envía este correo" — Claude llama a la herramienta, y algo más se ejecuta.
• Las Skills le enseñan a Claude un procedimiento. "Genera el informe de estado diario siguiendo esta plantilla" — es un manual que Claude lee y sigue, lo que a veces implica ejecutar scripts incluidos él mismo.

Una forma sencilla de recordarlo: las herramientas se tratan de qué puede hacer Claude, mientras que las Skills se tratan de cómo quieres que se haga.



Otra cosa que vale la pena saber: las Skills no se cargan por completo en el contexto al inicio. Solo el nombre y la descripción se cargan al principio. Cuando tu agente decide que una Skill es relevante, entonces carga la Skill completa en el contexto. Eso mantiene tu contexto ligero incluso cuando hay muchas Skills disponibles.

Subir una Skill

Las Skills se suben una vez a tu espacio de trabajo y luego se referencian por ID. Puedes subirlas directamente en la Claude Platform, o hacerlo de forma programática:

skill = client.skills.create(
    display_name="Status Report Generator",
    files=files_from_dir("status-report-skill"),  # folder containing SKILL.md
)

print(skill.id)  # reference this ID in future requests

Para este ejemplo, quiero un generador de informes de estado. Todas las reglas sobre qué hace que un buen informe de estado — secciones, tono, cómo resumir, cómo manejar los bloqueos — viven en una Skill empaquetada de antemano. El registro de actividad en sí es solo una cadena de texto que se pasa en el momento de la solicitud.

Adjuntar una Skill a una solicitud

Las Skills se adjuntan a una solicitud a través de la configuración del contenedor — un arreglo skills dentro del contenedor, donde cada entrada nombra un skill_id y una version. Aquí está la llamada completa para el generador de informes de estado:

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    container={
        "skills": [
            {
                "type": "custom",
                "skill_id": skill.id,
                "version": "latest",
            }
        ]
    },
    tools=[
        {
            "type": "code_execution_20250825",
            "name": "code_execution",
        }
    ],
    messages=[
        {
            "role": "user",
            "content": f"Generate the daily status report from this activity log:\n\n{activity_log}",
        }
    ],
)

Algunas cosas que vale la pena señalar:

• Estamos llamando al client.messages.create estándar, sin encabezado beta. Las Skills están disponibles de forma general en la API de Claude, por lo que el encabezado beta skills-2025-10-02 ya no es necesario; las solicitudes que aún lo envían siguen funcionando sin cambios.
• container.skills es donde se adjunta la Skill. Es una lista, así que puedes combinar varias Skills en una sola llamada.
• La ejecución de código también está activada aquí. Es obligatoria: en la API, las Skills se ejecutan dentro del contenedor de la herramienta de ejecución de código, que es lo que permite que los procedimientos de las Skills realicen trabajo real — como ejecutar scripts en una terminal.

Ejecutándolo

El resultado es un informe de estado formateado exactamente de la manera en que la Skill indica que debe formatearse. Secciones, tono, manejo de bloqueos — todo proviene del archivo SKILL.md que subiste. El prompt del usuario es una sola línea; el procedimiento vive en la Skill.



En una aplicación de producción, así es como un equipo estandariza la salida en toda una funcionalidad. Con este endpoint de informe de estado diario, cada PM obtiene la misma estructura, el mismo tono, las mismas secciones, en el mismo orden — sin que nadie tenga que copiar y pegar una plantilla en un prompt.



Resumen

• Las Skills empaquetan tus procedimientos. Un archivo SKILL.md (más cualquier script y recurso) le enseña a Claude cómo quieres que se haga algo.
• Herramientas vs. Skills: las herramientas se tratan de qué puede hacer Claude; las Skills se tratan de cómo quieres que se haga.
• Las Skills se cargan progresivamente. Solo el nombre y la descripción se cargan al inicio; la Skill completa se carga en el contexto cuando el agente decide usarla.
• Sube una vez con client.skills.create, luego adjunta con container.skills en cualquier llamada messages.create — una lista, así que puedes combinar varias Skills.
• Combínala con la ejecución de código cuando el procedimiento de la Skill necesite realizar trabajo real.
• Recurre a una Skill cuando el cómo importa tanto como el qué.