Conceptos básicos de comandos personalizados y subagentes

7 ejemplos para empezar con Comandos Personalizados y Subagentes: 5 básicos y 2 intermedios.

Prerrequisitos

• Una instalación funcional de Claude Code, invocada desde el directorio raíz de tu proyecto.
• Un directorio de comandos específico del proyecto en .claude/commands/ (se crea bajo demanda, no requiere paso de instalación).
• Sin paquetes adicionales. Los comandos son solo archivos markdown; los subagentes se generan a través de la herramienta Agent integrada, no hay nada que configurar por adelantado.

Ejemplos básicos

1. Crear un directorio de comandos

Cada comando personalizado vive como un archivo markdown bajo .claude/commands/.

mkdir -p .claude/commands

• Claude Code escanea este directorio automáticamente; no se necesita ningún paso de registro más allá de crear el archivo.
• Los comandos aquí son específicos del proyecto y se registran en el control de versiones junto con el resto del repositorio.
• También existe un equivalente a nivel de usuario para los comandos que deseas que estén disponibles en todos los proyectos, pero el ámbito del proyecto es la opción predeterminada correcta para los comandos compartidos en equipo.

2. Escribir un comando de barra diagonal de una línea

El comando más simple es una cabecera de metadatos (frontmatter) y una sola frase de indicación (prompt).

---
description: Resume el diff de git actual en lenguaje claro
---
 
Resume los cambios de git actualmente preparados en dos o tres frases, escritas para un compañero de equipo que aún no ha visto el diff.

• Guarda esto como .claude/commands/summarize-diff.md y el comando estará disponible como /summarize-diff.
• El campo description de los metadatos es lo que se muestra cuando un usuario completa con tabulación los comandos disponibles.
• El cuerpo debajo de los metadatos se envía a la conversación exactamente como está escrito, como si el usuario lo hubiera pegado él mismo.

3. Invocar el comando

Una vez que el archivo existe, el comando está activo inmediatamente, sin necesidad de reinicio.

# dentro de una sesión de Claude Code
/summarize-diff

• Escribir /summarize-diff inserta el cuerpo de la indicación del archivo en la conversación y lo ejecuta de inmediato.
• Dado que la indicación se almacena en disco, cada compañero de equipo que obtenga el repositorio obtiene el comando idéntico.
• Editar el archivo markdown cambia el comportamiento del comando la próxima vez que se invoque, sin necesidad de un paso de reconstrucción.

Relacionado: Escribiendo tu primer comando de barra diagonal personalizado con metadatos Markdown - el esquema completo de metadatos

4. Aceptar argumentos en un comando

Los comandos pueden hacer referencia al texto escrito después del nombre del comando.

---
description: Explica el propósito de un archivo específico
---
 
Lee $ARGUMENTS y explica qué hace, quién lo llama y cualquier efecto secundario no obvio, en menos de 150 palabras.

• $ARGUMENTS se reemplaza con lo que el usuario escribió después del nombre del comando, por ejemplo, /explain-file lib/auth.ts.
• Esto convierte un comando único en una plantilla reutilizable en lugar de una indicación fija y codificada.
• Si no se proporcionan argumentos, $ARGUMENTS está vacío, así que redacta la indicación para que se degrade con gracia o indica que se requiere un objetivo.

5. Generar un subagente único

Un subagente es una instancia de Claude separada con su propio contexto, lanzada para manejar una tarea delimitada.

# una solicitud en lenguaje claro en la sesión principal, no un comando de shell
# "Usa un subagente para encontrar todos los lugares donde se envían correos electrónicos de notificación
#  en esta base de código y resume las condiciones de activación para cada uno."

• El subagente explora la base de código en su propio contexto aislado y devuelve solo un resumen a la sesión principal.
• Ninguna de las lecturas de archivos intermedios o pasos de búsqueda del subagente contamina la ventana de contexto de la conversación principal.
• Este es el movimiento correcto cuando una tarea es exploratoria y de lo contrario consumiría mucho contexto en callejones sin salida.

Relacionado: Cómo los subagentes obtienen su propio contexto y herramientas - por qué existe el aislamiento

Ejemplos intermedios

6. Combinar un comando con una solicitud de subagente

El cuerpo de la indicación de un comando puede pedirle a Claude que delegue en un subagente.

---
description: Audita un área de características e informa los hallazgos, sin descarrilar la sesión principal
---
 
Usa un subagente para investigar cómo se implementa $ARGUMENTS en esta base de código:
puntos de entrada, flujo de datos y cualquier prueba que lo cubra. Haz que el subagente devuelva
un resumen conciso (rutas de archivo y una breve descripción cada una), no el contenido completo de los archivos.

• Guardado como .claude/commands/audit-feature.md, esto hace que /audit-feature payment retries sea una línea única repetible que siempre delega de la misma manera.
• La sesión principal solo ve el resumen del subagente, manteniendo su propio contexto libre para la corrección real o el trabajo de características que sigue.
• Redactar la indicación para pedir explícitamente "un resumen conciso, no el contenido completo de los archivos" es importante, ya que un subagente de lo contrario informará todo lo que encontró.

7. Distribuir varios subagentes desde un comando

Para auditorías más grandes, un solo comando puede solicitar que se ejecuten varios subagentes en partes independientes de la base de código a la vez.

---
description: Investiga tres subsistemas en paralelo y compara sus patrones
---
 
Genera tres subagentes en paralelo, uno para cada uno de: el código de autenticación,
el código de facturación y el código de notificaciones. Cada subagente debe devolver
el patrón de manejo de errores que encuentre en su área. Luego, compara los
tres patrones y anota cualquier inconsistencia que valga la pena corregir.

• Dado que cada subagente obtiene su propio contexto aislado, las tres tareas de investigación no interfieren ni contaminan los hallazgos de los demás.
• Ejecutarlos en paralelo es más rápido que investigar cada subsistema secuencialmente en la sesión principal.
• La sesión principal solo tiene que razonar sobre tres resúmenes cortos, no sobre la amplitud completa de los archivos que cada subagente abrió realmente.

Relacionado: Generación de subagentes en paralelo para tareas de investigación aisladas - el patrón de distribución en profundidad

Versiones de la pila: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026: Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5. Los nombres de los modelos, los precios y las características del producto cambian rápidamente: verifique los detalles actuales en platform.claude.com/docs antes de confiar en ellos.