Agent Skills en el SDK
Extienda Claude con capacidades especializadas utilizando Agent Skills en el Claude Agent 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, 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:
- Definidas como artefactos del sistema de archivos: Creadas como archivos
SKILL.mden directorios específicos (.claude/skills/) - Cargadas desde el sistema de archivos: Las Skills se cargan desde ubicaciones del sistema de archivos gobernadas por
settingSources(TypeScript) osetting_sources(Python) - 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
- Invocadas por el modelo: Claude elige autónomamente cuándo usarlas según el contexto
- 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.
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 habilita la herramienta Skill automáticamente, por lo que no necesita incluirla en allowedTools.
Una vez configurado, Claude descubre automáticamente Skills desde el sistema de archivos e las invoca 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())
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Help me process this PDF document",
options: {
cwd: "/path/to/project", // Project with .claude/skills/
settingSources: ["user", "project"], // Load Skills from filesystem
skills: "all", // Enable every discovered Skill
allowedTools: ["Read", "Write", "Bash"]
}
})) {
console.log(message);
}
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"])
const options = { 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 cuandosetting_sourcesincluye"project" - User Skills (
~/.claude/skills/): Skills personales en todos los proyectos - cargadas cuandosetting_sourcesincluye"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:
- 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 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:
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)
for await (const message of query({
prompt: "Analyze the codebase structure",
options: {
settingSources: ["user", "project"], // Load Skills from filesystem
skills: "all",
allowedTools: ["Read", "Grep", "Glob"],
permissionMode: "dontAsk" // Deny anything not in allowedTools
}
})) {
console.log(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)
for await (const message of query({
prompt: "What Skills are available?",
options: {
settingSources: ["user", "project"], // Load Skills from filesystem
skills: "all"
}
})) {
console.log(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)
for await (const message of query({
prompt: "Extract text from invoice.pdf",
options: {
cwd: "/path/to/project",
settingSources: ["user", "project"], // Load Skills from filesystem
skills: "all",
allowedTools: ["Read", "Bash"]
}
})) {
console.log(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",
)
// Skills not loaded: settingSources excludes user and project
const options = {
settingSources: [],
skills: "all"
};
// Skills loaded: user and project sources included
const options = {
settingSources: ["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 relativas a la opción cwd. Asegúrese 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"], # Loads skills from these sources
skills="all",
)
// Ensure your cwd points to the directory containing .claude/skills/
const options = {
cwd: "/path/to/project", // Must contain .claude/skills/
settingSources: ["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
- 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 en el SDK: Agentes similares basados en el sistema de archivos con opciones programáticas
- Slash Commands 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