Extender Claude con skills

Cree, gestione y comparta skills para extender las capacidades de Claude en Claude Code. Incluye comandos personalizados y skills agrupados.

Los skills extienden lo que Claude puede hacer. Cree un archivo SKILL.md con instrucciones, y Claude lo añade a su kit de herramientas. Claude utiliza skills cuando es relevante, o puede invocar uno directamente con /skill-name.

Cree un skill cuando siga pegando las mismas instrucciones, lista de verificación o procedimiento de varios pasos en el chat, o cuando una sección de CLAUDE.md haya crecido hasta convertirse en un procedimiento en lugar de un hecho. A diferencia del contenido de CLAUDE.md, el cuerpo de un skill se carga solo cuando se utiliza, por lo que el material de referencia largo cuesta casi nada hasta que lo necesite.

[!NOTE]

Para comandos integrados como /help y /compact, y skills agrupados como /debug y /code-review, consulte la referencia de comandos.

Los comandos personalizados se han fusionado en skills. Un archivo en .claude/commands/deploy.md y un skill en .claude/skills/deploy/SKILL.md crean ambos /deploy y funcionan de la misma manera. Sus archivos existentes en .claude/commands/ siguen funcionando. Los skills añaden características opcionales: un directorio para archivos de apoyo, frontmatter para controlar si usted o Claude los invoca, y la capacidad de que Claude los cargue automáticamente cuando sea relevante.

Los skills de Claude Code siguen el estándar abierto Agent Skills, que funciona en múltiples herramientas de IA. Claude Code extiende el estándar con características adicionales como control de invocación, ejecución de subagentes, e inyección de contexto dinámico. Consulte Usar frontmatter de skills fuera de Claude Code para saber qué campos de frontmatter forman parte del estándar y cuáles son extensiones de Claude Code.

Skills incluidas

Claude Code incluye un conjunto de skills incluidas, como /doctor, /code-review, /batch, /debug, /loop y /claude-api. Las skills incluidas se basan en prompts: proporcionan a Claude instrucciones detalladas y le permiten orquestar el trabajo utilizando sus herramientas. La mayoría de los comandos integrados en su lugar ejecutan lógica fija directamente.

Usted invoca una skill incluida de la misma manera que cualquier otra skill, escribiendo / seguido del nombre de la skill. Claude invoca algunas skills incluidas automáticamente cuando es relevante; otras, incluyendo /verify, se ejecutan solo cuando usted las invoca, lo que le mantiene en control de cuándo estas comprobaciones de ejecución más larga gastan tiempo y tokens.

La mayoría de las skills incluidas están disponibles en cada sesión. Algunas dependen de una característica específica: /workflow-authoring, por ejemplo, está disponible solo cuando los flujos de trabajo dinámicos están habilitados.

Para desactivar las skills incluidas, use la configuración disableBundledSkills.

[!NOTE]

La comprobación de configuración /doctor se puede seguir escribiendo cuando disableBundledSkills está activado. Para ocultarla, establece la variable de entorno DISABLE_DOCTOR_COMMAND o una entrada de skillOverrides de "doctor": "off".

Las skills incluidas se enumeran junto con los comandos integrados en la referencia de comandos, marcadas como Skill en la columna Propósito.

Revisa tu configuración con /doctor

Ejecuta /doctor en el prompt de Claude Code para obtener una comprobación de configuración que diagnostica problemas y puede corregirlos. Claude informa primero sus hallazgos y pide confirmación antes de cambiar nada. La comprobación abarca estas áreas:

• Estado de la instalación: instalaciones duplicadas o residuales, problemas de PATH, archivos de configuración que no se pueden analizar y si hay una versión más reciente disponible en tu canal de versiones
• Extensiones: skills, servidores MCP y plugins sin usar comparados con su costo de contexto, y hooks lentos
• Archivos CLAUDE.md: archivos CLAUDE.md locales que duplican los que están en el repositorio, contenido de CLAUDE.md en el repositorio que Claude podría derivar de la base de código, y la guía que siempre se carga y que queda, que Claude ofrece migrar a skills y a archivos CLAUDE.md anidados que se cargan bajo demanda
• Permisos: una oferta para hacer del modo automático tu modo de permisos predeterminado y para aprobar previamente comandos de solo lectura que deniegas con frecuencia
• Uso: en un plan Pro, Max, Ultra, Team o Enterprise, los cambios que recomienda /usage para reducir el uso de tu plan, medido durante los últimos 7 días. Claude propone los cambios que puede hacer por sí mismo e informa el resto como consejos, por ejemplo un comando para que lo ejecutes. La comprobación de uso requiere Claude Code v2.1.305 o posterior, y /doctor la omite mientras Remote Control está conectado.

Para obtener diagnósticos de instalación de solo lectura sin iniciar una sesión, ejecuta claude doctor en tu terminal.

Para auditar tus instrucciones en lugar de tu configuración, ejecuta /doctor prompt-audit en el prompt de Claude Code. Claude revisa tus archivos CLAUDE.md, skills y otra configuración en busca de instrucciones obsoletas o contradictorias en lugar de ejecutar la comprobación. El subcomando prompt-audit requiere Claude Code v2.1.283 o posterior.

Ejecute y verifique su aplicación

Tres skills incluidos funcionan juntos para lanzar tu aplicación y confirmar los cambios contra la aplicación en ejecución en lugar de solo con pruebas:

/run y /verify funcionan sin configuración. Deducen el lanzamiento de su tipo de proyecto (CLI, servidor, TUI, impulsado por navegador) y de lo que hay en su README, package.json o Makefile. Esa deducción se vuelve poco confiable para proyectos que necesitan algo más allá de un lanzamiento estándar: una base de datos, un archivo env, una sesión gráfica, una compilación de varios pasos.

/run-skill-generator registra la receta en su lugar. Consigue que su aplicación se ejecute desde un entorno limpio, captura lo que funcionó (los comandos de instalación, las variables de entorno, el script de lanzamiento) y lo confirma como una skill por proyecto en .claude/skills/run-<name>/. Después de eso, /run, /verify y cualquier otro agente en el repositorio siguen la receta registrada en lugar de redescubrirla. Ejecute /run-skill-generator una vez por proyecto, y nuevamente si el proceso de compilación o lanzamiento cambia.

/verify también puede registrar su propia receta. Cuando tiene que compilar y manejar tu aplicación sin una receta registrada, escribe lo que funcionó en .claude/skills/verify/SKILL.md en la raíz del repositorio, o en el directorio del paquete modificado en un monorepo, para que las ejecuciones posteriores y otros agentes sigan los mismos pasos. En la raíz del repositorio, el skill registrado reemplaza al /verify incluido.

Claude edita el archivo registrado solo cuando dirigió una ejecución incorrectamente, como un comando que falló o un paso faltante, para que puedas hacer commit del archivo sin diffs por sesión.

Ejecuta tus comprobaciones antes de cada commit

Cuando una sesión comienza con un skill llamado verify o simplify disponible, las instrucciones de commit de Claude Code le indican a Claude que lo ejecute justo antes de cada commit, excepto para cambios en documentación o pruebas. Esto requiere Claude Code v2.1.286 o posterior. Claude recibe esa instrucción cuando se cumplen estas condiciones al inicio de la sesión:

• Ubicación: el skill se carga desde la ubicación empresarial, personal, de proyecto o de directorio adicional, o desde un archivo .claude/commands/ con ese nombre. La receta que /verify registra en la raíz de tu repositorio es un skill de proyecto, así que cuenta. Los /verify y /simplify incluidos, los skills de plugins y los skills de tu cuenta de claude.ai no cuentan.
• Invocación: Claude puede invocar el skill. Si has impedido que Claude lo invoque, por ejemplo con disable-model-invocation: true, Claude no recibe la instrucción.
• Instrucciones de Git: no has desactivado includeGitInstructions. Desactivarlo elimina esta instrucción junto con el resto de las instrucciones integradas de commit y PR.

Trabaje en proyectos de Claude API

La skill incluida /claude-api carga material de referencia de Claude API y Managed Agents para el idioma de su proyecto. Claude también la activa automáticamente cuando su código importa anthropic o @anthropic-ai/sdk.

Para iniciar uno de los flujos de trabajo de la skill, escriba un subcomando después del nombre de la skill en el prompt de Claude Code, por ejemplo /claude-api migrate. La tabla enumera lo que hace cada subcomando y la versión más antigua de Claude Code que lo incluye. migrate y managed-agents-onboard son anteriores a v2.1.221, la versión más antigua que la tabla rastrea.

Primeros pasos

Crear su primera skill

Este ejemplo crea una skill que resume los cambios sin confirmar en su repositorio de git e identifica cualquier cosa arriesgada. Extrae el diff en vivo en el prompt antes de que Claude lo lea, por lo que la respuesta se basa en su árbol de trabajo real en lugar de lo que Claude puede adivinar a partir de archivos abiertos. Claude carga la skill automáticamente cuando pregunta sobre sus cambios, o puede invocarla directamente con /summarize-changes.

1. Create the skill directory

Cree un directorio para la skill en su carpeta de skills personales. Las skills personales están disponibles en todos sus proyectos.

mkdir -p ~/.claude/skills/summarize-changes

2. Write SKILL.md

Cada skill necesita un archivo SKILL.md con dos partes: frontmatter YAML entre marcadores --- que le dice a Claude cuándo usar la skill, y contenido markdown con las instrucciones que Claude sigue cuando se ejecuta la skill. El nombre del directorio, o el name del frontmatter cuando lo establece, se convierte en el comando que escribe, y la description ayuda a Claude a decidir cuándo cargar la skill automáticamente.

Guarde esto en ~/.claude/skills/summarize-changes/SKILL.md:

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

La línea !`git diff HEAD` utiliza inyección de contexto dinámico: Claude Code ejecuta el comando y reemplaza la línea con su salida antes de que Claude vea el contenido de la skill, por lo que las instrucciones llegan con el diff actual ya insertado.

3. Test the skill

Abra un proyecto de git, realice una pequeña edición en cualquier archivo e inicie Claude Code ejecutando claude. Puede probar la skill de dos formas.

Deje que Claude la invoque automáticamente preguntando algo que coincida con la descripción:

What did I change?

O invóquela directamente con el nombre de la skill:

/summarize-changes

De cualquier forma, Claude debe responder con un breve resumen de su edición y una lista de riesgos.

Elige dónde se cargan los skills

El lugar donde guardas un skill decide qué sesiones lo cargan. Guárdalo en tu directorio home para tenerlo en todos los proyectos, haz commit de él en un repositorio para compartirlo con todos los que trabajan ahí, o distribúyelo mediante un plugin o la configuración administrada para llegar a todo un equipo.

Las carpetas de skills también siguen estas reglas:

• Carpetas con enlace simbólico: una entrada <skill-name> en la ubicación empresarial, personal o de proyecto puede ser un enlace simbólico a un directorio en otra parte del disco. Claude Code lee SKILL.md desde el destino y carga el skill una sola vez aunque varias ubicaciones apunten al mismo destino. Los skills de plugins manejan los enlaces simbólicos de forma diferente.
• Nombre reservado synced: no nombres una carpeta de skill synced, con ninguna combinación de mayúsculas y minúsculas. Claude Code usa ~/.claude/skills/synced/ para los skills descargados desde claude.ai y omite un skill que crees con ese nombre en las ubicaciones empresarial, personal y de proyecto.
• Nombre reservado anthropic-skills: fuera de un plugin, una carpeta de skill o un archivo de comando cuyo nombre sea anthropic-skills o empiece por anthropic-skills: no se carga. Consulta Nombres reservados para skills sincronizados.
• Caracteres en el nombre: fuera de un plugin, una carpeta de skill no se carga cuando su nombre tiene un carácter como un espacio de ancho cero o <. Consulta Caracteres que no puede contener el nombre de un skill.
• Archivos de comando: un archivo Markdown en .claude/commands/ es el formato anterior y sigue funcionando. Admite el mismo frontmatter excepto name y paths. Para saber el nombre que escribes para invocarlo, consulta Cómo obtiene un skill su nombre de comando. Prefiere un skill para el trabajo nuevo, ya que los skills también admiten archivos de apoyo.
• Carpeta de skill como plugin: agrega un .claude-plugin/plugin.json a una carpeta de skill personal o de proyecto y Claude Code puede cargarla como un plugin llamado <name>@skills-dir con sus propios agentes, hooks y servidores MCP. En el .claude/skills/ de un proyecto, esto requiere aceptar primero el diálogo de confianza del espacio de trabajo, y en cualquiera de las dos ubicaciones requiere que tu administrador no haya bloqueado los plugins del directorio de skills.

Carga skills en monorepos y subdirectorios

Claude Code carga los skills de proyecto desde .claude/skills/ en el directorio donde lo inicias y en cada directorio padre hasta la raíz del repositorio, así que iniciarlo en packages/frontend/ también recoge los skills definidos en la raíz. Cuando mueves la sesión con /cd en la v2.1.246 o posterior, Claude Code agrega los skills de proyecto del nuevo directorio.

En una sesión que se ejecuta en un git worktree vinculado que creaste con --worktree o git worktree add, Claude Code busca en los directorios padre solo hasta la raíz del worktree. En Claude Code v2.1.277 o posterior, cuando el checkout del worktree no tiene un directorio .claude/skills en su raíz, Claude Code carga en su lugar los skills de proyecto del checkout principal. Consulta Qué comparten los worktrees con el checkout principal.

Los skills en un directorio .claude/skills/ por debajo de donde iniciaste no se cargan al inicio. Se cargan la primera vez que Claude lee o edita un archivo en ese subdirectorio y siguen disponibles el resto de la sesión. Hasta entonces no aparecen en el menú / y no puedes invocarlos por nombre. Para cargarlos antes, ejecuta /add-dir con la ruta del subdirectorio, lo que requiere Claude Code v2.1.257 o posterior. Para una sesión de worktree que inicias desde la aplicación de escritorio, consulta Qué comparten los worktrees con el checkout principal.

Cuando el nombre del directorio de un skill anidado coincide con el nombre de otro skill, ambos siguen disponibles. Con un skill deploy en la raíz del repositorio y otro en apps/web/.claude/skills/:

• /deploy ejecuta el skill de la raíz. Claude Code también enumera para Claude las variantes calificadas por directorio, con la instrucción de invocar aquella cuyo directorio contiene los archivos en los que está trabajando, así que el skill anidado sigue aplicándose al trabajo en apps/web/.
• /apps/web:deploy ejecuta el skill anidado por sí solo. Su descripción nombra el directorio al que se aplica.

Carga skills desde un directorio fuera del proyecto

Cuando agregas un directorio con --add-dir o /add-dir, Claude Code carga los skills del .claude/skills/ de ese directorio, junto con sus .claude/commands/ y .claude/agents/. Los directorios que el Agent SDK agrega mediante additionalDirectories en TypeScript o add_dirs en Python se cargan de la misma manera, porque el SDK los pasa como --add-dir. El ajuste permissions.additionalDirectories en settings.json solo otorga acceso a archivos y no carga ninguno de estos.

Claude Code vigila .claude/skills/ en un directorio que pasas con --add-dir al iniciar, como describe Edita un skill durante una sesión. No vigila los .claude/commands/ ni .claude/agents/ del directorio agregado, así que reinicia la sesión después de cambiar un archivo ahí.

Estas cargas dependen de la fuente de configuración project, que está activada de forma predeterminada. Una política strictPluginOnlyCustomization, el modo bare y --safe-mode las restringen aún más, como describen esas páginas. Consulta Los directorios adicionales otorgan acceso a archivos, no configuración para ver la tabla completa de lo que carga un directorio agregado, incluidos CLAUDE.md y la configuración de plugins.

Ejecuta un skill con el mismo nombre desde un directorio agregado

Un skill de un directorio agregado recibe un prefijo cuando el nombre de su carpeta choca con un skill empresarial, personal o de proyecto, o con uno de un directorio agregado antes. Para ejecutarlo, escribe /<prefix>:<skill-name> en el prompt de Claude Code. El menú / enumera el skill con su nombre con prefijo, y Cómo obtiene un skill su nombre de comando describe de dónde viene el prefijo. Ese nombre requiere Claude Code v2.1.309 o posterior.

Por ejemplo, con --add-dir ../cli y un skill verify tanto en tu proyecto como en ../cli:

• /verify ejecuta el skill de tu proyecto
• /cli:verify ejecuta el skill de ../cli

Resuelve skills que comparten nombre

Cuando dos skills comparten un nombre de directorio o de archivo, el origen de cada uno decide cuál ejecuta /name. Para un nombre definido por el campo name del frontmatter, consulta Cómo obtiene un skill su nombre de comando.

Usa skills en sesiones de Cowork y sesiones en la nube

Las sesiones de Cowork y las sesiones en la nube, incluidas las tareas programadas en la nube, no leen ~/.claude/skills/ en tu máquina. Tanto las sesiones de Cowork interactivas como las programadas cargan los skills habilitados para tu cuenta de claude.ai, sincronizados al inicio de la sesión. Adminístralos desde Customize en la barra lateral de la aplicación de escritorio o desde la configuración de skills en claude.ai.

Si un skill existe solo en ~/.claude/skills/ en tu máquina, Claude Code informa que no se encontró el skill cuando una tarea programada en la nube lo invoca. Esto ocurre porque cada ejecución empieza como una sesión en la nube nueva. Para que un skill personal esté disponible en estas sesiones:

• Para sesiones de Cowork, sesiones en la nube e hilos en la nube de un proyecto, habilita el skill para tu cuenta de claude.ai. En el hilo en la nube de un proyecto, los skills con commit en el .claude/skills/ de un repositorio no están disponibles. Algunas sesiones en un entorno autoalojado no cargan los skills de tu cuenta.
• Para las sesiones en la nube que no son hilos de proyecto, puedes en cambio hacer commit del skill en el .claude/skills/ del repositorio. Los plugins declarados en el .claude/settings.json del repositorio y los plugins habilitados solo en tu configuración de usuario no se cargan en sesiones en la nube.

Las tareas programadas de escritorio se ejecutan localmente en tu máquina, así que sí cargan ~/.claude/skills/.

Skills sincronizados desde claude.ai

Esta sección te aplica si usas sesiones de Cowork o sesiones en la nube, o si inicias sesión en Claude Code en tu terminal con una cuenta de claude.ai. En esas sesiones, Claude Code carga los skills habilitados para tu cuenta de claude.ai, sin que tengas que configurar nada, como describe Dónde se cargan los skills sincronizados. Esos skills incluyen los que creas o activas en tu configuración de claude.ai, los skills que tu organización proporciona ahí y los skills integrados de Anthropic, como pdf y xlsx.

Claude Code descarga un skill sincronizado desde tu cuenta en lugar de leer un archivo que escribiste en la máquina donde se ejecuta la sesión, así que aplica a los skills sincronizados reglas que no se aplican a los skills que guardas en las ubicaciones de skills.

Dónde se cargan los skills sincronizados

En una sesión de Cowork o una sesión en la nube, Claude Code carga los skills habilitados para tu cuenta de claude.ai, y Skills en sesiones de Cowork y sesiones en la nube explica cómo elegir qué skills reciben esas sesiones.

En tu terminal, Claude Code sincroniza esos skills en las sesiones en las que inicias sesión con tu cuenta de claude.ai. Cuando la sesión empieza, Claude Code descarga los skills de tu cuenta en ~/.claude/skills/synced/ en segundo plano y luego consulta claude.ai en busca de cambios mientras la sesión se ejecuta. Cuando una consulta detecta que un skill se agregó, se editó o se desactivó en claude.ai, Claude Code lo agrega, actualiza o elimina en la sesión en curso sin reiniciar. La sincronización en sesiones de terminal requiere Claude Code v2.1.273 o posterior.

Las consultas se ejecutan con menos frecuencia mientras la sesión está inactiva:

• Mientras tú o Claude trabajan en la sesión: se ejecuta una consulta aproximadamente cada 10 minutos.
• Mientras la sesión está inactiva: se ejecuta una consulta aproximadamente cada 40 minutos. Cuando vuelves a escribir en la sesión, Claude Code consulta en unos pocos minutos si la última consulta fue hace más de 10 minutos.

La sincronización nunca retrasa el inicio, porque Claude espera la descarga de un skill solo cuando invoca ese skill. Por eso, una ejecución no interactiva corta puede terminar antes de que se descargue un skill recién agregado, en cuyo caso una sesión posterior lo descarga. Para que una ejecución no interactiva descargue tus skills y espere la lista antes de responder al prompt, establece CLAUDE_CODE_SYNC_SKILLS en 1. Antes de la v2.1.273, las sesiones de terminal los descargaban solo en una ejecución con -p con esta variable establecida.

Claude Code sincroniza solo en una sesión que inicia sesión con tu cuenta de claude.ai y obtiene los feature flags de Anthropic. No sincroniza en estas sesiones:

• Una sesión que no usa un inicio de sesión guardado por /login, como una que se autentica con una clave de API, o una en la que ANTHROPIC_AUTH_TOKEN, CLAUDE_CODE_OAUTH_TOKEN o un script apiKeyHelper proporciona la credencial
• Una sesión que no obtiene feature flags, como una en Amazon Bedrock o una en la que estableces CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC
• Una sesión en modo bare o una que inicias con --safe-mode
• Una sesión en la que la configuración administrada de tu organización restringe los skills a fuentes de plugins, o una que inicias con una lista de --setting-sources que omite user

Si inicias sesión con /login durante una sesión, reinicia Claude Code para empezar a sincronizar.

Los skills que una sesión anterior sincronizó permanecen en el disco. Claude Code los carga en sesiones posteriores iniciadas con la misma cuenta, incluso cuando no puede conectarse a claude.ai.

Claude Code descarga los skills sincronizados y nunca los sube. Si tú o Claude editan un archivo en ~/.claude/skills/synced/, el cambio no se guarda en tu cuenta de claude.ai, y una sincronización posterior puede sobrescribirlo o eliminarlo. Para cambiar un skill sincronizado, actualízalo en claude.ai; la siguiente sincronización descarga la nueva versión.

Para ver qué skills se sincronizaron, ejecuta /skills. El menú los enumera bajo claude.ai sync.

Algunos de los skills de Anthropic, como pdf y xlsx, siempre se sincronizan. Para el resto, activa o desactiva un skill en tu configuración de skills en claude.ai para cambiar si se sincroniza.

Para dejar de sincronizar en una máquina, establece syncClaudeAiSkills en false en tu configuración de usuario. Claude Code deja de descargar y, la próxima vez que se inicia, mueve los skills que ya sincronizó a ~/.claude/skills/.trash/ y deja de cargarlos. Tu organización puede desactivar la sincronización para todos desactivando Skills en claude.ai. Para dejar de sincronizar sin desactivar Skills, puede establecer la misma clave en la configuración administrada.

Si tu organización desactiva Skills en claude.ai, Claude Code elimina los skills descargados y dejan de cargarse. Los skills eliminados se mueven a ~/.claude/skills/.trash/, donde puedes recuperar los archivos hasta que la limpieza por retención los borre. Una vez que tu organización vuelve a activar Skills, Claude Code descarga los skills que habilitaste en la siguiente sincronización.

Cuando el nombre de un skill sincronizado coincide con otro comando

Puedes invocar un skill sincronizado por su nombre corto, /<name>, o por su nombre completo, /anthropic-skills:<name>. Cuando otro comando usa el nombre corto, /<name> ejecuta el otro comando, y el skill sincronizado se ejecuta solo como /anthropic-skills:<name>. Con un skill local deploy y un deploy sincronizado, /deploy ejecuta el skill local y /anthropic-skills:deploy ejecuta el sincronizado. Antes de la v2.1.269, un skill sincronizado tenía solo su nombre corto.

En el menú /, /skills y /context, un skill sincronizado aparece con su nombre corto, o con su nombre completo mientras otro comando use el nombre corto. Ejecuta /skills en tu sesión. Una nota debajo de la lista explica cada skill sincronizado que perdió su nombre corto. Si uno de tus skills personales o archivos de comando en ~/.claude/ usa el nombre, la nota también indica qué renombrar o eliminar para liberarlo.

Desde la v2.1.269 hasta la v2.1.280, estas listas mostraban cada skill sincronizado con su nombre completo, y /skills no tenía esa nota; ambas cosas cambiaron en la v2.1.281.

El comando que usa el nombre corto puede ser cualquiera de estos:

• Un comando integrado o un skill incluido, incluido uno que no está disponible en tu sesión, por ejemplo después de desactivar los skills incluidos
• Un skill en cualquier nivel local o un archivo en .claude/commands/
• Un skill de plugin
• Un prompt de MCP

Claude Code etiqueta los skills sincronizados para que puedas saber de dónde vienen. El menú /skills y /context agrupan los skills sincronizados bajo claude.ai sync, y el menú de comandos / los marca como provenientes de claude.ai.

Al comparar nombres, Claude Code ignora las mayúsculas y minúsculas, los espacios y los caracteres invisibles, y trata las formas de compatibilidad, como las letras de ancho completo y las variantes de guion, como sus equivalentes simples. Por ejemplo, un skill sincronizado llamado Commit y un skill local llamado commit cuentan como el mismo nombre, así que /commit sigue ejecutando tu skill local.

Un nombre que difiere solo por una letra parecida de otro alfabeto cuenta como un nombre distinto, y la etiqueta claude.ai sync es la forma de distinguir ambos. Estas comprobaciones y etiquetas requieren Claude Code v2.1.228 o posterior.

Nombres reservados para skills sincronizados

Claude Code reserva el nombre anthropic-skills, y cada nombre dentro de ese espacio de nombres, como anthropic-skills:pdf, para los skills sincronizados desde claude.ai, de modo que el nombre completo de un skill sincronizado nunca ejecute otra cosa. El nombre está reservado en todas las sesiones, inicies sesión o no con una cuenta de claude.ai.

• Una carpeta de skill, un name del frontmatter, un archivo o subcarpeta en .claude/commands/, o un flujo de trabajo guardado: no se carga. Un aviso al inicio nombra el primer elemento que debes renombrar o editar.
• Un plugin llamado anthropic-skills: se carga. Cuando uno de sus skills y un skill sincronizado se llaman ambos <name>, /anthropic-skills:<name> ejecuta el skill sincronizado.
• Un servidor MCP llamado anthropic-skills: se conecta y sus herramientas funcionan, pero sus prompts no aparecen como comandos. Renombra el servidor en tu configuración de MCP para que se enumeren.

Cómo maneja Claude Code el frontmatter de un skill sincronizado

Claude Code aplica dos reglas al frontmatter de un skill sincronizado:

• El frontmatter se aplica en todo tipo de sesión, así que una concesión de allowed-tools pasa por el flujo de permisos normal. Si tu organización establece allowManagedPermissionRulesOnly, la concesión no se aplica.
• Claude Code sanitiza el texto de visualización que proporciona el skill, como su descripción. Elimina los caracteres de control y, en el texto que llega a Claude, como la descripción, también escapa los corchetes angulares para que el texto no pueda imitar el formato interno de Claude Code. Esta sanitización requiere Claude Code v2.1.228 o posterior.

Cómo maneja Claude Code el cuerpo de un skill sincronizado

Lo que Claude Code hace con el cuerpo de un skill sincronizado depende de dónde se ejecuta la sesión:

• En una sesión en la nube, el cuerpo conserva el comportamiento que tiene un skill local, porque la sesión se ejecuta en un contenedor aislado.
• En una sesión de Cowork en tu escritorio, el cuerpo conserva el comportamiento que tiene un skill local, excepto que Claude Code reemplaza cada línea de comando ! con el marcador de posición de disableSkillShellExecution, como hace con cada skill que proporcionas ahí.
• En cualquier otra sesión en tu máquina, Claude Code no ejecuta comandos !, no adjunta los archivos que nombran las referencias @ como lo hace para un skill local, y no sustituye los marcadores de posición ${CLAUDE_PROJECT_DIR} y ${CLAUDE_SESSION_ID}, así que las referencias @ y ambos marcadores de posición llegan a Claude como texto literal. Una línea de comando ! también llega a Claude como texto literal, o como ese marcador de posición cuando disableSkillShellExecution está activado. Este manejo requiere Claude Code v2.1.228 o posterior.

Edita un skill durante una sesión

Claude Code vigila los directorios de skills en busca de cambios en los archivos, excepto en modo bare. Cuando agregas, editas o eliminas un skill en ~/.claude/skills/, el .claude/skills/ del proyecto o un .claude/skills/ dentro de un directorio de --add-dir, Claude Code detecta el cambio dentro de la sesión actual, sin reiniciar.

Si creas un directorio de skills de nivel superior que no existía cuando empezó la sesión, ejecuta /reload-skills para recoger los skills que pusiste ahí. Claude Code todavía no vigila ese directorio, así que vuelve a ejecutar /reload-skills después de cada cambio posterior ahí.

La detección de cambios en vivo cubre solo el texto de SKILL.md. Para una carpeta de skill que también es un plugin, los cambios en hooks/, .mcp.json, agents/ y output-styles/ necesitan /reload-plugins para surtir efecto.

Elimina un skill

La forma de eliminar un skill depende de su origen:

• Skill personal o de proyecto: borra el directorio del skill, ~/.claude/skills/<skill-name>/ o .claude/skills/<skill-name>/. Claude Code lo quita de /skills en la sesión actual; el contenido que Claude Code ya cargó desde él sigue el ciclo de vida del contenido de skills.
• Skill empresarial: un administrador borra el directorio del skill de .claude/skills/ dentro del directorio de configuración administrada, por ejemplo /etc/claude-code/.claude/skills/<skill-name>/ en Linux.
• Skill de plugin: deshabilita o desinstala el plugin que lo proporciona, desde el menú /plugin o con /plugin uninstall <plugin-name>@<marketplace-name>. Claude Code descarga de la sesión los skills del plugin cuando se aplica el cambio o cuando reinicias.
• Skill sincronizado desde claude.ai: desactiva el skill para tu cuenta de claude.ai, en el mismo lugar donde lo habilitaste. Claude Code lo elimina de ~/.claude/skills/synced/ la próxima vez que sincroniza tus skills. Si en cambio borras el directorio a mano, la siguiente sincronización lo vuelve a descargar mientras el skill siga habilitado en claude.ai.
• Skill incluido: establece disableBundledSkills en true para desactivar los skills incluidos, o establece un skill en "off" en skillOverrides para ocultarlo.

Para conservar un skill personal o de proyecto pero evitar que Claude lo invoque por su cuenta, establece disable-model-invocation: true en su frontmatter, o "user-invocable-only" en skillOverrides cuando no quieras editar el archivo.

Configurar skills

Los skills se configuran a través de frontmatter YAML en la parte superior de SKILL.md y el contenido markdown que sigue.

Tipos de contenido de skill

Los archivos de skill pueden contener cualquier instrucción, pero pensar en cómo deseas invocarlos ayuda a guiar qué incluir:

Contenido de referencia añade conocimiento que Claude aplica a tu trabajo actual. Convenciones, patrones, guías de estilo, conocimiento del dominio. Este contenido se ejecuta en línea para que Claude pueda usarlo junto con el contexto de tu conversación.

---
name: api-conventions
description: API design patterns for this codebase
---

When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats
- Include request validation

Contenido de tarea proporciona a Claude instrucciones paso a paso para una acción específica, como implementaciones, commits o generación de código. Estas son a menudo acciones que deseas invocar directamente con /skill-name en lugar de dejar que Claude decida cuándo ejecutarlas. Añade disable-model-invocation: true para evitar que Claude la active automáticamente. El ejemplo a continuación añade context: fork, que ejecuta el skill en su propio contexto de subagente; consulta Ejecutar skills en un subagente.

---
name: deploy
description: Deploy the application to production
context: fork
disable-model-invocation: true
---

Deploy the application:
1. Run the test suite
2. Build the application
3. Push to the deployment target

Mantén el cuerpo en sí conciso. Una vez que se carga un skill, su contenido permanece en contexto entre turnos, por lo que cada línea es un costo de token recurrente. Indica qué hacer en lugar de narrar cómo o por qué, y aplica la misma prueba de concisión que harías para contenido de CLAUDE.md.

Referencia de frontmatter

Configura un skill con YAML frontmatter entre marcadores --- en la parte superior de SKILL.md, y escribe las instrucciones del skill como Markdown después del cierre ---. Los nombres de campo usan palabras en minúsculas separadas por guiones, excepto when_to_use. Un archivo de comando en .claude/commands/ acepta los mismos campos excepto name y paths. Este ejemplo establece cuatro campos:

---
name: my-skill
description: What this skill does
disable-model-invocation: true
allowed-tools: Read Grep
---

Your skill instructions here...

Todos los campos son opcionales. Solo se recomienda description para que Claude sepa cuándo usar el skill. Un nombre de campo debe coincidir exactamente con la tabla, guiones incluidos: Claude Code ignora un campo que no reconoce sin reportar un error. Los campos booleanos aceptan yes, no, on, off, 1 y 0 en cualquier combinación de mayúsculas y minúsculas, además de true y false.

Claude Code lee el frontmatter solo cuando la apertura --- es la primera línea del archivo. De lo contrario, trata todo el archivo, incluidos los marcadores ---, como contenido de skill. Si el YAML entre los marcadores no se analiza, el skill aún se carga sin campos establecidos; consulta Skill no se activa para encontrar y corregir el error.

Usar frontmatter de skill fuera de Claude Code

Claude Code acepta cada campo en la tabla anterior. Fuera de Claude Code, solo puedes usar los campos en la especificación Agent Skills:

Cuando habilitas un skill personal para tu cuenta de claude.ai, por ejemplo para usarlo en sesiones de Cowork y en la nube y en tareas programadas, lo cargas en claude.ai. Las mismas reglas se aplican a esa carga.

Si incluyes algún campo que la especificación no permite, el empaquetamiento o la carga falla con un error grave en lugar de ignorar el campo:

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

Restringir el frontmatter a los seis campos de la especificación evita el error de clave inesperada anterior. La especificación de Agent Skills y los requisitos de la API de Skills definen todo lo demás que esas rutas validan. Las características del cuerpo solo de Claude Code, como inyección de contexto dinámico, no funcionan en el chat de claude.ai o a través de la API. Claude Code acepta los seis campos, por lo que el frontmatter que sigue la especificación se carga en Claude Code sin cambios.

Cómo un skill obtiene su nombre de comando

El comando que escribes para invocar un skill proviene de dónde vive el archivo de skill y, para directorios de skill y skills de plugin, del campo de frontmatter name. En un directorio de skill personal o de proyecto, name establece el comando que el menú / muestra y que escribes, a menos que otro comando ya use ese nombre. El nombre del directorio también invoca el skill. En un skill de plugin, name establece el último segmento del comando y el prefijo del plugin permanece en su lugar.

La tabla a continuación muestra de dónde proviene el nombre del comando para cada diseño:

En un skill de plugin, el frontmatter name reemplaza el nombre del directorio en el último segmento del comando, por lo que my-plugin/skills/review/SKILL.md con name: fancy se convierte en /my-plugin:fancy. El comando desnudo /fancy también invoca el skill a menos que otro comando ya use ese nombre. Si el name que escribes ya comienza con el prefijo propio del plugin, Claude Code no añade el prefijo nuevamente en v2.1.246 o posterior. Por ejemplo, name: my-plugin:fancy sigue siendo /my-plugin:fancy. De v2.1.216 a v2.1.245, Claude Code duplicaba el prefijo cuando el name ya lo llevaba.

En sesiones no interactivas, los nombres help y feedback no están reservados para sus comandos integrados solo de terminal, por lo que un skill de plugin con uno de esos nombres mantiene su comando desnudo allí. Todos los demás nombres de integrados solo de terminal, como /login, permanecen reservados aunque el comando no pueda ejecutarse en esas sesiones.

Para un SKILL.md raíz de plugin, no hay directorio de skill del que tomar el nombre, por lo que name proporciona el segmento final completo. Sin un campo name, Claude Code recurre al nombre del directorio del plugin.

Caracteres que no puede contener el nombre de un skill

Si falta un skill o un comando personalizado en el menú /, o el menú no muestra el name del frontmatter de un skill, revisa el nombre. Claude Code rechaza un nombre de comando o un name de frontmatter que contenga caracteres como estos:

• Un espacio de ancho cero o un carácter de control
• Un carácter de uso privado o sin asignar, como un glifo de una fuente de íconos
• Un carácter que cambia la dirección del texto que lo rodea
• Un espacio en blanco distinto de un único espacio simple entre palabras, como un espacio de no separación, dos espacios seguidos o un espacio al inicio o al final
• < o >

Un comando personalizado o un skill no se carga cuando Claude Code rechaza el nombre de su directorio o archivo. Cambia el nombre de esa carpeta o archivo para quitar los caracteres. Un skill sigue cargándose cuando estos caracteres están solo en el nombre de la carpeta de un skill de plugin o en su name de frontmatter:

• Carpeta en el directorio skills/ de un plugin o en las rutas skills de su manifiesto: no necesitas cambiar el nombre de la carpeta. Estos caracteres se convierten en guiones en el nombre del comando del skill, así que escribe el comando con los guiones.
• name de frontmatter: el menú / no muestra el valor de name y escribirlo no invoca el skill. Edita la línea name: para quitar los caracteres.

Para averiguar qué nombre rechazó Claude Code, inícialo con claude --debug desde tu shell y busca [names] en el registro de depuración. En una sesión interactiva, un aviso de inicio también te indica que se rechazaron nombres. Después de cambiar un nombre o editar la línea name:, reinicia la sesión, a menos que el archivo esté en un directorio que Claude Code vigila en busca de cambios.

Sustituciones de cadena disponibles

Los skills admiten sustitución de cadena para valores dinámicos en el contenido del skill:

Claude Code sustituye ${CLAUDE_SKILL_DIR} y ${CLAUDE_PROJECT_DIR} en dos lugares: el contenido markdown del skill y las reglas Bash en el frontmatter allowed-tools. En un skill de plugin, Claude Code sustituye ${CLAUDE_PLUGIN_ROOT} y ${CLAUDE_PLUGIN_DATA} en los mismos dos lugares. Usar la misma variable en ambos lugares permite que un skill ejecute un script incluido sin un aviso de permiso. El siguiente skill muestra el patrón:

---
name: render-chart
description: Render a chart from a CSV file
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/render.sh *)
---

Run `${CLAUDE_SKILL_DIR}/scripts/render.sh <csv-file>` to render the chart.

Si este skill está instalado en ~/.claude/skills/render-chart/, ambas ocurrencias de ${CLAUDE_SKILL_DIR} se expanden a ese directorio. La regla allowed-tools luego coincide con el comando exacto que el cuerpo del skill le dice a Claude que ejecute, por lo que el script se ejecuta sin solicitar.

Los argumentos indexados usan comillas de estilo shell, por lo que envuelve valores de varias palabras entre comillas para pasarlos como un único argumento. Por ejemplo, /my-skill "hello world" second hace que $0 se expanda a hello world y $1 a second. El marcador de posición $ARGUMENTS siempre se expande a la cadena de argumento completa tal como se escribió.

Un marcador de posición indexado sin argumento correspondiente, como $2 cuando solo se pasó un argumento, permanece en el contenido sin cambios. Un marcador de posición nombrado del frontmatter arguments sin argumento coincidente se expande a una cadena vacía.

Si pasas un valor de argumento que en sí contiene texto como $1 o $ARGUMENTS, Claude Code lo inserta como texto literal y no lo expande. Por ejemplo, si el cuerpo de un skill contiene Summarize $0 y ejecutas /summarize "$ARGUMENTS from yesterday", Claude recibe Summarize $ARGUMENTS from yesterday. Claude Code aún reemplaza variables ${CLAUDE_*} como ${CLAUDE_SKILL_DIR} después de insertar los argumentos.

Para incluir un $ literal antes de un dígito, ARGUMENTS o un nombre de argumento declarado, como $1.00 en prosa, escápalo con una barra invertida: \$1.00. Una barra invertida antes de cualquier otro $ se deja sin cambios. Solo una barra invertida directamente antes del token lo escapa. Una barra invertida duplicada como \\$1 deja ambas barras invertidas en su lugar, y $1 aún se expande al valor del argumento. El escape de barra invertida cubre solo estos marcadores de posición de argumento. Una barra invertida no evita la sustitución de una variable ${CLAUDE_*} donde se aplica la variable.

Ejemplo usando sustituciones:

---
name: session-logger
description: Log activity for this session
---

Log the following to logs/${CLAUDE_SESSION_ID}.log:

$ARGUMENTS

Añadir archivos de apoyo

Los skills pueden incluir múltiples archivos en su directorio. Esto mantiene SKILL.md enfocado en lo esencial mientras permite que Claude acceda a material de referencia detallado solo cuando sea necesario. Documentos de referencia grandes, especificaciones de API o colecciones de ejemplos no necesitan cargarse en contexto cada vez que se ejecuta el skill.

my-skill/
├── SKILL.md (required - overview and navigation)
├── reference.md (detailed API docs - loaded when needed)
├── examples.md (usage examples - loaded when needed)
└── scripts/
    └── helper.py (utility script - executed, not loaded)

Haz referencia a archivos de apoyo desde SKILL.md para que Claude sepa qué contiene cada archivo y cuándo cargarlo:

## Additional resources

- For complete API details, see [reference.md](/anthropic/claude-code/history/docs/es/2026-11-08-2258..2026-11-09-2302/reference/)
- For usage examples, see [examples.md](/anthropic/claude-code/history/docs/es/2026-11-08-2258..2026-11-09-2302/examples/)

[!TIP]

Mantén SKILL.md bajo 500 líneas. Mueve material de referencia detallado a archivos separados.

Controlar quién invoca un skill

Por defecto, tanto tú como Claude pueden invocar cualquier skill. Puedes escribir /skill-name para invocarlo directamente, y Claude puede cargarlo automáticamente cuando sea relevante para tu conversación. Dos campos de frontmatter te permiten restringir esto:

• disable-model-invocation: true: Claude no puede invocar el skill por sí solo. Úsalo para flujos de trabajo con efectos secundarios o que deseas controlar el tiempo, como /commit, /deploy o /send-slack-message. No quieres que Claude decida desplegar porque tu código se ve listo.

• user-invocable: false: Solo Claude puede invocar el skill. Úsalo para conocimiento de fondo que no es accionable como comando. Un skill legacy-system-context explica cómo funciona un sistema antiguo. Claude debe saber esto cuando sea relevante, pero /legacy-system-context no es una acción significativa para que los usuarios realicen.

Este ejemplo crea un skill de despliegue. Si estableces disable-model-invocation: true, Claude no puede ejecutar el skill automáticamente:

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---

Deploy $ARGUMENTS to production:

1. Run the test suite
2. Build the application
3. Push to the deployment target
4. Verify the deployment succeeded

Si Claude lo intenta de todas formas, Claude Code bloquea la llamada e instruye a Claude a no reproducir los pasos de implementación de otra manera, así que espera que Claude sugiera ejecutar /deploy tú mismo.

Aquí está cómo los dos campos afectan la invocación y la carga de contexto:

[!NOTE]

En una sesión regular, las descripciones de skills se cargan en contexto para que Claude sepa qué está disponible, pero el contenido completo del skill solo se carga cuando se invoca. Subagentes con skills precargados funcionan diferente: el contenido completo del skill se inyecta al inicio.

Dónde escribes el nombre del skill

Para ejecutar un skill directamente, pon su nombre al inicio de tu mensaje. Después de texto simple, el nombre le da a Claude permiso para ejecutar el skill, pero no lo ejecuta:

Para escribir sobre el skill sin permitir una ejecución, omite la barra.

Ciclo de vida del contenido del skill

Cuando tú o Claude invocas un skill, el contenido SKILL.md renderizado entra en la conversación como un único mensaje y permanece allí en turnos posteriores. Esta persistencia se aplica a las instrucciones del skill, no a sus permisos: una concesión allowed-tools se borra cuando envías tu siguiente mensaje. Claude Code no vuelve a leer el archivo de skill en turnos posteriores, por lo que escribe orientación que debe aplicarse durante una tarea como instrucciones permanentes en lugar de pasos únicos.

Cuando Claude reinvoca un skill cuyo contenido renderizado es idéntico a la copia ya en contexto, Claude Code añade una nota breve de que el skill ya está cargado en lugar de una segunda copia del contenido. Cuando el contenido renderizado difiere, porque los argumentos cambiaron o un comando contexto dinámico produjo nueva salida, Claude Code añade el contenido completo nuevamente.

Auto-compactación lleva skills invocados hacia adelante dentro de un presupuesto de tokens. Cuando la conversación se resume para liberar contexto, Claude Code vuelve a adjuntar la invocación más reciente de cada skill después del resumen, manteniendo los primeros 5.000 tokens de cada uno. Los skills reajuntados comparten un presupuesto combinado de 25.000 tokens. Claude Code llena este presupuesto comenzando desde el skill invocado más recientemente, por lo que los skills más antiguos pueden ser eliminados completamente después de la compactación si has invocado muchos en una sesión.

Si Claude deja de seguir un skill a mitad de una sesión, consulta Claude deja de seguir un skill.

Pre-aprobar herramientas para un skill

El campo allowed-tools otorga permiso para las herramientas listadas durante el turno que invoca el skill, para que Claude pueda usarlas sin solicitarte aprobación. La concesión se borra cuando envías tu siguiente mensaje, aunque el contenido del skill permanece en contexto; invocar el skill nuevamente vuelve a aplicarlo para ese turno. No restringe qué herramientas están disponibles: cada herramienta sigue siendo invocable, y tu configuración de permisos aún rige herramientas que no están listadas. Para pre-aprobar herramientas para toda la sesión en lugar de un único turno, añade reglas de permitir a esa configuración de permisos en su lugar.

La confianza del espacio de trabajo no controla este campo. Claude Code aplica el allowed-tools de un skill de proyecto incluso en una ejecución -p en una carpeta en la que nunca has confiado. Un skill puede otorgarse a sí mismo acceso amplio a herramientas, por lo que revisa el allowed-tools de los skills incluidos en un repositorio antes de ejecutar Claude Code allí. Para impedir que los skills de repositorios usen este campo en toda tu organización, consulta Cuándo solo se aplican las reglas de permisos administradas.

Este skill permite que Claude ejecute comandos git sin aprobación por uso siempre que lo invokes:

---
name: commit
description: Stage and commit the current changes
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---

Para eliminar herramientas del grupo disponible de Claude mientras un skill está activo, listalás en disallowed-tools en el frontmatter del skill. La restricción se borra cuando envías tu siguiente mensaje. Como las reglas de denegación, el campo no puede eliminar EndConversation mientras cualquier otra herramienta permanezca. Para bloquear herramientas en todos los skills y prompts, añade reglas de denegación en tu configuración de permisos.

Cuándo la configuración administrada restringe los hooks a plugins

Cuando la configuración administrada de tu organización incluye hooks en strictPluginOnlyCustomization, un skill personal o de proyecto cuyo frontmatter declara hooks pierde la pre-aprobación de su allowed-tools, salvo los skills que la conservan.

• Comprobar: escribe /status en una sesión de Claude Code. Si /status muestra Enterprise managed settings, pregunta a tu administrador si strictPluginOnlyCustomization incluye hooks.
• Corregir: quita hooks del frontmatter del skill, porque sus hooks no se ejecutan con ese ajuste. Para conservarlos, mueve el skill a un plugin que instales desde un marketplace.

Cuándo solo se aplican las reglas de permisos administradas

Cuando tu organización establece allowManagedPermissionRulesOnly en la configuración administrada, Claude Code ignora allowed-tools en los skills de proyecto y personales, y en las otras fuentes que enumera la entrada de ese ajuste. Esto requiere Claude Code v2.1.282 o posterior.

Las herramientas que enumera un skill afectado pasan en su lugar por las reglas administradas de tu organización y la solicitud de permiso normal. Ejecuta /status para listar cada skill cuyo allowed-tools Claude Code ha ignorado hasta el momento en la sesión. Un comando inyectado en el skill que ninguna regla administrada permite sigue lo descrito en Comprobaciones de permisos en comandos inyectados.

Pasar argumentos a skills

Tanto tú como Claude pueden pasar argumentos al invocar un skill. Los argumentos están disponibles a través del marcador de posición $ARGUMENTS.

Este skill corrige un problema de GitHub por número. El marcador de posición $ARGUMENTS se reemplaza con lo que sigue al nombre del skill:

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

1. Read the issue description
2. Understand the requirements
3. Implement the fix
4. Write tests
5. Create a commit

Cuando ejecutas /fix-issue 123, Claude recibe "Fix GitHub issue 123 following our coding standards..."

Si invocas un skill con argumentos pero ningún marcador de posición en el contenido del skill recibe uno, Claude Code añade ARGUMENTS: <your input> al final del contenido del skill para que Claude aún vea lo que escribiste. Un marcador de posición es $ARGUMENTS, una forma indexada como $1, o un argumento nombrado. Un marcador de posición indexado sin argumento en su posición permanece como texto literal y no cuenta como recibiendo uno. Un marcador de posición nombrado cuenta incluso cuando su posición no tiene argumento, porque se expande a una cadena vacía.

Para acceder a argumentos individuales por posición, usa $ARGUMENTS[N] o la forma más corta $N:

---
name: migrate-component
description: Migrate a component from one language to another
---

Migrate the $ARGUMENTS[0] component from $ARGUMENTS[1] to $ARGUMENTS[2].
Preserve all existing behavior and tests.

Ejecutar /migrate-component SearchBar JavaScript TypeScript reemplaza $ARGUMENTS[0] con SearchBar, $ARGUMENTS[1] con JavaScript y $ARGUMENTS[2] con TypeScript. El mismo skill usando la abreviatura $N:

---
name: migrate-component
description: Migrate a component from one language to another
---

Migrate the $0 component from $1 to $2.
Preserve all existing behavior and tests.

Apilar varios skills en un mensaje

Cuando escribes en el prompt de Claude Code en tu terminal, puedes apilar varios skills al inicio de un mensaje. A través del Agent SDK o claude -p, Claude Code carga solo el primer skill, con el resto de la línea como sus argumentos. En el prompt de la terminal, escribir /write-tests /fix-issue 123 carga ambos skills y pasa el texto final 123 como $ARGUMENTS a cada uno de ellos.

Claude Code expande el primer skill más hasta cinco más apilados después de él. La expansión se detiene en el primer token que no es un skill invocable por el usuario en línea. Si apilas un skill que se ejecuta como un subagente bifurcado, como /code-review, o uno cuyos argumentos pueden comenzar con otro comando, como /loop, la expansión termina allí. Ese token y todo lo que viene después se convierten en el texto de argumento para cada skill expandido.

Patrones avanzados

Inyectar contexto dinámico

La sintaxis !`<command>` ejecuta comandos de shell antes de que el contenido de la skill se envíe a Claude. La salida del comando reemplaza el marcador de posición, por lo que Claude recibe datos reales, no el comando en sí. Claude Code no ejecuta estos comandos en su máquina cuando la skill está sincronizada desde su cuenta de claude.ai. Esta restricción requiere Claude Code v2.1.228 o posterior.

Esta skill resume una solicitud de extracción obteniendo datos de PR en vivo con la CLI de GitHub. Los comandos !`gh pr diff` y otros se ejecutan primero, y su salida se inserta en el prompt:

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Your task
Summarize this pull request...

La sustitución se ejecuta una sola vez sobre el archivo original. La salida del comando se inserta como texto sin formato y no se vuelve a escanear para buscar más marcadores de posición !`<command>`, por lo que un comando no puede emitir un marcador de posición para que una pasada posterior lo expanda.

La forma en línea solo se reconoce cuando ! aparece al inicio de una línea o inmediatamente después de espacios en blanco. Si ! sigue a otro carácter, como en KEY=!`cmd`, el marcador de posición se deja como texto literal y el comando no se ejecuta.

Para comandos de varias líneas, use un bloque de código delimitado abierto con ```! en lugar de la forma en línea:

## Environment
```!
node --version
git status --short
```

Para desactivar este comportamiento para skills y comandos personalizados de fuentes de usuario, proyecto, plugin o directorio adicional, establezca "disableSkillShellExecution": true en settings. Cada comando se reemplaza con [shell command execution disabled by policy] en lugar de ejecutarse. Las skills agrupadas y administradas no se ven afectadas. Esta configuración es más útil en managed settings, donde los usuarios no pueden anularla.

Claude Code nunca ejecuta estos comandos en su máquina cuando aparecen en skills sincronizadas desde su cuenta de claude.ai, independientemente de esta configuración. Esta restricción requiere Claude Code v2.1.228 o posterior. How Claude Code handles the body of a synced skill dice qué recibe Claude en lugar del comando en cada tipo de sesión.

[!TIP]

Para solicitar un razonamiento más profundo cuando se ejecuta una skill, incluya ultrathink en cualquier lugar del contenido de la skill. Consulte Use ultrathink for one-off deep reasoning.

Cómo se ejecutan los comandos inyectados

Claude Code elige la herramienta que ejecuta los comandos inyectados de una skill desde la clave shell en el frontmatter de la skill y su entorno. Cada combinación ejecuta los comandos a través de la herramienta Bash o la herramienta PowerShell, excepto una que falla la invocación directamente:

• shell: powershell, con la herramienta PowerShell habilitada: los comandos se ejecutan a través de la herramienta PowerShell.
• shell: bash cuando bash no está disponible: la invocación falla antes de que se ejecute ningún comando. Esto sucede en Windows sin Git Bash. Claude Code muestra Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found.
• Cualquier otra combinación: los comandos se ejecutan a través de la herramienta Bash cuando bash está disponible. Cuando no lo está, se ejecutan a través de la herramienta PowerShell.

Cualquiera de las herramientas ejecuta los comandos de la misma manera que ejecuta los propios comandos de shell de Claude. Comparten el directorio de trabajo, el tiempo de espera y el manejo de salida:

• Directorio de trabajo: Claude Code ejecuta cada comando en el directorio de trabajo actual del shell de la sesión. Ese directorio se mueve cuando Claude ejecuta cd. Use ${CLAUDE_SKILL_DIR} o ${CLAUDE_PROJECT_DIR} en rutas que deben resolverse de la misma manera cada vez.
• stderr: con el shell bash predeterminado, Claude Code fusiona stderr en stdout. Cualquier cosa que el comando escriba en stderr aparece en el texto inyectado.
• Tiempo de espera: cada comando se ejecuta bajo el tiempo de espera predeterminado de 2 minutos de la herramienta Bash. Cuando la herramienta Bash mueve un comando que agotó el tiempo de espera al fondo, la skill aún se renderiza. El texto inyectado informa el movimiento y nombra la tarea de fondo y el archivo que recopila la salida del comando. Cuando el comando es uno que la herramienta Bash nunca pone automáticamente en segundo plano, Claude Code lo mata en el tiempo de espera. Esa falla aborta la invocación.
• Tamaño de salida: la salida más allá del techo en línea de la herramienta Bash llega como una ruta de archivo más una vista previa corta, no texto truncado. Output limits cubre el techo y cómo ajustar cada límite.

La herramienta PowerShell aplica el mismo comportamiento de tiempo de espera, puesta en segundo plano y techo de salida a los comandos que ejecuta. Consulte la sección herramienta PowerShell para obtener sus detalles específicos.

Cuando un comando inyectado falla

Un comando fallido aborta toda la invocación del skill, no solo su propio marcador de posición. Claude nunca ve el contenido del skill para esa invocación. El aborto muestra Shell command failed for pattern "...". El mensaje de error incluye la salida del comando.

Con el shell bash predeterminado, cualquier código de salida distinto de cero cuenta como un fallo. Se aplica una excepción: Claude Code trata el código de salida 1 de comandos de búsqueda y comparación como un resultado normal e inyecta su salida. Los códigos de salida de 2 o superior fallan incluso para esos comandos.

Qué comandos obtienen la excepción depende del shell:

• Shell bash predeterminado: los comandos enumerados en Output limits
• shell: powershell, cuando la herramienta PowerShell está habilitada: un conjunto diferente que incluye grep y git diff pero no find ni diff

Con el shell bash predeterminado, agregue || true a cualquier otro comando que espere que salga con un código distinto de cero. Un script de verificación que sale con 1 cuando encuentra problemas es un ejemplo.

Cuando no se ejecutó ningún comando de shell

No shell command in <name> was run significa que uno de sus comandos de shell contiene un carácter que la herramienta no acepta. Para encontrar y eliminar el carácter, consulta la referencia de errores.

Verificaciones de permisos en comandos inyectados

Los comandos inyectados nunca solicitan permiso mientras se renderiza la skill. Claude Code verifica cada uno contra sus reglas de permisos primero. Un comando que una regla de denegación coincide aborta la invocación con Shell command permission check failed for pattern "...".

Fuera del modo automático, cuando la verificación de permisos de un comando devuelve algo distinto de permitir, Claude Code aborta la invocación con el mismo error. Esto incluye una regla que normalmente te pediría confirmación. Para evitar que un comando sin coincidencia aborte aquí, apruébalo previamente con allowed-tools. Si tu organización restringe las reglas de permisos a la configuración administrada, consulta Cuando solo se aplican reglas de permisos administradas. Las reglas de denegación y de solicitud siguen teniendo prioridad sobre allowed-tools. Consulta Administrar permisos.

En modo automático, un comando que de otro modo necesitaría su aprobación no aborta la invocación. La skill se carga con una instrucción que le dice a Claude que ejecute el comando primero, y la llamada propia de Claude luego pasa por las verificaciones habituales del modo automático. La invocación aún aborta en una skill bifurcada que establece agent, y en una sesión donde Claude no tiene la herramienta de shell que ejecuta comandos inyectados.

Ejecutar skills en un subagente

Agregue context: fork a su frontmatter cuando desee que una skill se ejecute en aislamiento. Claude Code inicia un nuevo subagente del tipo establecido en el campo agent y le da el contenido de la skill como su prompt. El subagente no ve su historial de conversación, por lo que las instrucciones de la skill tienen que ser autosuficientes.

[!NOTE]

A pesar del nombre, una skill con context: fork no se ejecuta en un fork de la conversación actual, que entregaría al subagente todo lo que ha discutido hasta ahora. Cuando la tarea depende de ese historial, bifurque la conversación en lugar de usar context: fork.

El subagente bifurcado se ejecuta en segundo plano: sigues trabajando mientras se ejecuta, y su resultado llega a tu conversación cuando termina. Establece background: false en el frontmatter para, en cambio, esperar el resultado en el turno que invocó el skill.

Claude Code también espera el resultado, incluso cuando la skill no establece background: false, en casos como estos:

• En modo no interactivo, con la bandera -p o el Agent SDK
• Cuando estableces CLAUDE_CODE_DISABLE_BACKGROUND_TASKS en 1, lo que también desactiva otras funciones de tareas en segundo plano
• Cuando invoca una skill bifurcada mientras una invocación anterior de la misma skill aún se está ejecutando
• Cuando una tarea programada con alcance de sesión se dispara con el skill como su prompt

Cuando un agente en un flujo de trabajo dinámico invoca un skill bifurcado, ese agente espera y recibe el resultado, incluso cuando el skill no establece background: false. Antes de v2.1.295, cuando el skill se ejecutaba en segundo plano, ese agente no lo esperaba. El resultado del skill llegaba entonces a tu conversación principal en lugar de llegar al agente.

Un fork en segundo plano también se ejecuta con el conjunto de herramientas más estrecho que se aplica a los subagentes en segundo plano: el subagente de la skill es un tipo de agente regular, por lo que la exención para subagentes que bifurcan la conversación no lo cubre. Si los pasos de su skill dependen de una herramienta fuera de ese conjunto, establezca background: false para mantener el conjunto completo de herramientas.

Un skill bifurcado que se ejecuta en segundo plano aplica sus ediciones fuera de los checkpoints de tu sesión. Después de uno, /rewind restaura solo los archivos que Claude ya había editado en tu conversación. Las ediciones del skill en otros archivos se mantienen, así que usa git para revertirlas.

[!WARNING]

context: fork solo tiene sentido para skills con instrucciones explícitas. Si su skill contiene directrices como "use estas convenciones de API" sin una tarea, el subagente recibe las directrices pero sin un prompt procesable, y regresa sin salida significativa.

Las skills y los subagentes funcionan juntos en dos direcciones:

Con context: fork, escribes la tarea en tu skill y eliges un tipo de agente para ejecutarla. Los agentes integrados Explore y Plan se inician sin CLAUDE.md ni el estado de git para mantener su contexto pequeño. Pon todo lo que la tarea necesita en tu SKILL.md. Un skill bifurcado que usa agent: Explore se inicia con ese contenido y el prompt del sistema propio del agente, y ninguno de tus archivos CLAUDE.md.

Para el caso inverso, en el que defines un subagente personalizado que usa skills como material de referencia, consulta Subagentes.

Ejemplo: Skill de investigación usando agente Explore

Esta skill ejecuta investigación en un agente Explore bifurcado. El contenido de la skill se convierte en la tarea, y el agente proporciona herramientas de solo lectura optimizadas para la exploración de bases de código:

---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:

1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

Cuando se ejecuta esta skill:

1. Se crea un nuevo contexto aislado
2. El subagente recibe el contenido de la skill como su prompt (las instrucciones "Research $ARGUMENTS thoroughly")
3. El campo agent determina el entorno de ejecución (modelo, herramientas y permisos)
4. El subagente resume sus resultados y los devuelve a su conversación principal cuando termina

El campo agent especifica qué configuración de subagente usar. Las opciones incluyen agentes integrados (Explore, Plan, general-purpose) o cualquier subagente personalizado de .claude/agents/. Si se omite, usa general-purpose.

Restringir el acceso de Claude a las skills

De forma predeterminada, Claude puede invocar cualquier skill que no tenga establecido disable-model-invocation: true. Los skills que definen allowed-tools le otorgan a Claude acceso a esas herramientas sin aprobación por uso durante el turno que invoca el skill; la concesión se elimina cuando envías tu siguiente mensaje. Tu configuración de permisos sigue rigiendo el comportamiento de aprobación base para todas las demás herramientas. Algunos comandos integrados también están disponibles a través de la herramienta Skill, incluidos /init y /security-review. Otros comandos integrados como /compact no lo están.

Tres formas de controlar qué skills puede invocar Claude:

Desactivar todas las skills denegando la herramienta Skill en /permissions:

# Add to deny rules:
Skill

Permitir o denegar skills específicas usando reglas de permisos:

# Allow only specific skills
Skill(commit)
Skill(review-pr *)

# Deny specific skills
Skill(deploy *)

Sintaxis de permisos: Skill(name) para coincidencia exacta, Skill(name *) para coincidencia de prefijo con cualquier argumento.

La tabla muestra qué bloquea una regla deny más allá del nombre que escribe, según el tipo de nombre en la regla.

Antes de v2.1.260, Claude Code no bloqueaba una skill anidada listada bajo su nombre calificado cuando la regla de denegación solo nombraba el nombre no calificado.

Claude Code coincide una regla allow solo contra el nombre de la skill y el nombre en la invocación de Claude. Para aprobar una skill sincronizada sin un prompt, nombre la dentro de su espacio de nombres reservado:

• Skill(anthropic-skills:pdf) aprueba la skill pdf sincronizada
• Skill(anthropic-skills *) aprueba cada skill sincronizada
• Skill(anthropic *) no cubre anthropic-skills:pdf, porque un prefijo fuera del espacio de nombres no coincide con los nombres dentro de él

Ocultar skills individuales agregando disable-model-invocation: true a su frontmatter. Esto elimina la skill del contexto de Claude por completo.

[!NOTE]

Con user-invocable: false, no puede invocar la skill, pero Claude aún puede. Para evitar que Claude la invoque a través de la herramienta Skill, establezca disable-model-invocation: true.

Anular la visibilidad de la skill desde la configuración

La configuración skillOverrides controla la visibilidad de la skill desde su configuración en lugar del frontmatter de la skill. Úsela para skills cuyo SKILL.md no desea editar, como las que se registran en un repositorio de proyecto compartido. El menú /skills lo escribe por usted: resalte una skill y presione Space para ciclar estados, luego Esc para guardar en .claude/settings.local.json.

Cada clave es un nombre de skill y cada valor es uno de cuatro estados:

El menú /skills etiqueta el estado "user-invocable-only" como user-only.

"off" también oculta el skill de las listas de comandos que se anuncian a los clientes de Remote Control y a quienes llaman al Agent SDK, además del menú / de la terminal. Invocar un skill oculto por su nombre completo devuelve el error de skillOverrides en lugar de ejecutarlo.

Una skill que está ausente de skillOverrides se trata como "on". El ejemplo a continuación colapsa una skill a su nombre y desactiva otra por completo:

{
  "skillOverrides": {
    "legacy-context": "name-only",
    "deploy": "off"
  }
}

Algunas skills agrupadas tienen alias, como checkup para /doctor. Si establece una entrada skillOverrides bajo un alias en managed settings o en un archivo que pasa con la bandera --settings, Claude Code la aplica a la skill detrás del alias. Solo puede restringir una skill más a través de un alias, nunca hacerla más visible, y si también establece una entrada bajo el nombre de la skill en managed settings, esa entrada tiene prioridad. Antes de v2.1.260, Claude Code no aplicaba una entrada bajo un alias a la skill en ninguna fuente de configuración.

En configuración de usuario, proyecto y local, Claude Code coincide entradas solo contra nombres de skill. Si establece una entrada para review allí, se aplica a una skill nombrada review, no al /code-review agrupado a través de su alias /review.

Las skills de plugins no se ven afectadas por skillOverrides. Administre esas a través de /plugin en su lugar.

Encontrar skills no utilizadas

Cada skill en el listado de skills se suma a su contexto en cada turno, independientemente de si Claude la usa o no. Ejecute /skill-doctor para ver qué cuesta cada una de sus skills y con qué frecuencia se usa, para que pueda decidir cuáles desactivar. En una sesión interactiva, el informe se abre en la pestaña Stats del administrador /plugin. En modo no interactivo con -p, Claude Code lo imprime como texto.

El informe cubre las skills en su sesión que no sean skills agrupadas ni skills empresariales. Marca las skills en el listado que nunca se han invocado y dice dónde desactivarlas. De las skills que le dice dónde desactivar, comience con las que tienen el costo de contexto más alto. El informe también enumera los plugins que no ha usado recientemente.

/skill-doctor requiere Claude Code v2.1.252 o posterior y no está disponible en sesiones que omiten obtención de banderas de características. Si ejecuta /skill-doctor sobre Remote Control desde su teléfono o navegador, Claude Code responde Skill usage reports are not available on this connection. en su lugar. Ejecute /skill-doctor en el terminal en la máquina donde se ejecuta la sesión.

Evaluar e iterar sobre una skill

Ver que una skill se activa le indica que Claude la encontró, no que haya hecho lo que usted pretendía. Para saber que una skill funciona, mida dos cosas por separado: si Claude la invoca en los prompts que debería, y si la salida coincide con lo que espera cuando lo hace.

La verificación de ambas es una comparación de línea base. Recopile algunos prompts realistas, ejecute cada uno en una sesión nueva con la skill disponible y nuevamente con ella deshabilitada, y compare los resultados. Una sesión nueva es importante porque el contexto residual de la creación de la skill enmascarará las brechas en las instrucciones escritas.

Cómo desactiva la skill para la segunda ejecución depende de dónde provenga:

• Skill personal o de proyecto: establézcala en "off" en skillOverrides.
• Skill que proporciona un plugin: skillOverrides no se aplica a las skills de plugins. Use claude plugin eval en su lugar, que repite cada ejecución sin plugin cargado.

Dos herramientas automatizan la comparación de línea base. Para una skill que se distribuye en un plugin, claude plugin eval ejecuta cada prompt en una sesión aislada con y sin el plugin, la califica con evaluadores que usted define o que escribe por usted, y sale con un código distinto de cero por debajo de un umbral para que pueda controlar su CI. Para iterar sobre una única skill dentro de una conversación de Claude Code, el plugin skill-creator a continuación ejecuta un bucle similar con su propio formato evals/evals.json. Los dos formatos no son intercambiables.

Ejecutar evals con skill-creator

El plugin skill-creator automatiza el bucle de comparación dentro de Claude Code. En la extensión de VS Code o en la aplicación de escritorio, instálalo desde el marketplace oficial siguiendo Instalar un plugin. En una terminal, inicia Claude Code ejecutando claude y luego escribe esto en su prompt:

/plugin install skill-creator@claude-plugins-official

Si la instalación falla, haga coincidir el mensaje que Claude Code reporta:

• Marketplace "claude-plugins-official" not found: agregue el marketplace con /plugin marketplace add anthropics/claude-plugins-official, luego reintente la instalación.
• Plugin "<name>" not found in marketplace "claude-plugins-official": es posible que tu copia local del catálogo del marketplace esté desactualizada. Actualízala con /plugin marketplace update claude-plugins-official y luego reintenta la instalación. Si el reintento muestra el mismo mensaje, consulta Plugin no encontrado en el marketplace.

Si el resumen de instalación reporta Run /reload-plugins to apply., Claude Code ejecuta esa recarga por ti. Si la recarga advierte que tu próximo mensaje volvería a leer la conversación, ejecuta /reload-plugins --force para que los skills del plugin estén disponibles en la sesión actual. Luego pide a Claude que evalúe un skill existente, por ejemplo evaluate my summarize-changes skill with skill-creator. El plugin te guía a través de la escritura de casos de prueba y ejecuta el bucle:

• Casos de prueba: almacena prompts, archivos de entrada y comportamiento esperado en evals/evals.json dentro del directorio de la skill
• Ejecuciones aisladas: genera una subagente por caso de prueba para que cada ejecución comience con un contexto limpio, y registra el recuento de tokens y la duración
• Calificación: verifica cada aserción contra la salida y escribe aprobado o reprobado con evidencia en grading.json
• Benchmark: agrega la tasa de aprobación, tiempo y tokens para con-skill versus sin-skill en benchmark.json para que pueda comparar la mejora de la tasa de aprobación contra la sobrecarga de tokens y tiempo
• Comparación de versiones: ejecuta una prueba A/B ciega entre dos versiones de la skill para que pueda confirmar que una edición es una mejora antes de confirmarla
• Ajuste de descripción: genera prompts de debe-activarse y no-debe-activarse, mide la tasa de aciertos, y propone ediciones de descripción cuando la skill se activa en solicitudes incorrectas
• Visor de revisión: abre un informe HTML donde puede inspeccionar cada salida y registrar comentarios cualitativos que la siguiente iteración lee

Para el formato del archivo eval y el flujo de trabajo de iteración completo, consulte Evaluating skill output quality en agentskills.io. Para obtener información sobre los modos de benchmark y comparación, consulte el anuncio de skill-creator.

Compartir skills

Los skills se pueden distribuir en diferentes ámbitos según su audiencia:

• Skills de proyecto: Confirmar .claude/skills/ en el control de versiones
• Plugins: Crear un directorio skills/ en su plugin
• Administrado: Implementar en toda la organización a través de configuración administrada

Generar salida visual

Los skills pueden agrupar y ejecutar scripts en cualquier lenguaje, dando a Claude capacidades más allá de lo que es posible en un único prompt. Un patrón es generar salida visual: archivos HTML interactivos que se abren en su navegador para explorar datos, depurar o crear informes.

Este ejemplo crea un explorador de base de código: una vista de árbol interactiva donde puede expandir y contraer directorios, ver tamaños de archivo de un vistazo e identificar tipos de archivo por color.

Cree el directorio Skill:

mkdir -p ~/.claude/skills/codebase-visualizer/scripts

Guarde esto en ~/.claude/skills/codebase-visualizer/SKILL.md. La descripción le dice a Claude cuándo activar este Skill, y las instrucciones le dicen a Claude que ejecute el script incluido. La ruta del script utiliza ${CLAUDE_SKILL_DIR} para que se resuelva correctamente si el skill se instala a nivel personal, de proyecto o de plugin:

---
name: codebase-visualizer
description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo, understanding project structure, or identifying large files.
allowed-tools: Bash(python3 *)
---

# Codebase Visualizer

Generate an interactive HTML tree view that shows your project's file structure with collapsible directories.

## Usage

Run the visualization script from your project root:

```bash
python3 ${CLAUDE_SKILL_DIR}/scripts/visualize.py .
```

This creates `codebase-map.html` in the current directory and opens it in your default browser.

## What the visualization shows

- **Collapsible directories**: Click folders to expand/collapse
- **File sizes**: Displayed next to each file
- **Colors**: Different colors for different file types
- **Directory totals**: Shows aggregate size of each folder

Guarde esto en ~/.claude/skills/codebase-visualizer/scripts/visualize.py. Este script escanea un árbol de directorios y genera un archivo HTML independiente con:

• Una barra lateral de resumen que muestra el recuento de archivos, recuento de directorios, tamaño total y número de tipos de archivo
• Un gráfico de barras que desglosa la base de código por tipo de archivo (los 8 principales por tamaño)
• Un árbol contraíble donde puede expandir y contraer directorios, con indicadores de tipo de archivo codificados por color

El script requiere Python 3 pero utiliza solo bibliotecas integradas, por lo que no hay paquetes que instalar:

#!/usr/bin/env python3
"""Generate an interactive collapsible tree visualization of a codebase."""

import json
import sys
import webbrowser
from html import escape
from pathlib import Path
from collections import Counter

IGNORE = {'.git', 'node_modules', '__pycache__', '.venv', 'venv', 'dist', 'build'}

def scan(path: Path, stats: dict) -> dict:
    result = {"name": path.name, "children": [], "size": 0}
    try:
        for item in sorted(path.iterdir()):
            if item.name in IGNORE or item.name.startswith('.'):
                continue
            if item.is_file():
                size = item.stat().st_size
                ext = item.suffix.lower() or '(no ext)'
                result["children"].append({"name": item.name, "size": size, "ext": ext})
                result["size"] += size
                stats["files"] += 1
                stats["extensions"][ext] += 1
                stats["ext_sizes"][ext] += size
            elif item.is_dir():
                stats["dirs"] += 1
                child = scan(item, stats)
                if child["children"]:
                    result["children"].append(child)
                    result["size"] += child["size"]
    except PermissionError:
        pass
    return result

def generate_html(data: dict, stats: dict, output: Path) -> None:
    ext_sizes = stats["ext_sizes"]
    total_size = sum(ext_sizes.values()) or 1
    sorted_exts = sorted(ext_sizes.items(), key=lambda x: -x[1])[:8]
    colors = {
        '.js': '#f7df1e', '.ts': '#3178c6', '.py': '#3776ab', '.go': '#00add8',
        '.rs': '#dea584', '.rb': '#cc342d', '.css': '#264de4', '.html': '#e34c26',
        '.json': '#6b7280', '.md': '#083fa1', '.yaml': '#cb171e', '.yml': '#cb171e',
        '.mdx': '#083fa1', '.tsx': '#3178c6', '.jsx': '#61dafb', '.sh': '#4eaa25',
    }
    lang_bars = "".join(
        f'<div class="bar-row"><span class="bar-label">{ext}</span>'
        f'<div class="bar" style="width:{(size/total_size)*100}%;background:{colors.get(ext,"#6b7280")}"></div>'
        f'<span class="bar-pct">{(size/total_size)*100:.1f}%</span></div>'
        for ext, size in sorted_exts
    )
    def fmt(b):
        if b < 1024: return f"{b} B"
        if b < 1048576: return f"{b/1024:.1f} KB"
        return f"{b/1048576:.1f} MB"

    html = f'''<!DOCTYPE html>
<html><head>
  <meta charset="utf-8"><title>Codebase Explorer</title>
  <style>
    body {{ font: 14px/1.5 system-ui, sans-serif; margin: 0; background: #1a1a2e; color: #eee; }}
    .container {{ display: flex; height: 100vh; }}
    .sidebar {{ width: 280px; background: #252542; padding: 20px; border-right: 1px solid #3d3d5c; overflow-y: auto; flex-shrink: 0; }}
    .main {{ flex: 1; padding: 20px; overflow-y: auto; }}
    h1 {{ margin: 0 0 10px 0; font-size: 18px; }}
    h2 {{ margin: 20px 0 10px 0; font-size: 14px; color: #888; text-transform: uppercase; }}
    .stat {{ display: flex; justify-content: space-between; padding: 8px 0; border-bottom: 1px solid #3d3d5c; }}
    .stat-value {{ font-weight: bold; }}
    .bar-row {{ display: flex; align-items: center; margin: 6px 0; }}
    .bar-label {{ width: 55px; font-size: 12px; color: #aaa; }}
    .bar {{ height: 18px; border-radius: 3px; }}
    .bar-pct {{ margin-left: 8px; font-size: 12px; color: #666; }}
    .tree {{ list-style: none; padding-left: 20px; }}
    details {{ cursor: pointer; }}
    summary {{ padding: 4px 8px; border-radius: 4px; }}
    summary:hover {{ background: #2d2d44; }}
    .folder {{ color: #ffd700; }}
    .file {{ display: flex; align-items: center; padding: 4px 8px; border-radius: 4px; }}
    .file:hover {{ background: #2d2d44; }}
    .size {{ color: #888; margin-left: auto; font-size: 12px; }}
    .dot {{ width: 8px; height: 8px; border-radius: 50%; margin-right: 8px; }}
  </style>
</head><body>
  <div class="container">
    <div class="sidebar">
      <h1>📊 Summary</h1>
      <div class="stat"><span>Files</span><span class="stat-value">{stats["files"]:,}</span></div>
      <div class="stat"><span>Directories</span><span class="stat-value">{stats["dirs"]:,}</span></div>
      <div class="stat"><span>Total size</span><span class="stat-value">{fmt(data["size"])}</span></div>
      <div class="stat"><span>File types</span><span class="stat-value">{len(stats["extensions"])}</span></div>
      <h2>By file type</h2>
      {lang_bars}
    </div>
    <div class="main">
      <h1>📁 {escape(data["name"])}</h1>
      <ul class="tree" id="root"></ul>
    </div>
  </div>
</body></html>'''
    output.write_text(html)

if __name__ == '__main__':
    target = Path(sys.argv[1] if len(sys.argv) > 1 else '.').resolve()
    stats = {"files": 0, "dirs": 0, "extensions": Counter(), "ext_sizes": Counter()}
    data = scan(target, stats)
    out = Path('codebase-map.html')
    generate_html(data, stats, out)
    print(f'Generated {out.absolute()}')
    webbrowser.open(f'file://{out.absolute()}')

Para probar, abra Claude Code en cualquier proyecto y pregunte "Visualize this codebase." Claude ejecuta el script, que imprime la ruta del archivo generado, como Generated /path/to/codebase-map.html, y lo abre en su navegador. Si trabaja en un entorno sin interfaz gráfica donde no se abre ningún navegador, la ruta impresa confirma que el script se ejecutó correctamente.

Este patrón funciona para cualquier salida visual: gráficos de dependencias, informes de cobertura de pruebas, documentación de API o visualizaciones de esquemas de bases de datos. El script incluido realiza el trabajo mientras Claude maneja la orquestación.

Solución de problemas

Skill no se activa

Si Claude no utiliza su skill cuando se espera:

1. Verifique que la descripción incluya palabras clave que los usuarios dirían naturalmente
2. Confirme que el skill aparece en ¿Qué skills están disponibles?
3. Intente reformular su solicitud para que coincida más estrechamente con la descripción
4. Invóquelo directamente con /skill-name si el skill es invocable por el usuario
5. Si /skill-name tampoco se reconoce, verifica si Claude Code rechazó el nombre del skill
6. Si el skill define paths, verifica que los archivos que Claude lee, edita o escribe estén dentro del directorio de trabajo actual de Claude. El skill no se activa para archivos fuera de él, como los de un worktree de git hermano, incluso uno que hayas agregado con /add-dir. Para que el skill se active para esos archivos, inicia Claude Code en ese worktree o mueve la sesión allí con /cd.

Si el YAML del frontmatter está mal formado, Claude Code carga el cuerpo del skill con metadatos vacíos, por lo que /skill-name sigue funcionando pero Claude no puede comparar contra su description. Ejecute con --debug para ver el error de análisis.

Si el skill se distribuye en un plugin, puede medir con qué frecuencia se activa en solicitudes realistas en lugar de verificar una por una: escriba un caso de evaluación con un calificador tool_used: Skill y ejecútelo con claude plugin eval después de cada cambio de descripción.

Para encontrar archivos SKILL.md cuyo frontmatter no se analiza, ejecute claude plugin validate en el directorio de skills, por ejemplo claude plugin validate .claude/skills para skills de proyecto o claude plugin validate ~/.claude/skills para skills personales. Requiere Claude Code v2.1.233 o posterior.

Skill se activa demasiado a menudo

Si Claude utiliza su skill cuando no lo desea:

1. Haga la descripción más específica
2. Agregue disable-model-invocation: true si solo desea invocación manual

Claude deja de seguir un skill

Si Claude sigue un skill en su primera respuesta y deja de seguirlo después, comience con el caso que coincida:

• Claude omitió una regla que debe cumplirse cada vez: mueva la regla a un hook. Claude Code ejecuta un hook cada vez que ocurre su evento, como antes de cada edición de archivo, independientemente de si Claude está siguiendo el skill o no. Para mantener la regla con el skill, defina el hook en el frontmatter hooks del skill. Ese hook se aplica desde el momento en que se invoca el skill hasta que termina la sesión.
• Claude omitió orientación que debería aplicar con criterio: redacte la orientación para que se aplique a toda la tarea, por ejemplo "Ejecute las pruebas después de cada edición" en lugar de "Ejecute las pruebas". Claude Code agrega el contenido del skill a la conversación cuando se invoca el skill y no vuelve a leer el archivo en turnos posteriores.
• La conversación fue compactada: invoque el skill nuevamente para restaurar su contenido completo. Después de la compactación, Claude Code puede mantener solo el inicio de un skill invocado, por lo que coloque las instrucciones más importantes cerca de la parte superior de SKILL.md.

Las descripciones de skills se cortan

Claude Code carga un listado de nombres y descripciones de skills en el contexto para que Claude sepa qué está disponible. El listado siempre contiene todos los nombres de skills, pero si tiene muchos skills, Claude Code acorta las descripciones para ajustarse al presupuesto de caracteres del listado, lo que puede eliminar las palabras clave que Claude necesita para comparar con su solicitud. El presupuesto se escala al 1% de la ventana de contexto del modelo. Cuando el listado se desborda, Claude Code elimina descripciones comenzando con los skills que invoca menos, por lo que los skills que utiliza más mantienen su texto completo.

Ejecute /doctor para obtener una estimación del costo de contexto del listado y sus mayores contribuyentes. Para encontrar skills que vale la pena desactivar, ejecute /skill-doctor. Cuando el listado excede su presupuesto, Claude Code también escribe una advertencia en el registro de depuración, visible con --debug.

La fila Skills en /context reporta el tamaño del listado después de que se aplica el presupuesto, por lo que coincide con lo que recibe el modelo. Antes de v2.1.196, la fila contaba el texto completo de cada descripción y podría mostrar un valor varias veces mayor que el presupuesto configurado.

Para aumentar el presupuesto, establezca la configuración skillListingBudgetFraction (por ejemplo, 0.02 = 2%) o la variable de entorno SLASH_COMMAND_TOOL_CHAR_BUDGET a un recuento de caracteres fijo. Para liberar presupuesto para otros skills, establezca entradas de baja prioridad en "name-only" en skillOverrides para que se listen sin descripción. También puede recortar el texto de description y when_to_use en la fuente: coloque el caso de uso clave primero, ya que el texto combinado de cada entrada está limitado a 1.536 caracteres independientemente del presupuesto. El límite es configurable con skillListingMaxDescChars.

Los corchetes angulares en la descripción de un skill se muestran como < y >

Claude Code muestra < y > en los campos description y when_to_use como < y >. Para mostrar un marcador de posición como <branch>, usa corchetes o argument-hint:

• Corchetes: reemplaza <branch> por [branch], que se muestra tal como lo escribes
• argument-hint: mueve el marcador de posición a una nueva línea argument-hint: <branch>. Se muestra después del nombre del comando. Si también subes el skill a claude.ai o a la Skills API, primero verifica si argument-hint se acepta allí.

Skills personales desaparecieron

Si las carpetas de skills que creó en ~/.claude/skills/ desaparecieron, busque en ~/.claude/skills/.trash/. Cuando Claude Code sincroniza skills desde claude.ai, las descarga en la subcarpeta separada synced y no mueve ni elimina las carpetas que crea.

Antes de v2.1.280, un archivo llamado manifest.json en ~/.claude/skills/ causaba que Claude Code moviera las carpetas de skills que ese archivo listaba a una carpeta con marca de tiempo bajo ~/.claude/skills/.trash/, y esos skills dejaban de cargarse.

Para restaurar un skill, mueva su carpeta de la carpeta con marca de tiempo de vuelta a ~/.claude/skills/. Haga esto antes de que la limpieza de retención elimine las entradas de papelera, por defecto 30 días después de que se movieron a la papelera.

Recursos relacionados

• Depura tu configuración: diagnostica por qué una skill no aparece o no se activa
• Evaluating skill output quality: el formato del archivo eval y el flujo de trabajo de iteración en agentskills.io
• Skill authoring best practices: orientación de escritura que se aplica en productos Claude
• Subagents: delega tareas a agents especializados
• Plugins: empaqueta y distribuye skills con otras extensiones
• Hooks: automatiza flujos de trabajo alrededor de eventos de herramientas
• Memory: gestiona archivos CLAUDE.md para contexto persistente
• Comandos: referencia para comandos integrados y skills agrupados
• Permisos: controla el acceso a herramientas y skills
• Claude Tag skills: skills de proyecto comprometidas en un repositorio también se cargan cuando ese repositorio se utiliza en un canal de Claude Tag