Habilidades de Agente en el SDK

Descripción General

Las Habilidades de Agente extienden Claude con capacidades especializadas que Claude invoca autónomamente cuando es relevante. Las Habilidades se empaquetan como archivos SKILL.md que contienen instrucciones, descripciones y recursos de apoyo opcionales.

Para obtener información completa sobre Habilidades, incluidos beneficios, arquitectura y directrices de autoría, consulta la descripción general de Habilidades de Agente.

Cómo funcionan las Habilidades con el SDK

Cuando se utiliza el SDK del Agente Claude, las Habilidades son:

1. Definidas como artefactos del sistema de archivos: Creadas como archivos SKILL.md en directorios específicos (.claude/skills/)
2. Cargadas desde el sistema de archivos: Las Habilidades se cargan desde ubicaciones del sistema de archivos configuradas. Debes especificar settingSources (TypeScript) o setting_sources (Python) para cargar Habilidades desde el sistema de archivos
3. Descubiertas automáticamente: Una vez que se cargan las configuraciones del sistema de archivos, los metadatos de Habilidades se descubren al inicio desde directorios de usuario y proyecto; el contenido completo se carga cuando se activa
4. Invocadas por el modelo: Claude elige autónomamente cuándo usarlas según el contexto
5. Habilitadas a través de allowed_tools: Agrega "Skill" a tu allowed_tools para habilitar Habilidades

A diferencia de los subagentes (que se pueden definir programáticamente), las Habilidades deben crearse como artefactos del sistema de archivos. El SDK no proporciona una API programática para registrar Habilidades.

Usando Habilidades con el SDK

Para usar Habilidades con el SDK, necesitas:

1. Incluir "Skill" en tu configuración de allowed_tools
2. Configurar settingSources/setting_sources para cargar Habilidades desde el sistema de archivos

Una vez configurado, Claude descubre automáticamente Habilidades desde los directorios especificados e las invoca cuando son relevantes para la solicitud del usuario.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    options = ClaudeAgentOptions(
        cwd="/path/to/project",  # Project with .claude/skills/
        setting_sources=["user", "project"],  # Load Skills from filesystem
        allowed_tools=["Skill", "Read", "Write", "Bash"]  # Enable Skill tool
    )

    async for message in query(
        prompt="Help me process this PDF document",
        options=options
    ):
        print(message)

asyncio.run(main())

Ubicaciones de Habilidades

Las Habilidades se cargan desde directorios del sistema de archivos según tu configuración de settingSources/setting_sources:

• Habilidades de Proyecto (.claude/skills/): Compartidas con tu equipo a través de git - cargadas cuando setting_sources incluye "project"
• Habilidades de Usuario (~/.claude/skills/): Habilidades personales en todos los proyectos - cargadas cuando setting_sources incluye "user"
• Habilidades de Plugin: Incluidas con los plugins de Claude Code instalados

Creando Habilidades

Las Habilidades se definen como directorios que contienen un archivo SKILL.md con frontmatter YAML y contenido Markdown. El campo description determina cuándo Claude invoca tu Habilidad.

Estructura de directorio de ejemplo:

.claude/skills/processing-pdfs/
└── SKILL.md

Para obtener orientación completa sobre la creación de Habilidades, incluida la estructura de SKILL.md, Habilidades de múltiples archivos y ejemplos, consulta:

• Habilidades de Agente en Claude Code: Guía completa con ejemplos
• Mejores Prácticas de Habilidades de Agente: Directrices de autoría y convenciones de nomenclatura

Restricciones de Herramientas

Para restringir herramientas para Habilidades en aplicaciones SDK, usa la opción allowedTools:

options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # Load Skills from filesystem
    allowed_tools=["Skill", "Read", "Grep", "Glob"]  # Restricted toolset
)

async for message in query(
    prompt="Analyze the codebase structure",
    options=options
):
    print(message)

Descubriendo Habilidades Disponibles

Para ver qué Habilidades están disponibles en tu aplicación SDK, simplemente pregúntale a Claude:

options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # Load Skills from filesystem
    allowed_tools=["Skill"]
)

async for message in query(
    prompt="What Skills are available?",
    options=options
):
    print(message)

Claude listará las Habilidades disponibles según tu directorio de trabajo actual y plugins instalados.

Probando Habilidades

Prueba Habilidades haciendo preguntas que coincidan con sus descripciones:

options = ClaudeAgentOptions(
    cwd="/path/to/project",
    setting_sources=["user", "project"],  # Load Skills from filesystem
    allowed_tools=["Skill", "Read", "Bash"]
)

async for message in query(
    prompt="Extract text from invoice.pdf",
    options=options
):
    print(message)

Claude invoca automáticamente la Habilidad relevante si la descripción coincide con tu solicitud.

Solución de Problemas

Habilidades No Encontradas

Verifica la configuración de settingSources: Las Habilidades solo se cargan cuando configuras explícitamente settingSources/setting_sources. Este es el problema más común:

# Incorrecto - Las Habilidades no se cargarán
options = ClaudeAgentOptions(
    allowed_tools=["Skill"]
)

# Correcto - Las Habilidades se cargarán
options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # Required to load Skills
    allowed_tools=["Skill"]
)

Para más detalles sobre settingSources/setting_sources, consulta la referencia del SDK de TypeScript o la referencia del SDK de Python.

Verifica el directorio de trabajo: El SDK carga Habilidades relativas a la opción cwd. Asegúrate de que apunte a un directorio que contenga .claude/skills/:

# Asegúrate de que tu cwd apunte al directorio que contiene .claude/skills/
options = ClaudeAgentOptions(
    cwd="/path/to/project",  # Must contain .claude/skills/
    setting_sources=["user", "project"],  # Required to load Skills
    allowed_tools=["Skill"]
)

Consulta la sección "Usando Habilidades con el SDK" anterior para el patrón completo.

Verifica la ubicación del sistema de archivos:

# Check project Skills
ls .claude/skills/*/SKILL.md

# Check personal Skills
ls ~/.claude/skills/*/SKILL.md

Habilidad No Siendo Usada

Verifica que la herramienta Skill esté habilitada: Confirma que "Skill" está en tu allowedTools.

Verifica la descripción: Asegúrate de que sea específica e incluya palabras clave relevantes. Consulta Mejores Prácticas de Habilidades de Agente para obtener orientación sobre cómo escribir descripciones efectivas.

Solución de Problemas Adicional

Para la solución de problemas general de Habilidades (sintaxis YAML, depuración, etc.), consulta la sección de solución de problemas de Habilidades de Claude Code.

Documentación Relacionada

Guías de Habilidades

• Habilidades de Agente en Claude Code: Guía completa de Habilidades con creación, ejemplos y solución de problemas
• Descripción General de Habilidades de Agente: Descripción conceptual, beneficios y arquitectura
• Mejores Prácticas de Habilidades de Agente: Directrices de autoría para Habilidades efectivas
• Libro de Recetas de Habilidades de Agente: Habilidades de ejemplo y plantillas

Recursos del SDK

• Subagentes en el SDK: Agentes similares basados en sistema de archivos con opciones programáticas
• Comandos Slash en el SDK: Comandos invocados por el usuario
• Descripción General del SDK: Conceptos generales del SDK
• Referencia del SDK de TypeScript: Documentación completa de la API
• Referencia del SDK de Python: Documentación completa de la API