Saltar al contenido principal

​
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, consulte 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 gobernadas por settingSources (TypeScript) o setting_sources (Python)
  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. Filtradas a través de la opción skills: Las Skills descubiertas están habilitadas de forma predeterminada. Pase una lista de nombres de Skills, "all", o [] para controlar cuáles están disponibles en la sesión
A diferencia de los subagentes (que se pueden definir mediante programación), las Skills deben crearse como artefactos del sistema de archivos. El SDK no proporciona una API programática para registrar Skills.
Las Skills se descubren a través de las fuentes de configuración del sistema de archivos. Con las opciones predeterminadas de query(), el SDK carga fuentes de usuario y proyecto, por lo que las Skills en ~/.claude/skills/, <cwd>/.claude/skills/, y .claude/skills/ en cualquier directorio padre de <cwd> hasta la raíz del repositorio están disponibles. Si establece settingSources explícitamente, incluya 'user' o 'project' para mantener el descubrimiento de Skills, o use la opción plugins para cargar Skills desde una ruta específica.

​
Uso de Skills con el SDK

Establezca la opción skills en query() para controlar qué Skills están disponibles para la sesión. Cuando se omite, las Skills descubiertas están habilitadas y la herramienta Skill está disponible, coincidiendo con el comportamiento de CLI. Pase "all" para habilitar cada Skill descubierta, una lista de nombres de Skill para habilitar solo esos, o [] para deshabilitar todos. Cuando establece skills, el SDK añade la herramienta Skill a allowedTools automáticamente. Si también pasa una lista explícita de tools, incluya "Skill" en esa lista para que Claude pueda invocar skills. Una vez configurado, Claude descubre automáticamente Skills desde el sistema de archivos e invoca los cuando es relevante 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
        skills="all",  # Enable every discovered Skill
        allowed_tools=["Read", "Write", "Bash"],
    )

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


asyncio.run(main())
Para habilitar solo Skills específicas, pase sus nombres. Los nombres coinciden con el campo name en SKILL.md o el nombre del directorio de la Skill. Use plugin:skill para Skills proporcionadas por plugins. 
options = ClaudeAgentOptions(skills=["pdf", "docx"])
La opción skills es un filtro de contexto, no un sandbox. Las Skills no listadas se ocultan del modelo y se rechazan por la herramienta Skill, pero sus archivos permanecen en el disco y son accesibles a través de Read y Bash.

​
Ubicaciones de Skills

Las Skills se cargan desde directorios del sistema de archivos según su configuración settingSources/setting_sources:
  • Project Skills (.claude/skills/): Compartidas con su equipo a través de git - cargadas cuando setting_sources incluye "project"
  • User Skills (~/.claude/skills/): Skills personales en todos los proyectos - cargadas cuando setting_sources incluye "user"
  • Plugin Skills: Incluidas con plugins de Claude Code instalados

​
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 su 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, consulte:

​
Restricciones de herramientas

El campo frontmatter allowed-tools en SKILL.md solo se admite cuando se utiliza directamente la CLI de Claude Code. No se aplica cuando se utilizan Skills a través del SDK.Cuando se utiliza el SDK, controle el acceso a herramientas a través de la opción principal allowedTools en su configuración de consulta.
Para controlar el acceso a herramientas para Skills en aplicaciones SDK, use allowedTools para preautorizar herramientas específicas. Sin una devolución de llamada canUseTool, se deniega cualquier cosa que no esté en la lista:
Se asume que las declaraciones de importación del primer ejemplo están en los siguientes fragmentos de código.
options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # Load Skills from filesystem
    skills="all",
    allowed_tools=["Read", "Grep", "Glob"],
)

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 su aplicación SDK, simplemente pregunte a Claude: 
options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # Load Skills from filesystem
    skills="all",
)

async for message in query(prompt="What Skills are available?", options=options):
    print(message)
Claude listará las Skills disponibles según su directorio de trabajo actual y plugins instalados.

​
Prueba de Skills

Pruebe Skills haciendo preguntas que coincidan con sus descripciones: 
options = ClaudeAgentOptions(
    cwd="/path/to/project",
    setting_sources=["user", "project"],  # Load Skills from filesystem
    skills="all",
    allowed_tools=["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 su solicitud.

​
Solución de problemas

​
Skills no encontradas

Verifique la configuración de settingSources: Las Skills se descubren a través de las fuentes de configuración user y project. Si establece settingSources/setting_sources explícitamente y omite esas fuentes, las Skills no se cargan: 
# Skills not loaded: setting_sources excludes user and project
options = ClaudeAgentOptions(setting_sources=[], skills="all")

# Skills loaded: user and project sources included
options = ClaudeAgentOptions(
    setting_sources=["user", "project"],
    skills="all",
)
Para más detalles sobre settingSources/setting_sources, consulte la referencia del SDK de TypeScript o la referencia del SDK de Python. Verifique el directorio de trabajo: El SDK carga Skills desde .claude/skills/ en la opción cwd y en cada directorio padre hasta la raíz del repositorio. Asegúrese de que cwd apunte a o esté por debajo del directorio que contiene .claude/skills/, dentro del mismo repositorio: 
# Ensure your cwd points to the directory containing .claude/skills/
options = ClaudeAgentOptions(
    cwd="/path/to/project",  # .claude/skills/ here or in a parent directory
    setting_sources=["user", "project"],  # Loads skills from these sources
    skills="all",
)
Consulte la sección “Uso de Skills con el SDK” anterior para el patrón completo. Verifique 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

Verifique la opción skills: Si pasó una lista de skills, confirme que el nombre de la Skill está incluido. Pasar [] deshabilita todas las Skills. Verifique la descripción: Asegúrese de que sea específica e incluya palabras clave relevantes. Consulte Agent Skills Best Practices para obtener orientación sobre cómo escribir descripciones efectivas.

​
Solución de problemas adicional

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

​
Documentación relacionada

​
Guías de Skills

​
Recursos del SDK