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 más información 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 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.

[!NOTE]

Las skills se descubren a través de las fuentes de configuración del sistema de archivos. Con 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. La fuente del proyecto también cubre <dir>/.claude/skills/ en cada directorio que pase a través de additionalDirectories (TypeScript) o add_dirs (Python), porque el SDK pasa esos directorios a Claude Code como --add-dir. Si establece settingSources explícitamente, incluya 'project' para mantener las skills de proyecto y directorio agregado e 'user' para mantener sus skills personales, o use la opción plugins para cargar skills desde una ruta específica.

Usa skills con el Agent SDK

Establece la opción skills en query() para controlar qué skills puede invocar Claude en la sesión. Cuando se omite, los skills descubiertos están habilitados y la herramienta Skill está disponible, igual que en el comportamiento de la CLI. Pasa "all" para permitir que Claude invoque todos los skills descubiertos, 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 con nombre:

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

const options = { skills: ["pdf", "docx"] };

Configura skills en una sesión

Cuando estableces skills, el SDK añade la herramienta Skill a allowedTools automáticamente. Si también pasas una lista explícita de tools, incluye "Skill" en esa lista para que Claude pueda invocar skills.

Una vez configurado, Claude descubre automáticamente los skills desde el sistema de archivos y los invoca cuando son relevantes para la solicitud del usuario.

El siguiente ejemplo habilita todos los skills descubiertos en una sesión y preaprueba las herramientas que los skills suelen necesitar. El ejemplo establece cwd en el directorio de trabajo actual del proceso, así que ejecútalo desde dentro de un proyecto que tenga un directorio .claude/skills/ en el directorio actual o en cualquier directorio 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())

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

for await (const message of query({
  prompt: "Help me process this PDF document",
  options: {
    cwd: process.cwd(), // .claude/skills/ here or in a parent directory
    settingSources: ["user", "project"], // Load skills from filesystem
    skills: "all", // Let Claude invoke every discovered skill
    allowedTools: ["Read", "Write", "Bash"]
  }
})) {
  console.log(message);
}

Confirma que los skills se cargaron

Cerca del inicio del stream, el SDK produce un mensaje del sistema con subtipo init. Revisa su matriz skills para confirmar que tus skills se cargaron antes de que Claude comience a trabajar. La matriz incluye los skills invocables por el usuario que has definido con un campo de frontmatter description o when_to_use, junto con los skills incluidos con Claude Code.

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

Permite solo skills específicos

Para permitir que Claude invoque solo skills específicos, pasa sus nombres en la lista skills:

Tus propios skills: el nombre del directorio del skill
Skills de plugins: plugin:skill
Conflictos de nombres en additionalDirectories o add_dirs: un skill en uno de esos directorios recibe un nombre con prefijo cuando su nombre entra en conflicto con un skill empresarial, personal o de proyecto, o con uno de un directorio añadido antes. Inclúyelo en la lista con ese nombre. Con un skill verify en ../api y en ../web, añadidos en ese orden, y ningún otro skill verify, inclúyelos como verify y web:verify. Requiere Claude Code v2.1.309 o posterior

La lista acepta 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. Consulta Error de nombre de skill inválido para conocer las reglas de nombres y el error que genera cada SDK.

El modelo no ve los skills que no están en la lista y la herramienta Skill los rechaza, mientras que sus archivos permanecen en disco y siguen siendo accesibles a través de Read y Bash. Restringir la lista no restringe el despacho por nombre.

Para permitir que Claude invoque todos los skills descubiertos, pasa 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 definiciones de comando y skill, 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);
  }
}

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage


async def main():
    async for message in query(prompt="Hello Claude", options=ClaudeAgentOptions(max_turns=1)):
        if isinstance(message, SystemMessage) and message.subtype == "init":
            print("Available commands:", message.data["slash_commands"])


asyncio.run(main())

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.

Un /<name> que no coincida ni con un comando en la sesión ni con un comando integrado de Claude Code no falla la consulta. Claude Code envía el prompt a Claude como un mensaje ordinario, con una nota de que el comando no se ejecutó, así que la consulta gasta un turno de modelo y devuelve la respuesta de Claude. Antes de v2.1.274, un /<name> que no coincidía con nada devolvía Unknown command: /<name> como resultado sin un turno de modelo.

Un /<name> que coincida con un comando integrado de Claude Code que no está disponible en la sesión, como /theme, devuelve /theme isn't available in this environment. como resultado sin un turno de modelo.

[!NOTE]

Un comando puede alcanzar el límite maxTurns / max_turns como cualquier otro prompt, terminando la consulta con un resultado de error en lugar de success. Para el contrato de resultado de error, consulte Maneje el resultado. Si su comando podría alcanzar el límite, envuelva el bucle en un try/catch en TypeScript o try/except en Python, como se muestra en Entrada de mensaje único, o establezca maxTurns lo suficientemente alto para que el trabajo se complete.

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
  }
}

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage, SystemMessage


async def main():
    # Compaction needs existing history, so have a conversation first
    try:
        async for message in query(
            prompt="Explain what this project does",
            options=ClaudeAgentOptions(max_turns=2),
        ):
            if isinstance(message, ResultMessage) and message.subtype == "success":
                print(message.result)
    except Exception as error:
        # A single-shot query() raises after yielding an error result,
        # so the follow-up query below still runs.
        print(f"Session ended with an error: {error}")

    # Compact the same conversation
    async for message in query(
        prompt="/compact",
        options=ClaudeAgentOptions(continue_conversation=True, max_turns=1),
    ):
        if isinstance(message, SystemMessage) and message.subtype == "compact_boundary":
            print("Compaction completed")
            print("Pre-compaction tokens:", message.data["compact_metadata"]["pre_tokens"])
            print("Trigger:", message.data["compact_metadata"]["trigger"])
            # Example output:
            # Compaction completed
            # Pre-compaction tokens: 1842
            # Trigger: manual


asyncio.run(main())

[!NOTE]

Un mensaje compact_boundary solo llega cuando se ejecutó la compactación. Cuando una sesión continuada tiene mensajes pero nada que /compact pueda resumir, la ejecución aún termina con un resultado success en lugar de un error, y no llega ningún mensaje compact_boundary. El texto del resultado entonces lleva la razón, por ejemplo Not enough messages to compact. cuando la sesión contiene un prompt pero aún no hay respuesta de Claude. Una llamada query() nueva de un solo disparo comienza con contexto vacío, así que use este patrón en una sesión con turnos previos, por ejemplo en modo de entrada de streaming o cuando reanuda una sesión.

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);
  }
}

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


async def main():
    async for message in query(
        prompt="/security-check", options=ClaudeAgentOptions(max_turns=10)
    ):
        if isinstance(message, ResultMessage) and message.subtype == "success":
            print(message.result)


asyncio.run(main())

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.

[!NOTE]

Claude Code incluye skills incluidas code-review y verify. Si nombra un archivo .claude/commands/ después de uno de ellos, por ejemplo .claude/commands/code-review.md, el archivo del comando sombrea la skill incluida y slash_commands lista el nombre una vez.

Preapruebe herramientas para skills

[!NOTE]

En sesiones del SDK, puedes preaprobar herramientas para un skill de proyecto o personal con el frontmatter allowed-tools del skill o con la opción allowedTools (allowed_tools en Python) en tu configuración de consulta. Si tu organización establece allowManagedPermissionRulesOnly en la configuración administrada, Claude Code ignora ambos. Los skills sincronizados desde claude.ai siguen sus propias reglas de frontmatter.

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())

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

for await (const message of query({
  prompt: "Check this project for security issues",
  options: {
    settingSources: ["user", "project"], // Load skills from filesystem
    skills: "all",
    allowedTools: ["Read", "Grep", "Glob"]
  }
})) {
  console.log(message);
}

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",
)

// Skills not loaded: settingSources excludes user and project
const optionsWithoutSkills = {
  settingSources: [],
  skills: "all"
};

// Skills loaded: user and project sources included
const optionsWithSkills = {
  settingSources: ["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",
)

// Ensure your cwd points to the directory containing .claude/skills/
const options = {
  cwd: "/path/to/project", // .claude/skills/ here or in a parent directory
  settingSources: ["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:

[tab] TypeScript

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.

[tab] Python

El SDK de Python genera ValueError indicando la regla que la entrada rompió. Por ejemplo, skills=["docs:*"] genera:
ValueError: 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 Python Agent SDK 0.2.129, 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:

Referencia de frontmatter: cada campo soportado
Pasa argumentos a skills: $ARGUMENTS, $0 y $1. La tabla de sustitución completa añade argumentos nombrados y las variables ${CLAUDE_*}
Inyecte contexto dinámico: líneas !`command` que se ejecutan antes de que Claude vea el contenido de la skill
Elija dónde cargan las skills: cada ubicación de skill, espacios de nombres de plugins y qué skill se ejecuta cuando dos comparten un nombre

Recursos relacionados

Comandos en Claude Code: la superficie de comando completa, incluido cada uno integrado
Descripción general de Agent Skills: 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
Subagentes en el SDK: agentes similares basados en el sistema de archivos con opciones programáticas
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

agent-sdk/skills.md 2026-11-10 21:57 UTC to 2026-11-11 22:59 UTC

Extienda agentes con skills

Cómo funcionan las skills con el Agent SDK

Usa skills con el Agent SDK

Configura skills en una sesión

Confirma que los skills se cargaron

Permite solo skills específicos

Comandos en sesiones del Agent SDK

Descubra comandos disponibles

Despache comandos por nombre

Compacte el historial con /compact

Reinicie el contexto con /clear

Cree skills

Elija un nivel de descubrimiento

Cree y despache su primera skill

Preapruebe herramientas para skills

Solución de problemas

Skills no encontradas

Skill no se está utilizando

Error de nombre de skill inválido

Solución de problemas adicional

Próximos pasos

Recursos relacionados

Compacte el historial con `/compact`

Reinicie el contexto con `/clear`