Cómo domar agentes de IA con el kit de herramientas de habilidades de Matt Pocock
Cuando los desarrolladores comienzan a trabajar de cerca con Claude Code o Codex, rápidamente se encuentran con el mismo problema. El agente acepta alegremente la tarea, se va a escribir código durante cinco minutos y regresa con quinientas líneas de espagueti roto. ¿Te suena familiar? Matt Pocock, el autor de Total TypeScript, decidió abordar este problema con disciplina de ingeniería y creó un repositorio de instrucciones prácticas (habilidades) para agentes de IA. Y el proyecto vinvcn/mattpocock-skills-zh-CN adaptó todo este kit de herramientas para trabajar con modelos de lenguaje chinos y contextos mixtos.
Esto no se trata de discusiones abstractas sobre el futuro del desarrollo. Es un conjunto de comandos y escenarios concretos que hacen que el modelo de lenguaje actúe como un desarrollador ordenado de nivel medio o senior, en lugar de un generador aleatorio de funciones.
Cuatro escenarios donde los agentes típicamente fallan
Matt identificó las trampas típicas en las que los desarrolladores tropiezan al entregar tareas a la IA, y escribió un protocolo de trabajo separado para cada caso.
El agente hace algo completamente diferente a lo que se le pidió
El dolor de cabeza de desarrollo más común se llama desalineación de expectativas. Una persona piensa en una arquitectura, el modelo llena los detalles a su gusto. Para cerrar esta brecha, el autor ideó el comando /grill-me (y su variante de ingeniería /grill-with-docs).
Antes de tocar cualquier código, el agente realiza una interrogación formal. Hace una serie de preguntas específicas sobre casos límite, estructura de datos y requisitos de interfaz. El modelo no escribirá una sola línea hasta que el árbol de decisiones converja. Esto ahorra horas de reescritura de código.
El modelo desperdicia contexto en conversaciones innecesarias
Cuando un agente entra en un proyecto desconocido, comienza a inventar su propia terminología y gasta decenas de tokens explicando cosas obvias. La solución está en crear un documento con vocabulario de dominio unificado (en el proyecto se llama CONTEXT.md).
El comando /grill-with-docs no solo te encuesta, sino que inmediatamente registra la terminología del proyecto y las decisiones arquitectónicas (ADRs). Una vez que tú y el agente comparten un lenguaje común, el diálogo se reduce drásticamente, y las variables en el código comienzan a nombrarse igual en todos los módulos.
El código generado no se ejecuta
Cuando un modelo escribe código sin retroalimentación, trabaja a ciegas. Necesita pruebas. La habilidad /tdd obliga al agente a seguir estrictamente el ciclo red-green-refactor. Primero el modelo escribe una prueba unitaria que falla, luego implementa exactamente lo necesario para pasar la prueba, y solo entonces limpia.
Para errores complejos existe un escenario /diagnosing-bugs separado. Guía al modelo a través de un protocolo estricto: reproducir el error con una prueba, reducir el área de búsqueda, formular una hipótesis, agregar logging, corregir el código y ejecutar una prueba de regresión.
La arquitectura se convierte en un desastre
La velocidad de generación de código alimenta el crecimiento de la entropía. Para evitar que el proyecto se convierta en una bola de espagueti enredada, se usa el comando /improve-codebase-architecture.
Escanea el proyecto, busca candidatos para módulos profundos (con interfaces públicas simples y lógica compleja oculta) y genera un informe. Esencialmente, es una auditoría regular de calidad de código directamente en la terminal.
Por qué localizar al chino
El repositorio original está escrito en inglés, pero la localización de vinvcn tiene un propósito técnico interesante. No se trata solo de comodidad para los desarrolladores chinos.
Cuando se trabaja con LLMs asiáticos como Qwen o DeepSeek, los prompts e instrucciones del sistema en chino reducen la pérdida de contexto. El modelo se confunde menos con los matices de formulación. Mientras tanto, todos los identificadores, nombres de comandos, rutas de archivos y claves de configuración se dejan en inglés. Nada se rompe al ejecutar scripts.
Cómo funciona la arquitectura de las habilidades
Todas las habilidades del repositorio se dividen en dos categorías:
- Comandos invocados por el usuario. Solo los humanos los activan manualmente a través de slash. Por ejemplo,
/ask-mattayuda a seleccionar la habilidad correcta para la tarea actual,/to-speccompila la discusión en un ticket, y/wayfinderplanifica una característica importante varias sesiones adelante. - Habilidades invocadas por el modelo. Tanto el usuario como el agente pueden activarlas por iniciativa propia cuando ven una subtarea adecuada. Estas incluyen el ciclo TDD, resolución de conflictos git sin abortos duros, revisión de código y redacción.
Las habilidades están escritas como archivos Markdown simples con instrucciones. Son fáciles de leer y se pueden editar para adaptarlas a las reglas de tu equipo.
Configuración en un par de minutos
Puedes agregar habilidades a tu proyecto usando el instalador skills.sh:
npx skills@latest add vinvcn/mattpocock-skills-zh-CN
La utilidad te preguntará qué habilidades quieres copiar y en qué directorios de agentes registrarlas. Asegúrate de seleccionar /setup-matt-pocock-skills.
Después de la instalación, ejecuta la configuración inicial directamente en el diálogo del agente:
/setup-matt-pocock-skills
El agente aclarará dónde rastreas las tareas (GitHub Issues, Linear o archivos locales), qué etiquetas usas para la clasificación y en qué carpeta almacenar la documentación arquitectónica.
Si estás trabajando en Claude Code y no quieres almacenar copias de archivos en cada repositorio, puedes conectar las habilidades como un plugin:
claude plugin marketplace add vinvcn/mattpocock-skills-zh-CN
claude plugin install mattpocock-skills@mattpocock
En este modo, las habilidades se actualizarán centralmente cuando se lancen nuevas versiones.
Para quién es esto
Dos categorías de ingenieros deberían revisar este repositorio.
Primero, quienes usan activamente Claude Code, Codex u OpenCodeInterpreter y están hartos de luchar contra las alucinaciones del modelo. El enfoque de Matt Pocock devuelve la previsibilidad al desarrollo a través de restricciones estrictas y ciclos de retroalimentación cortos.
Segundo, es un excelente ejemplo de cómo escribir instrucciones del sistema para asistentes de IA. Incluso si no necesitas la traducción al chino, la estructura de archivos en este repositorio proporciona una lección clara sobre el diseño de habilidades para agentes. Prueba incorporar un par de comandos como /grill-me en tu flujo de trabajo diario, y notarás la diferencia para la tarde.
Proyectos relacionados