Comandos slash personalizados en Claude Code: /review, /handoff y /release para equipos

Pegas otra vez la misma checklist de revisión. Antes de publicar, intentas recordar los pasos del release. Al final de una sesión larga con Claude Code, todavía tienes que escribir a mano qué se hizo y qué queda pendiente. Cuanto más usa un equipo un agente de programación, más valor tienen estos pequeños rituales repetibles.

Los comandos slash personalizados convierten esos prompts repetidos en nombres cortos que todo el equipo entiende. Un comando como /review, /handoff o /release no es solo un atajo. Bien diseñado, se convierte en una forma compartida de revisar código, transferir contexto y decidir si algo está listo para salir.

Este artículo sigue la documentación oficial de Claude Code Skills y la referencia de Commands, verificadas el 3 de junio de 2026. El cambio importante es que los comandos personalizados ahora están integrados en Skills. Los archivos existentes en .claude/commands/*.md siguen funcionando, pero para workflows de equipo suele ser mejor usar .claude/skills/<name>/SKILL.md.

Idea principal: un comando es un procedimiento reutilizable

En Claude Code, los comandos son mensajes que empiezan con / dentro de una sesión. La referencia oficial explica que el comando se reconoce al inicio del mensaje y que el texto posterior se pasa como argumento. Por eso /release 1.8.0 puede usar 1.8.0 como versión, y /handoff frontend reviewer puede indicar para quién se prepara la nota.

Un Skill es un paquete reutilizable de instrucciones para Claude. En lenguaje simple, es un pequeño manual de trabajo: cuándo usarlo, qué pasos seguir, qué entrada importa y qué formato de salida se espera. Los archivos antiguos de .claude/commands/ siguen siendo válidos, pero Skills añade estructura de carpetas, frontmatter, archivos auxiliares, argumentos con nombre y un flujo de revisión más claro.

Hay una trampa práctica: el nombre. Las instalaciones actuales de Claude Code pueden traer comandos como /review, /code-review o /security-review. Antes de crear un /review propio, escribe / y revisa el menú. Si el nombre ya existe, usa /team-review, /review-note u otro nombre específico del equipo. En este artículo hablamos del patrón de review; el nombre exacto debe evitar conflictos en tu entorno.

Ubicación de archivos: prioriza Skills y conserva Commands por compatibilidad

Si la regla es del equipo, debe vivir dentro del proyecto, no solo en el directorio personal de una persona. Los Skills de proyecto se pueden versionar, revisar en pull requests y modificar junto con el repositorio. Los Skills personales sirven para flujos privados, pero no deberían contener reglas que todos dependen de usar.

Ubicación	Ejemplo	Mejor uso
Skill de proyecto	.claude/skills/team-review/SKILL.md	Reviews, releases, investigación y onboarding compartidos
Command de proyecto	.claude/commands/handoff.md	Comandos ligeros existentes o transición durante una migración
Skill personal	~/.claude/skills/my-note/SKILL.md	Notas personales y rutinas privadas
Command personal	~/.claude/commands/my-command.md	Atajos temporales

Una estructura limpia se ve así:

.claude/
├── commands/
│   └── handoff.md
└── skills/
    ├── team-review/
    │   ├── SKILL.md
    │   └── checklists/
    │       └── review.md
    └── release-prep/
        ├── SKILL.md
        └── scripts/
            └── collect-release-notes.sh

El modelo mental es sencillo: el repositorio guarda el procedimiento, el menú / lo expone como comando, la persona pasa argumentos y Claude Code combina esa instrucción con el contexto actual.

flowchart LR
  A[".claude/skills o .claude/commands"] --> B["Comando como /team-review"]
  B --> C["Argumentos: $ARGUMENTS o $version"]
  C --> D["Claude Code carga las instrucciones"]
  D --> E["Review, handoff o preparación de release"]
  E --> F["Una persona revisa y decide si se mergea o publica"]

Después de añadir o modificar un Skill, comprueba si aparece en el menú /. Si la sesión actual no lo detecta, usa /reload-skills o abre una sesión nueva. Revisa también la descripción, porque es la forma en que otras personas encontrarán el workflow.

Plantilla inicial para copiar y pegar

Empieza pequeño. Este ejemplo crea /team-review, evitando un posible conflicto con el /review integrado.

mkdir -p .claude/skills/team-review
cat > .claude/skills/team-review/SKILL.md <<'EOF'
---
description: Review the current change with the team's checklist before a pull request or merge.
argument-hint: [target-branch-or-path]
disable-model-invocation: true
---

You are performing a read-only team review.

Target: $ARGUMENTS

If the target is empty, ask which diff, branch, or path to review before scanning broadly.
Do not edit files.
Do not run destructive commands.

Review from these perspectives:
1. Correctness bugs and edge cases
2. Security and privacy risks
3. Test coverage and missing verification
4. Consistency with existing code patterns
5. Documentation, migration notes, and user-facing copy

Output:
- Findings first, ordered by severity
- File path and line number when available
- One short suggestion for each issue
- "No blocking findings" only if you found none
EOF

Luego puedes llamarlo con /team-review main, /team-review src/auth o un objetivo acotado. disable-model-invocation: true evita que Claude active el Skill por su cuenta. Para reviews y releases conviene que el arranque sea explícito, porque son decisiones de control, no ayudas automáticas de fondo.

Caso de uso 1: convertir /review en la checklist del equipo

El valor de un comando de review está en la consistencia. Sin una checklist común, una persona mira nombres, otra seguridad y otra pruebas. El comando debe definir severidad, alcance y formato de salida para que Claude y los humanos revisen con el mismo criterio.

Si tu entorno ya tiene /review, usa team-review.md o un Skill llamado team-review. Si no existe conflicto, .claude/commands/review.md todavía puede crear un comando /review.

---
description: Team review checklist for the current branch or specified path.
argument-hint: [branch-or-path]
disable-model-invocation: true
---

Review target: $ARGUMENTS

Read the diff or files related to the target and report only review findings.
Do not rewrite code unless the user asks for fixes after the review.

Severity:
- P0: data loss, auth bypass, secret leak, production outage
- P1: correctness bug, missing validation, broken user flow
- P2: maintainability, unclear naming, duplicated logic
- P3: optional cleanup

Required checks:
1. Is the change scoped to the request?
2. Are tests or manual verification enough for the risk?
3. Are error paths and empty states handled?
4. Does the code follow existing local patterns?
5. Could the change break monetization links, analytics, or release notes?

Return a short summary after the findings.

La línea más importante es “Do not rewrite code”. Una review que modifica archivos en silencio deja de ser review y se convierte en implementación. Primero lectura, luego aceptación de hallazgos y después, si hace falta, una tarea separada para corregir.

Caso de uso 2: usar /handoff para la siguiente persona o agente

Las sesiones largas pierden valor si terminan sin una explicación clara. Un comando de handoff convierte el cierre de la tarea en una nota estructurada para tu yo de mañana, un compañero o el siguiente agente.

---
description: Create a concise handoff note for the current task.
argument-hint: [next-owner-or-audience]
disable-model-invocation: true
---

Create a handoff note for: $ARGUMENTS

Include these sections:
1. Goal: what the task was trying to achieve
2. Changed files: important files and why they changed
3. Decisions: tradeoffs or assumptions made during the work
4. Verification: commands run, screenshots checked, or checks not run
5. Risks: unresolved issues, fragile areas, or things needing human review
6. Next steps: the smallest useful next action

Keep it factual. Do not hide failed attempts. If something was not verified, say so clearly.

Esto es especialmente útil en sitios monetizados y aplicaciones de producción. Enlaces internos, CTAs, eventos de analítica, capturas y revisiones manuales se olvidan fácilmente cuando el cambio toca varios archivos. El handoff mantiene esos detalles visibles.

Caso de uso 3: usar /release para preparar, no para publicar

Los comandos de release deben ser conservadores. El objetivo no es que Claude publique por ti. El objetivo es reunir contexto, preparar notas, listar bloqueos y dejar la decisión final en manos humanas.

Esta plantilla usa argumentos con nombre. La documentación actual describe arguments como nombres asociados a argumentos posicionales; aquí el primer argumento se vuelve $version.

---
description: Prepare a release checklist and changelog draft without publishing.
argument-hint: [version]
arguments: [version]
disable-model-invocation: true
---

Prepare release $version.

Allowed work:
1. Inspect the current diff, package metadata, and changelog
2. Draft a changelog section for $version
3. Suggest verification commands
4. List release blockers and rollback notes
5. Propose a commit message

Safety rules:
- Do not run git push
- Do not publish packages
- Do not deploy to production
- Do not delete files
- Ask before changing version files

Output:
- Release summary
- Checklist
- Blockers
- Commands the user should run manually

Esto es preparación de release, no un botón de release. Si tu equipo quiere automatizar publicación, que sea en CI/CD, con aprobaciones, logs y reglas de rollback explícitas.

Argumentos: empieza con $ARGUMENTS

Para la mayoría de comandos propios, $ARGUMENTS basta. /handoff backend reviewer coloca backend reviewer en $ARGUMENTS. La documentación actual también admite $ARGUMENTS[0], $0 y argumentos con nombre como $issue o $branch si los declaras en el frontmatter.

---
description: Prepare an issue-specific work plan.
argument-hint: [issue] [branch]
arguments: [issue, branch]
disable-model-invocation: true
---

Issue: $issue
Branch: $branch
All arguments: $ARGUMENTS

Create a plan that:
1. Restates the issue in plain language
2. Lists files to inspect first
3. Identifies likely tests
4. Names one thing that should not be changed

Usa comillas si un argumento tiene varias palabras: /plan-issue "login redirect bug" fix-login. Ten cuidado con snippets antiguos que asumen que $1 es el primer argumento. La documentación actual describe $0 como abreviatura del primer argumento posicional.

Versionado y flujo de revisión

Trata los Skills y Commands del proyecto como código. Influyen en qué se revisa, qué se omite y qué acepta el equipo como “terminado”. Un cambio en .claude/skills/release-prep/SKILL.md debe verse en un pull request, no esconderse dentro de una feature sin relación.

Regla	Por qué importa
Versionar .claude/skills/ en Git	Permite saber quién cambió el workflow y cuándo
Permitir PRs solo de comandos	Los cambios de proceso no se mezclan con código de aplicación
Listar comandos en README o CLAUDE.md	Los nuevos miembros los encuentran rápido
Prohibir acciones destructivas en el prompt	Evita push, publish, deploy o borrados accidentales
Revisar el set cada mes	Quita comandos obsoletos antes de que confundan

Para diseñar una adopción de equipo, combínalo con la guía de inicio de Claude Code, las buenas prácticas de CLAUDE.md y la guía de Hooks de Claude Code.

Errores comunes y seguridad

El error más grande es pensar que un comando personalizado es seguro solo porque es corto. Sigue siendo un prompt potente. Si usas inyección de contexto dinámica con backticks !, Claude Code ejecuta el comando de shell e inserta la salida antes de que Claude lea el Skill. Es útil, pero necesita una regla estricta de solo lectura.

---
description: Collect read-only git context for release notes.
disable-model-invocation: true
---

Current status:
!`git status --short`

Recent commits:
!`git log --oneline -20`

Summarize the release notes from the information above.
Do not run write operations.

Limita estos comandos a inspección segura como git status y git log. No incluyas rm, git clean, git push, npm publish, curl ... | sh ni scripts que afecten producción. También cuida allowed-tools: dar acceso amplio a Bash puede reducir confirmaciones justo donde el equipo esperaba una pausa. Empieza con herramientas de lectura y añade permisos solo cuando el workflow lo necesite de verdad.

Los fallos concretos son previsibles. Un /review propio choca con uno integrado. Un comando vive solo en el home de una persona. El cuerpo del Skill crece tanto que consume contexto cada vez. Un argumento vacío hace que Claude inspeccione todo el repositorio. Un release incluye publicación. Todos nacen de intentar ahorrar demasiado. Empieza en modo solo lectura, acota el objetivo y deja confirmación humana en el diseño.

CTA: convierte las plantillas en operación real

Estas plantillas valen más cuando se adaptan a tu repositorio. Si trabajas solo, empieza con la cheatsheet gratuita de Claude Code y guarda cerca los patrones seguros. Si quieres plantillas reutilizables de review, release y handoff, revisa los productos de ClaudeCodeLab. Si tu equipo necesita permisos, CLAUDE.md, revisión de Skills, límites con CI y onboarding diseñados juntos, usa la página de formación y consultoría de Claude Code.

Al probarlo en el flujo de Masa, el resultado fue claro: tres comandos bastaron. /team-review, /handoff y /release-prep cubrieron la mayor parte del trabajo repetido sin convertir Claude Code en una herramienta peligrosa de despliegue. La mejora más grande vino de definir /release como un comando que reúne evidencia para una decisión humana, no como un comando que publica. Los comandos slash personalizados funcionan mejor cuando ayudan al equipo a detenerse, comprobar y entregar contexto con el mismo estándar.