code-reviewer

Visión general de la skill code-reviewer

Qué hace la skill code-reviewer

La skill code-reviewer ofrece un flujo estructurado de revisión de PRs y diffs para tareas de Code Review. En lugar de depender de un prompt de una sola línea como “review this code”, empuja al agente a recopilar los archivos modificados, inspeccionar el diff, entender los patrones locales del proyecto y, después, revisar los cambios por categorías concretas como corrección, seguridad, rendimiento, pruebas y mantenibilidad.

Quién debería instalar code-reviewer

Esta code-reviewer skill encaja especialmente bien para desarrolladores, tech leads y revisores asistidos por IA que buscan más consistencia de la que suele dar un prompt genérico. Resulta especialmente útil si revisas pull requests con frecuencia, quieres hallazgos clasificados por severidad o necesitas una lista de control repetible que cubra tanto problemas lógicos como riesgos de seguridad más serios.

La necesidad real que resuelve

La mayoría de los usuarios no quieren simplemente “feedback”. Quieren una revisión que responda a preguntas como: qué cambió, qué es arriesgado, qué debería bloquear el merge, qué puede esperar y qué evidencia respalda cada punto. El flujo de code-reviewer está diseñado en torno a esa necesidad: separa la recopilación de contexto del análisis, lo que reduce los comentarios superficiales basados solo en fragmentos de código.

Qué hace diferente a esta skill

Su principal diferencial es la estructura de revisión. El repositorio no se queda en una instrucción general de inspeccionar código. Incluye:

• un proceso de revisión por fases
• un formato de salida orientado por severidad
• referencias específicas para checklist, patrones de código y revisión de seguridad
• un script de apoyo en scripts/review_checklist.py para generar una checklist de revisión a partir de cambios en Git

Eso hace que code-reviewer for Code Review sea más accionable que un prompt simple y más fácil de adaptar a las normas de revisión de un equipo.

Cuándo code-reviewer encaja especialmente bien

Usa code-reviewer cuando tengas:

• un diff de una rama frente a main
• un PR con varios archivos o cambios transversales
• la necesidad de distinguir entre bloqueadores de merge y mejoras opcionales
• cambios sensibles en seguridad, como auth, manejo de entradas o acceso a datos
• una base de código donde los patrones existentes importan tanto como las buenas prácticas abstractas

Cuándo encaja peor

Esta skill resulta menos útil cuando:

• no hay diff ni conjunto de archivos que inspeccionar
• solo buscas observaciones de estilo
• la tarea es de diseño de arquitectura más que de code review
• no hay contexto del repo, así que no se pueden comparar patrones
• en realidad la petición es de debugging, reescritura o planificación de funcionalidades

Cómo usar la skill code-reviewer

Contexto de instalación para la skill code-reviewer

El SKILL.md de origen no publica un comando de instalación directo, pero la skill vive en zhaono1/agent-playbook dentro de skills/code-reviewer. Si tu runtime de skills permite instalar skills de GitHub desde una ruta del repositorio o una colección, instala desde ese repositorio y selecciona la skill code-reviewer.

Un patrón habitual es:

npx skills add https://github.com/zhaono1/agent-playbook --skill code-reviewer

Si tu entorno usa otro instalador, el dato clave es el slug de la skill: code-reviewer.

Lee primero estos archivos antes de apoyarte en ella

Para evaluarla más rápido, lee:

1. skills/code-reviewer/SKILL.md
2. skills/code-reviewer/README.md
3. skills/code-reviewer/references/checklist.md
4. skills/code-reviewer/references/security.md
5. skills/code-reviewer/references/patterns.md
6. skills/code-reviewer/scripts/review_checklist.py

Este orden importa. SKILL.md te dice cómo se activa el flujo, las referencias muestran qué estándares aplica y el script deja ver cómo espera recopilar evidencia del repo.

Qué entradas necesita code-reviewer para funcionar bien

El code-reviewer usage da mejores resultados cuando proporcionas:

• la rama base, normalmente main
• el objetivo del PR o el ticket vinculado
• los archivos cambiados o el diff completo
• las áreas de riesgo que más te preocupan
• el contexto de framework o lenguaje
• si quieres una revisión rápida o una revisión para bloquear el merge

Sin eso, la revisión puede ejecutarse igualmente, pero tenderá a ser más genérica.

Cómo recopila code-reviewer el contexto de revisión

El repositorio deja explícito el flujo esperado de revisión:

• obtener los archivos modificados con git diff main...HEAD --name-only
• inspeccionar el historial de commits con git log main...HEAD --oneline
• revisar el diff real con git diff main...HEAD
• leer documentación cercana y archivos similares para entender las convenciones locales

Esto es importante porque muchas revisiones débiles hechas con IA se saltan la recopilación de contexto y pasan directamente a buenas prácticas abstractas. Esta skill funciona mejor cuando primero se ancla en lo que realmente cambió.

Una plantilla práctica de prompt para code-reviewer

Usa un prompt más cercano a esto:

Review this branch with the code-reviewer skill.

Base branch: main
Goal: add password reset flow for users
Priority areas: security, correctness, test gaps
Constraints: keep current API shape, do not request large refactors
Please classify findings by severity: critical, high, medium, low.
For each finding, cite the file, explain the risk, and suggest the smallest safe fix.

Esto funciona mejor que “review my code” porque da a la skill la rama objetivo, la intención de negocio, las prioridades de revisión y el formato esperado para el feedback.

Entradas más sólidas frente a entradas más débiles

Entrada débil:

Review this PR

Entrada más sólida:

Use code-reviewer on the diff against main.
Focus on auth flows, input validation, and regression risk.
Check whether tests cover unhappy paths and whether any existing project patterns were broken.
Flag only issues that are actionable before merge unless clearly marked as low severity.

La versión más sólida mejora de forma tangible la calidad de salida porque acota el alcance de la revisión, identifica áreas de riesgo y le dice al agente qué nivel de exigencia aplicar.

Flujo recomendado para una revisión real de PRs

Una code-reviewer guide práctica se parece a esto:

1. Recopila los archivos modificados y el diff.
2. Lee la descripción del PR o el ticket.
3. Toma una muestra de archivos cercanos para aprender las convenciones.
4. Ejecuta la revisión por categorías: corrección, seguridad, rendimiento, calidad de código, pruebas, documentación y mantenibilidad.
5. Agrupa los hallazgos por severidad.
6. Pide una segunda pasada sobre los archivos de mayor riesgo si la primera revisión encontró problemas serios.

Este patrón de dos pasadas funciona bien porque la primera detecta riesgos amplios y la segunda mejora la precisión.

Usa las referencias para que las revisiones sean menos genéricas

Los archivos de apoyo son la principal razón para elegir esta skill frente a un prompt normal:

• references/checklist.md mantiene la revisión sistemática
• references/security.md añade comprobaciones orientadas a OWASP
• references/patterns.md aporta ejemplos concretos de implementaciones buenas y malas

Si una revisión te parece vaga, indica al agente que aplique explícitamente una o varias de estas referencias al analizar el diff.

Usa el script de apoyo si quieres una base de revisión

El repositorio incluye:

python scripts/review_checklist.py

Esto resulta útil si quieres una checklist generada automáticamente a partir del estado actual de Git antes de pedir al agente hallazgos narrativos. Es un puente práctico entre inspeccionar el diff en bruto y producir una revisión escrita completa.

Formato de salida que mejor funciona en la práctica

Pide a la skill que devuelva:

• un resumen breve de lo que cambió
• primero los bloqueadores de merge
• los hallazgos agrupados por severidad
• referencias a nivel de archivo
• razonamiento, no solo veredictos
• una evaluación final de “¿safe to merge?” con matices

Ese formato encaja con el modelo de severidad del repositorio y hace que la revisión sea más fácil de usar en flujos reales de equipo.

FAQ de la skill code-reviewer

¿Es code-reviewer mejor que un prompt normal de revisión?

Por lo general, sí, si tienes contexto real del repo. El valor de code-reviewer no está solo en una supuesta profundidad mágica del análisis. Está en la combinación de señales de activación, flujo por fases, cobertura mediante checklist y material de referencia, que empujan la revisión hacia mayor completitud y consistencia.

¿code-reviewer es apta para principiantes?

Sí, con un matiz: los principiantes siguen necesitando aportar contexto. La skill da una estructura sólida, pero no puede deducir requisitos, comportamiento esperado ni convenciones del equipo a partir de la nada. Los usuarios nuevos obtendrán mejores resultados si incluyen desde el inicio el objetivo del PR y la rama base.

¿code-reviewer solo funciona para pull requests?

No. El code-reviewer usage también encaja con diffs de ramas locales, un conjunto de archivos modificados o una petición de revisión a nivel de carpeta como “review the code in src/auth/.” Aun así, rinde mejor cuando hay un diff claro frente a una rama base conocida.

¿Qué tipos de problemas busca la skill code-reviewer?

La evidencia del repositorio muestra cobertura para:

• corrección y casos límite
• problemas de seguridad, incluidas preocupaciones de estilo OWASP
• problemas de rendimiento, como consultas o llamadas innecesarias
• calidad de código y mantenibilidad
• huecos en pruebas
• huecos en documentación

Esa amplitud la hace adecuada para revisión general de PRs, no solo para revisiones de seguridad o de estilo.

¿Cuándo no debería usar code-reviewer?

Evita code-reviewer cuando la tarea sea principalmente:

• generar código nuevo
• depurar un fallo en runtime
• planificar arquitectura a gran escala
• hacer solo limpieza de formato o lint
• revisar código sin acceso al contexto de los cambios

En esos casos, una skill más especializada o un prompt directo centrado en la tarea será una mejor opción.

¿Impone un único estilo de código?

No. El repositorio anima a comprobar primero los patrones existentes en archivos similares antes de juzgar el cambio. Eso es una buena señal de adopción, porque reduce recomendaciones genéricas que chocan con las convenciones locales.

Cómo mejorar la skill code-reviewer

Dale a code-reviewer la intención detrás del cambio

La mejora más importante de calidad es explicar qué se supone que debe hacer el código. La calidad de la revisión cae rápido cuando el agente solo ve la implementación. Añade el resumen del ticket, los criterios de aceptación o una nota breve de intención para que la skill pueda juzgar la corrección y no solo el estilo o la sintaxis.

Acota las áreas de revisión de mayor riesgo

Si lo que más te preocupa es auth, billing, migraciones o concurrencia, dilo. La skill ya cubre varias categorías, pero fijar prioridades mejora la profundidad donde de verdad importa. Esto es especialmente importante en PRs grandes, donde una revisión demasiado amplia puede quedarse en la superficie.

Da suficiente contexto del repo para comparar patrones

Este repositorio indica explícitamente al revisor que busque las convenciones existentes. Ayúdale nombrando archivos o módulos comparables:

Compare the new handler to the existing patterns in src/api/users/ and src/api/sessions/.
Prefer consistency with those files unless there is a clear bug.

Esto reduce falsos positivos y hace que las sugerencias sean más fáciles de adoptar.

Pide solo hallazgos basados en evidencia

Un fallo habitual en revisiones con IA es la crítica especulativa. Puedes mejorar la salida de code-reviewer fijando una regla como:

Only report an issue if you can point to a specific file change, missing case, or concrete risk. Avoid hypothetical style advice unless it affects maintainability or correctness.

Así mantienes la revisión con alta señal y poco ruido.

Divide las revisiones grandes en varias pasadas

Para PRs grandes, no pidas todo a la vez. Usa pasadas por etapas:

1. corrección y seguridad
2. rendimiento y mantenibilidad
3. pruebas y documentación

Esto refleja la estructura por categorías de la skill y normalmente produce mejores hallazgos que una única petición sobrecargada.

Pide recomendaciones de corrección más pequeñas

Si la primera salida es demasiado abstracta, pide a la skill que reformule los hallazgos como correcciones mínimas y seguras:

Revise the review. For each high or critical issue, suggest the smallest code change or test addition that would reduce the risk before merge.

Eso hace que la revisión sea más accionable para equipos con poco tiempo.

Vigila los fallos más comunes

Las formas más habituales en que la salida de la code-reviewer skill se debilita son:

• no especificar la rama base
• no proporcionar el diff
• no indicar el comportamiento esperado
• PRs enormes sin prioridades
• no aportar referencias de patrones del proyecto
• pedir “todo” y recibir de vuelta consejos genéricos

La mayoría de estos problemas son de entrada, no de la skill.

Usa explícitamente la checklist y las referencias de seguridad

Si tu primera revisión sale demasiado amplia, pide una segunda pasada usando referencias concretas del repo:

• references/checklist.md para completitud
• references/security.md para cambios sensibles
• references/patterns.md para consistencia y detección de anti-patrones

Es una de las formas más sencillas de mejorar la code-reviewer guide en el uso diario.

Itera después de la primera revisión

Un buen segundo prompt es:

Now re-review only the files with high-severity findings.
Assume the author wants merge-blocking issues only.
Double-check whether each finding is a real defect, a security exposure, or a missing test that hides regression risk.

Ese seguimiento suele eliminar comentarios de poco valor y afinar la recomendación final.

Adapta code-reviewer al flujo de trabajo de tu equipo

Si vas a adoptar code-reviewer de forma habitual, alinéalas con la cultura de merge de tu equipo:

• define qué cuenta como blocker frente a sugerencia
• nombra la convención de rama base
• incluye tus expectativas de pruebas
• añade comprobaciones de seguridad específicas del equipo
• señala archivos representativos para el estilo local

Así conviertes code-reviewer install en una mejora real del flujo de trabajo y no solo en otro atajo basado en prompts.