SpyBara
Go Premium

agent-sdk/skills.md 2026-09-13 21:00 UTC to 2026-09-14 22:58 UTC

This page contains 3 additions and 3 deletions.

2026
Wed 9 22:58 Mon 14 22:58 Fri 18 23:58

Extienda agentes con skills

Controle qué skills puede invocar Claude en sesiones del Claude Agent SDK, despache comandos por nombre y cree skills que sus sesiones descubran

Agent Skills extienden Claude con capacidades especializadas que Claude invoca cuando es relevante. Las Skills se empaquetan como archivos SKILL.md que contienen instrucciones, descripciones y recursos de apoyo opcionales. Esta página también cubre comandos en sesiones del Agent SDK.

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 Agent SDK

Cuando se utiliza el Claude Agent SDK, las skills son:

  • Definidas como artefactos del sistema de archivos: crea cada skill como un archivo SKILL.md en su propio directorio, como .claude/skills/<name>/SKILL.md
  • Cargadas desde el sistema de archivos: el SDK carga skills desde ubicaciones del sistema de archivos gobernadas por settingSources (TypeScript) o setting_sources (Python)
  • Descubiertas automáticamente: una vez que se cargan las configuraciones del sistema de archivos, el SDK descubre metadatos de skills al inicio desde directorios de usuario y proyecto, y carga el contenido completo cuando Claude invoca la skill
  • Invocadas por el modelo: Claude elige autónomamente cuándo usarlas según el contexto
  • Invocadas por el usuario: despache una skill directamente enviando /<name> en un prompt. Consulte Comandos en sesiones del Agent SDK
  • Limitadas 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 qué skills puede invocar Claude

A diferencia de los subagentes, que puede definir en la opción agents, crea skills como archivos en disco. El SDK no proporciona una API programática para registrarlas.

Use skills con el Agent SDK

Establezca la opción skills en query() para controlar qué skills puede invocar Claude en 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 permitir que Claude invoque cada skill descubierta, una lista de nombres de skills para permitir solo esos, o [] para que Claude no invoque ninguno.

Por ejemplo, para permitir que Claude invoque solo dos skills nombradas:

options = ClaudeAgentOptions(skills=["pdf", "docx"])

Configure skills en una sesión

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 las que son relevantes para la solicitud del usuario.

El siguiente ejemplo habilita cada skill descubierta en una sesión y preaprueba las herramientas que las skills comúnmente necesitan. El ejemplo establece cwd al directorio de trabajo actual del proceso, así que ejecútelo desde dentro de un proyecto que tenga un directorio .claude/skills/ en el directorio actual o cualquier padre hasta la raíz del repositorio:

import asyncio
import os

from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
options = ClaudeAgentOptions(
cwd=os.getcwd(),  # .claude/skills/ here or in a parent directory
setting_sources=["user", "project"],  # Load skills from filesystem
skills="all",  # Let Claude invoke 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())

Confirme que las skills se cargaron

Cerca del inicio del stream, el SDK produce un mensaje del sistema con subtipo init. Verifique su matriz skills para confirmar que sus skills se cargaron antes de que Claude comience a trabajar. La matriz incluye las skills invocables por el usuario que ha definido con un campo frontmatter description o when_to_use, junto con skills incluidas en Claude Code.

La matriz lista solo skills invocables por el usuario. Una skill con user-invocable: false en su frontmatter se carga y permanece disponible para Claude, pero no aparece en la matriz. La matriz lista las mismas skills independientemente de si están en su lista skills.

Permita solo skills específicas

Para permitir que Claude invoque solo skills específicas, pase sus nombres en la lista skills. 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.

La lista toma solo nombres exactos de skills. Si una entrada no puede funcionar como un nombre exacto, query() rechaza la lista antes de que comience la sesión. Consulte Error de nombre de skill inválido para las reglas de nombre y el error que cada SDK genera.

El modelo no ve skills no listadas y la herramienta Skill las rechaza, mientras que sus archivos permanecen en disco y permanecen accesibles a través de Read y Bash. Restringir la lista no restringe despacho por nombre.

Para permitir que Claude invoque cada skill descubierta, pase skills: "all" en lugar de un comodín.

Comandos en sesiones del Agent SDK

Esta sección es la documentación de comandos del SDK. Un comando es cualquier cosa que ejecute enviando /<name> en un prompt. Las entradas en la superficie del comando difieren en lo que las respalda:

  • Comandos integrados: ejecutan lógica codificada en el proceso de Claude Code que ejecuta el SDK, por ejemplo /compact
  • Skills incluidas: artefactos de prompt incluidos con Claude Code, por ejemplo /code-review
  • Sus skills: artefactos de prompt que crea, cada uno un directorio que contiene un archivo SKILL.md. El nombre de una skill invocable por el usuario se une a la superficie automáticamente, así que despachar su propio /security-check y ejecutar uno integrado funcionan de la misma manera
  • Archivos de comando personalizados: una forma de artefacto más antigua con el mismo comportamiento, archivos Markdown planos en .claude/commands/ cuyos nombres de archivo se convierten en nombres de comando. Las skills son su sucesor recomendado

De forma predeterminada, tanto usted como Claude pueden invocar cualquier skill. Puede restringir cualquiera de las dos rutas a través del frontmatter de la skill. Para una definición de los dos términos, consulte las entradas Comando y Skill del glosario. Consulte Comandos en Claude Code para cada uno integrado y Extienda Claude con skills para la guía completa de ambas formas de artefacto.

Descubra comandos disponibles

Puede despachar comandos que funcionan sin una terminal interactiva a través del SDK. El mensaje system/init lista los disponibles en su sesión en su campo slash_commands. Los comandos que necesitan una terminal interactiva, como /theme y /terminal-setup, no aparecen en la lista. Acceda al campo cuando su sesión comience:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
prompt: "Hello Claude",
options: { maxTurns: 1 }
})) {
if (message.type === "system" && message.subtype === "init") {
console.log("Available commands:", message.slash_commands);
}
}

La lista impresa mezcla comandos integrados, skills incluidas, sus skills invocables por el usuario y archivos .claude/commands/:

Available commands: ["clear", "compact", "context", "usage", "code-review", "verify", "security-check", ...]

Una skill con user-invocable: false en su frontmatter no aparece en esta lista ni en la matriz skills de Confirme que las skills se cargaron. Las sesiones que configuran servidores MCP también pueden exponer prompts MCP como comandos.

Despache comandos por nombre

Envíe un comando incluyéndolo en su cadena de prompt, de la misma manera que envía texto regular. El despacho no depende de la opción skills. Enviar /<name> ejecuta una skill invocable por el usuario incluso cuando su lista skills la omite. Los comandos que actúan en el historial de conversación, como /compact, necesitan mensajes previos para trabajar.

Compacte el historial con `/compact`

El comando /compact reduce el tamaño de su historial de conversación resumiendo mensajes más antiguos mientras preserva contexto importante. La compactación necesita una conversación existente con suficientes mensajes previos para resumir. Este ejemplo tiene una conversación primero, luego la compacta y lee el mensaje del sistema compact_boundary que reporta el resultado:

import { query } from "@anthropic-ai/claude-agent-sdk";

// Compaction needs existing history, so have a conversation first
try {
for await (const message of query({
prompt: "Explain what this project does",
options: { maxTurns: 2 }
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}
} catch (error) {
// A single-shot query() throws after yielding an error result,
// so the follow-up query below still runs.
console.error(`Session ended with an error: ${error}`);
}

// Compact the same conversation
for await (const message of query({
prompt: "/compact",
options: { continue: true, maxTurns: 1 }
})) {
if (message.type === "system" && message.subtype === "compact_boundary") {
console.log("Compaction completed");
console.log("Pre-compaction tokens:", message.compact_metadata.pre_tokens);
console.log("Trigger:", message.compact_metadata.trigger);
// Example output:
// Compaction completed
// Pre-compaction tokens: 1842
// Trigger: manual
}
}

Reinicie el contexto con `/clear`

El comando /clear reinicia la conversación a un contexto vacío, así que los prompts posteriores comienzan sin historial de conversación previo. La conversación anterior permanece en disco. Puede volver a esa conversación pasando su ID de sesión a la opción resume.

/clear es útil en modo de entrada de streaming, donde envía múltiples prompts sobre una sola conexión. Para llamadas query() de un solo disparo, cada llamada ya comienza con contexto vacío, así que enviar /clear no tiene efecto práctico. Comience una nueva query() en su lugar.

Cree skills

Cree cada skill como un directorio que contiene 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/security-check/
└── SKILL.md

Elija un nivel de descubrimiento

Guarde skills en uno de los dos niveles de descubrimiento más comunes:

  • Skills de proyecto: .claude/skills/, disponibles solo en el proyecto actual
  • Skills personales: ~/.claude/skills/, disponibles en todos sus proyectos

Si tiene archivos de comando personalizados existentes en .claude/commands/, siguen funcionando. Un archivo de comando en .claude/commands/deploy.md crea /deploy y funciona de la misma manera que una skill en .claude/skills/deploy/SKILL.md lo haría. Si un archivo de comando y una skill comparten un nombre, consulte Resuelva skills que comparten un nombre para saber cuál se ejecuta. El SDK carga archivos .claude/commands/ y ~/.claude/commands/ desde los mismos dos ámbitos que las skills. Consulte Extienda Claude con skills para la guía completa de ambas formas de artefacto.

Cree y despache su primera skill

Para ver el flujo completo, cree .claude/skills/security-check/SKILL.md:

---
name: security-check
description: Run a security vulnerability scan
---

Analyze the codebase for security vulnerabilities including:
- SQL injection risks
- XSS vulnerabilities
- Exposed credentials
- Insecure configurations

Una vez que el archivo existe, la skill está disponible a través del SDK. Claude la invoca cuando una solicitud coincide con su descripción, y puede despatcharla directamente:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
prompt: "/security-check",
options: { maxTurns: 10 }
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}

Una ejecución exitosa termina con un resultado success cuyo texto lleva los hallazgos del escaneo. Contra una pequeña aplicación Express con problemas sembrados, el texto del resultado comienza:

**Security scan of `app.js` — 4 findings (most severe first):**

1. **SQL Injection** (line 8) — `req.query.name` is concatenated directly into the SQL string. Trivially exploitable (`' OR '1'='1`, `'; DROP TABLE users;--`). **Fix:** use parameterized queries, e.g. `db.query("SELECT * FROM users WHERE name = ?", [req.query.name], cb)`.
...

El nombre de la skill también aparece en la matriz slash_commands del mensaje init.

Preapruebe herramientas para skills

Las skills se ejecutan con las herramientas de la sesión. El ejemplo a continuación preaprueba Read, Grep y Glob con allowedTools (allowed_tools en Python), así que Claude puede inspeccionar archivos mientras ejecuta la skill security-check sin detenerse para aprobación:

import asyncio

from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(
setting_sources=["user", "project"],  # Load skills from filesystem
skills="all",
allowed_tools=["Read", "Grep", "Glob"],
)


async def main():
async for message in query(prompt="Check this project for security issues", options=options):
print(message)


asyncio.run(main())

En el stream, la invocación de la skill aparece como un uso de herramienta Skill, seguido de llamadas Read en los archivos del proyecto. La ejecución termina con un resultado success cuyo texto lleva los hallazgos.

La lista preaprueba las herramientas nombradas en lugar de restringir las otras. Para el flujo de permisos completo, incluidos modos de permiso y la devolución de llamada canUseTool, consulte Permisos.

Solución de problemas

Skills no encontradas

Verifique la configuración de settingSources: el SDK descubre skills a través de las fuentes de configuración user y project. Si establece settingSources/setting_sources explícitamente y omite esas fuentes, el SDK no carga skills:

# 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 saber qué directorios de skills carga cada fuente, consulte la tabla de fuentes del sistema de archivos. 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 Use skills con el Agent SDK 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. Cuando Claude intenta invocar una skill no listada, la herramienta Skill devuelve Skill <name> is not in this session's skills allowlist. Añada el nombre a su lista, o despache la skill directamente enviando /<name> en un prompt, que funciona sin listar.

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.

Error de nombre de skill inválido

Cuando un nombre en su lista skills no puede funcionar como un nombre exacto de skill, query() rechaza la lista antes de iniciar el proceso de Claude Code. Los nombres que desencadenan el rechazo incluyen:

  • Un nombre vacío
  • Un nombre que contiene paréntesis, comas o caracteres de control
  • Un nombre relleno con espacios en blanco
  • Una forma de comodín como un * desnudo o un sufijo :*

Cada SDK presenta el rechazo de manera diferente:

El SDK de TypeScript lanza un Error indicando la regla que la entrada rompió. Por ejemplo, skills: ["docs:*"] lanza:

Invalid skill name "docs:*": wildcard-suffix names are not allowed; list each skill by its exact name.

Un nombre vacío reporta Skill names must be non-empty strings.

Antes de TypeScript Agent SDK 0.3.221, el SDK no ejecutaba esta verificación.

Solución de problemas adicional

Para la solución de problemas general de skills, como errores de sintaxis YAML y depuración, consulte la sección de solución de problemas de skills de Claude Code.

Próximos pasos

La guía de skills de Claude Code cubre la autoría en profundidad. Su orientación se aplica a sesiones del SDK. Comience con estas secciones: