Agent Skills en el SDK

Descripción general

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

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

Cómo funcionan las Skills con el SDK

Cuando se utiliza el Claude Agent SDK, las Skills 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 Skills se cargan desde ubicaciones del sistema de archivos configuradas. Debes especificar settingSources (TypeScript) o setting_sources (Python) para cargar Skills desde el sistema de archivos
3. Descubiertas automáticamente: Una vez que se cargan las configuraciones del sistema de archivos, los metadatos de Skill 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 mediante allowed_tools: Agrega "Skill" a tu allowed_tools para habilitar Skills

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

Uso de Skills con el SDK

Para usar Skills con el SDK, necesitas:

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

Una vez configurado, Claude descubre automáticamente Skills desde los directorios especificados e los 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 Skills

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

• Project Skills (.claude/skills/): Compartidas con tu equipo a través de git - se cargan cuando setting_sources incluye "project"
• User Skills (~/.claude/skills/): Skills personales en todos los proyectos - se cargan cuando setting_sources incluye "user"
• Plugin Skills: Incluidas con los complementos instalados de Claude Code

Creación de Skills

Las Skills 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 Skill.

Estructura de directorio de ejemplo:

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

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

• Agent Skills en Claude Code: Guía completa con ejemplos
• Agent Skills Best Practices: Directrices de autoría y convenciones de nomenclatura

Restricciones de herramientas

Para restringir herramientas para Skills en aplicaciones SDK, utiliza 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)

Descubrimiento de Skills disponibles

Para ver qué Skills 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 Skills disponibles según tu directorio de trabajo actual y complementos instalados.

Prueba de Skills

Prueba Skills 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 Skill relevante si la descripción coincide con tu solicitud.

Solución de problemas

Skills no encontradas

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

# Wrong - Skills won't be loaded
options = ClaudeAgentOptions(
    allowed_tools=["Skill"]
)

# Correct - Skills will be loaded
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 Skills en relación con la opción cwd. Asegúrate de que apunte a un directorio que contenga .claude/skills/:

# Ensure your cwd points to the directory containing .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 "Uso de Skills 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

Skill no se está utilizando

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 Agent Skills Best Practices para obtener orientación sobre cómo escribir descripciones efectivas.

Solución de problemas adicional

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

Documentación relacionada

Guías de Skills

• Agent Skills en Claude Code: Guía completa de Skills con creación, ejemplos y solución de problemas
• Agent Skills Overview: Descripción general conceptual, beneficios y arquitectura
• Agent Skills Best Practices: Directrices de autoría para Skills efectivas
• Agent Skills Cookbook: Skills de ejemplo y plantillas

Recursos del SDK

• Subagents in the SDK: Agentes similares basados en el sistema de archivos con opciones programáticas
• Slash Commands in the SDK: Comandos invocados por el usuario
• SDK Overview: Conceptos generales del SDK
• TypeScript SDK Reference: Documentación completa de la API
• Python SDK Reference: Documentación completa de la API