La skill grill-me: una guía práctica para mejorar el desarrollo agéntico

La skill grill-me es casi ridículamente pequeña.

Por eso es útil.

En lugar de pedirle a un agente que empiece a programar de inmediato, le pides que te entreviste sobre el plan, el diseño o la decisión de producto hasta que las partes ambiguas queden claras. Recorre el árbol de decisiones, hace una pregunta a la vez, recomienda respuestas cuando resulta útil y explora el código del proyecto cuando puede responder una pregunta directamente.

Para los ingenieros, esto convierte un «por favor, construye esto» en un mejor plan técnico. Para los PMs, transforma una intención vaga en tradeoffs claros, criterios de aceptación y registros de decisiones. Para ambos, reduce el clásico problema de los agentes: que implementen con total seguridad la versión equivocada de la idea correcta.

Al June 4, 2026, este patrón aparece en catálogos públicos de skills, incluidos el repositorio skills de Matt Pocock y Agent Skills Lab. En mi opinión, su popularidad se debe a una inversión sencilla del flujo de trabajo:

no dejes que el agente escriba código hasta que haya obligado al plan a ser comprobable.

TL;DR

• grill-me es una skill reutilizable que te entrevista sobre un plan o diseño antes de implementarlo.
• Su valor principal es la alineación: expone supuestos ocultos, decisiones de producto pendientes, restricciones técnicas y criterios de aceptación faltantes.
• Una skill suele ser un directorio con un archivo SKILL.md que contiene frontmatter YAML e instrucciones en Markdown.
• En Codex, una buena ubicación para las skills de proyecto es .agents/skills/<skill-name>/SKILL.md; las skills personales pueden estar en $HOME/.agents/skills.
• En Claude Code, las skills de proyecto suelen estar en .claude/skills/<skill-name>/SKILL.md; las personales suelen estar en ~/.claude/skills.
• El campo description importa más de lo que muchos creen. Es la condición que el agente usa para decidir si debe cargar la skill.
• Usa grill-me antes de crear PRDs, hacer cambios de arquitectura, refactorizaciones que abarcan varios archivos, desgloses de issues, planes de migración y funcionalidades construidas por agentes.
• En un flujo de Spec Kit, grill-me funciona mejor antes de /speckit.specify, después de /speckit.clarify y antes de /speckit.plan o /speckit.tasks.
• La mejor versión para tu equipo debe incluir su propio vocabulario de producto, las restricciones del código, los estándares de revisión y el estilo de toma de decisiones.

Qué aprenderás aquí

Al terminar, deberías poder:

• explicar qué hace la skill grill-me
• crear una skill grill-me específica para un proyecto
• adaptarla a Codex, Claude Code o cualquier agente compatible con el formato Agent Skills
• usarla en un flujo habitual de desarrollo agéntico
• combinarla con GitHub Spec Kit sin duplicar todo el proceso de Spec Kit
• decidir cuándo una sesión de preguntas debe producir un PRD, issues, pruebas o trabajo de implementación
• identificar las limitaciones actuales antes de depender demasiado de la skill

Por qué existe esta skill

La mayoría de los problemas del desarrollo agéntico no empiezan siendo problemas del modelo. Son problemas de alineación.

El agente parte de un contexto parcial. La persona tiene supuestos que no ha expresado. El proyecto tiene restricciones ocultas en el código, issues antiguos, ADRs, convenciones y detalles de despliegue. Entonces alguien escribe:

Build the new billing settings page.

Parece una instrucción concreta, pero oculta preguntas como estas:

• ¿Qué usuarios pueden verlo?
• ¿Qué proveedor de facturación es la fuente de verdad?
• ¿Es de solo lectura, editable o ambas cosas?
• ¿Qué pasa cuando la API del proveedor no está disponible?
• ¿Estamos reemplazando un flujo anterior o agregando uno nuevo?
• ¿Qué se debe probar antes de lanzar el cambio?

Las personas suelen resolver estas preguntas en conversaciones informales, reuniones de planificación, hilos de Slack y revisiones de código. Los agentes necesitan ese mismo ciclo de aclaración, pero antes y de manera más explícita.

grill-me es una forma compacta de hacer que ese ciclo ocurra.

¿Qué es una skill para agentes?

Una skill para agentes es un paquete reutilizable que define un flujo de trabajo. Su unidad básica es una carpeta con un archivo SKILL.md:

grill-me/
|-- SKILL.md
|-- references/      optional deeper docs
|-- scripts/         optional executable helpers
`-- assets/          optional templates or examples

El frontmatter le indica al agente qué es la skill y cuándo usarla. El cuerpo en Markdown le indica cómo comportarse una vez que la skill se activa.

---
name: grill-me
description: Interview the user about a plan, product decision, architecture, or implementation strategy before execution. Use when the user says "grill me", asks to stress-test a plan, asks what they are missing, or presents a proposal for critical questioning.
---

Your job is to interview the user before implementation.
Ask one question at a time unless several questions are independent.
Prefer questions that expose risk, ambiguity, dependencies, and missing acceptance criteria.
If the answer is discoverable from the repository, inspect the repository instead of asking.
After the interview, summarize decisions, unresolved gaps, and the recommended next action.

Eso basta para crear una primera versión funcional.

Cómo funciona grill-me

Las versiones públicas originales de grill-me son cortas. El patrón no es un framework gigantesco. Es un contrato de comportamiento:

• entrevistar a la persona sobre el plan
• recorrer el árbol de decisiones
• resolver las dependencias entre decisiones
• hacer una pregunta a la vez
• recomendar una respuesta cuando sea útil
• inspeccionar el código en lugar de hacer preguntas que el repositorio puede responder

El trabajo del agente no consiste en «revisar» la idea desde lejos. Debe cuestionar los puntos débiles del plan.

Este es el ciclo básico:

User brings a plan
        |
        v
Agent identifies unclear decisions
        |
        v
Agent asks the highest-leverage question
        |
        v
User answers or agent researches the repo
        |
        v
Agent updates the decision tree
        |
        +---- more unresolved branches? ---- yes ----+
        |                                            |
        no                                           |
        |                                            |
        v                                            |
Summarize decisions, gaps, and next action <---------+

Por eso la skill es útil para los flujos agénticos. Convierte un prompt vago en una secuencia de decisiones que el agente puede implementar, probar o entregar a otra persona más adelante.

Crea tu propia skill grill-me

Para crear una skill de proyecto compatible con Codex, crea:

.agents/skills/grill-me/SKILL.md

Para crear una skill de proyecto para Claude Code, crea:

.claude/skills/grill-me/SKILL.md

Si tu equipo usa ambas herramientas, puedes mantener una skill canónica en .agents/skills y crear una copia o un enlace simbólico donde tus herramientas la esperen. Mantén el contenido independiente de la herramienta, a menos que necesites una funcionalidad específica de la plataforma.

Aquí tienes una versión más sólida, lista para un equipo:

---
name: grill-me
description: Stress-test a plan, design, product decision, architecture, migration, or implementation strategy before execution. Use when the user says "grill me", "poke holes in this", "what am I missing", "does this plan make sense", or asks for critical questioning before coding.
---

# Grill Me

You are an interviewer, not an implementation agent.

Goal: turn an unclear plan into a clear, testable, implementation-ready decision set.

## Process

1. Restate the plan in one short paragraph.
2. Identify the highest-risk unknowns across product, users, data, architecture, operations, security, and rollout.
3. Ask one question at a time unless the questions are independent and can be answered together.
4. If the repository can answer a question, inspect the repository instead of asking the user.
5. For each important decision, offer a recommended answer and explain the tradeoff briefly.
6. Track decisions as accepted, rejected, or unresolved.
7. Do not start implementation until the user explicitly asks you to proceed.

## Question Priorities

Prefer questions that clarify:

- user and business goal
- success criteria
- non-goals
- affected systems and owners
- data model changes
- API contracts
- permissions and security boundaries
- failure modes
- testing strategy
- rollout, migration, and rollback

## Output At The End

Return:

- decisions made
- unresolved gaps
- recommended next step
- suggested artifacts: PRD, issues, tests, ADR, implementation plan, or prototype

Esta versión sigue siendo pequeña, pero le da al agente suficiente estructura para comportarse de manera predecible.

Úsala en tus propios proyectos

El mayor valor se obtiene antes de la implementación, no después.

Buenos prompts:

/grill-me I want to migrate our billing settings from Stripe-only to multi-provider.

$grill-me We are thinking about replacing our custom permissions table with OpenFGA. Poke holes in the plan.

Grill me on this checkout redesign before we create tickets.

Malos prompts:

Use grill-me and then immediately implement everything.

Eso combina la fase de aclaración y la de ejecución en una sola sesión. A veces está bien para cambios pequeños. Para trabajos importantes, mantén las fases separadas.

Un flujo habitual de desarrollo agéntico

Este es un flujo práctico que funciona para ingenieros y PMs:

Idea or request
      |
      v
Grill-me interview
      |
      v
Decision summary
      |
      +--> still unclear? return to interview
      |
      v
Artifact selection
      |
      +--> PRD
      +--> ADR
      +--> issue breakdown
      +--> test plan
      +--> prototype
      |
      v
Implementation agent
      |
      v
Tests, review, and rollout notes

Un ciclo realista de equipo podría verse así:

1. El PM presenta una idea para una funcionalidad.
2. El agente ejecuta grill-me y hace preguntas sobre producto, datos y casos límite.
3. El PM responde las preguntas de producto.
4. El ingeniero deja que el agente inspeccione el repositorio en busca de restricciones de implementación.
5. El agente produce un resumen de decisiones.
6. El equipo convierte el resumen en un PRD o un desglose de issues.
7. La implementación ocurre en una sesión separada con el agente, con pruebas y revisión.

La separación importa. grill-me no es quien construye. Es el punto de control de alineación antes de que alguien construya.

Dónde encaja grill-me con GitHub Spec Kit

GitHub Spec Kit y grill-me se superponen de manera positiva.

Spec Kit te proporciona el pipeline estructurado de artefactos:

constitution -> specify -> clarify -> checklist -> plan -> tasks -> analyze -> implement

La documentación actual de Spec Kit describe el flujo principal como Spec -> Plan -> Tasks -> Implement, con comandos de apoyo como /speckit.constitution, /speckit.clarify, /speckit.checklist y /speckit.analyze. Eso significa que Spec Kit ya reconoce una verdad importante del desarrollo asistido por IA:

no le pidas al agente de programación que implemente hasta que la especificación y el plan sean lo bastante claros para guiar el trabajo.

grill-me mejora este flujo al adelantar parte de la aclaración, antes de que comience el proceso formal de creación de artefactos.

Raw idea
  |
  v
grill-me
  |
  v
/speckit.specify
  |
  v
/speckit.clarify + /speckit.checklist
  |
  v
grill-me again, if the spec still hides decisions
  |
  v
/speckit.plan
  |
  v
/speckit.tasks + /speckit.analyze
  |
  v
/speckit.implement

La distinción principal es sencilla:

Así que grill-me no es «Spec Kit, pero más pequeño». Es la conversación que conviene tener a menudo antes de que Spec Kit reciba el prompt que se convierte en el artefacto de origen.

La superposición: grill-me frente a /speckit.clarify

La superposición más clara es con /speckit.clarify.

Ambos están diseñados para evitar que el agente haga suposiciones. Ambos son útiles cuando la solicitud está poco especificada. Ambos deberían producir un mejor contexto para la implementación.

Pero operan en momentos distintos:

grill-me
  -> before the first spec exists
  -> helps decide what should enter the spec
  -> can challenge whether the feature is worth doing this way

/speckit.clarify
  -> after spec.md exists
  -> resolves ambiguity in a concrete artifact
  -> updates or informs the formal Spec Kit flow

Mi regla práctica:

Usa grill-me cuando la idea todavía está en una conversación. Usa /speckit.clarify cuando la idea ya se convirtió en spec.md.

Eso facilita la transferencia entre PMs e ingenieros. El PM puede usar grill-me para precisar objetivos, lo que queda fuera de los objetivos, historias de usuario y criterios de aceptación. Luego, el ingeniero puede usar /speckit.specify y /speckit.clarify para convertir esas decisiones en artefactos versionados.

La mejora: mejores entradas para /speckit.specify

/speckit.specify de Spec Kit funciona mejor cuando el prompt explicita el qué y el por qué, no el stack tecnológico. Ahí es precisamente donde ayuda grill-me.

En lugar de esto:

/speckit.specify Add team invites.

Ejecuta:

/grill-me I want to add team invites. Help me find the missing decisions before I create the spec.

Luego, proporciona las decisiones resultantes a Spec Kit:

/speckit.specify Add email-based team invites for workspace admins.
Admins can invite users by email, invites expire after 7 days, pending
invites can be revoked, and accepted invites add the user to the workspace
with the selected role. V1 excludes bulk invites, SCIM, and invite links.
Success means an admin can invite, revoke, and track pending invites without
changing existing workspace membership behavior.

Ese segundo prompt le da a Spec Kit una base mucho mejor. Incluye el rol del usuario, el alcance, el ciclo de vida, lo que queda fuera de los objetivos y los criterios de éxito. El spec.md generado debería necesitar menos ajustes porque las decisiones humanas ya son visibles.

La mejora: mejores entradas para /speckit.plan

grill-me también es útil antes de /speckit.plan, pero las preguntas deben cambiar.

Antes de /speckit.specify, haz preguntas de producto:

• ¿Para quién es esto?
• ¿Qué comportamiento cambia?
• ¿Qué queda fuera del alcance?
• ¿Qué se considera un éxito?

Antes de /speckit.plan, haz preguntas de ingeniería:

• ¿Qué módulos existentes se ven afectados?
• ¿Qué cambios en el modelo de datos son inevitables?
• ¿Qué contratos o clientes podrían dejar de funcionar?
• ¿Qué límites de seguridad aplican?
• ¿Qué opción de rollback existe?
• ¿Qué pruebas deberían fallar primero?

Esto encaja bien con Spec Kit porque /speckit.plan es donde la funcionalidad pasa de la intención de producto a la implementación técnica. Una breve sesión de grill-me antes de planificar puede detectar una solución demasiado compleja, restricciones del repositorio que se pasaron por alto o decisiones arquitectónicas que deberían quedar escritas en el plan en lugar de descubrirse durante la implementación.

Un flujo combinado práctico

Para una funcionalidad importante, yo usaría esta secuencia:

1. /grill-me <raw idea>
   Output: decisions, gaps, non-goals, acceptance criteria

2. /speckit.specify <decision summary>
   Output: specs/<feature>/spec.md

3. /speckit.clarify
   Output: clarified requirements in the spec flow

4. /speckit.checklist
   Output: requirements quality review

5. /grill-me <spec + planned technical direction>
   Output: risk questions before architecture hardens

6. /speckit.plan <tech stack and architecture decisions>
   Output: plan.md, research.md, data-model.md, contracts, quickstart

7. /speckit.tasks
   Output: tasks.md

8. /speckit.analyze
   Output: consistency and coverage findings

9. /speckit.implement
   Output: code, tests, and implementation progress

Para cambios pequeños, esto es demasiado proceso. Para trabajos que abarcan varios módulos, migraciones, permisos, facturación, flujos de onboarding o cualquier cosa costosa de revertir, es una carga muy razonable.

Cómo incorporar esto en una skill de proyecto

Si tu equipo ya usa Spec Kit, agrega una breve regla de Spec Kit a tu skill grill-me:

## Spec Kit Integration

If this repo uses GitHub Spec Kit:

- Before `/speckit.specify`, help the user produce a concise decision summary focused on what, why, users, scope, non-goals, and success criteria.
- After `spec.md` exists, do not replace `/speckit.clarify`; recommend it for artifact-level ambiguity.
- Before `/speckit.plan`, ask engineering risk questions about modules, data, APIs, permissions, tests, rollout, and rollback.
- Before `/speckit.implement`, prefer `/speckit.analyze` over ad-hoc confidence.
- Never let implementation start while major decisions remain unresolved.

Esta pequeña adición evita confusiones entre herramientas. grill-me se encarga de la entrevista con la persona. Spec Kit se encarga de los artefactos duraderos.

Qué preguntar durante la entrevista

Una buena sesión de preguntas no debería sentirse aleatoria. Debería avanzar desde la intención hasta las restricciones y la ejecución.

Intent
  |
  +-- Who is this for?
  +-- What problem does it solve?
  +-- What outcome proves it worked?

Scope
  |
  +-- What is included?
  +-- What is explicitly not included?
  +-- What existing behavior must not change?

System design
  |
  +-- What data changes?
  +-- What API contracts change?
  +-- What permissions apply?
  +-- What failures should be graceful?

Delivery
  |
  +-- How do we test it?
  +-- How do we roll it out?
  +-- How do we revert it?

Las mejores preguntas del agente suelen sonar simples:

• «¿Qué debería pasar cuando esta dependencia no esté disponible?»
• «¿Qué comportamiento existente debe permanecer sin cambios?»
• «¿Quién es responsable de la fuente de verdad para este campo?»
• «¿Cuál es la versión más pequeña que aún permite validar la idea?»
• «¿Qué haría que no fuera seguro lanzar este cambio?»

Estas preguntas son aburridas en el mejor sentido posible. Evitan sorpresas costosas.

Ejemplo: de una funcionalidad vaga a un mejor plan

Prompt inicial:

Grill me on this: I want to add team invites to the app.

La skill debería evitar pasar directamente a las migraciones de base de datos. Una primera ronda útil podría preguntar:

Before we design the flow: who is allowed to invite members?

Recommended default: only workspace admins can invite members in v1.

Why: it keeps permissions simple, avoids accidental access expansion,
and gives us a clear policy to test.

Después de algunos intercambios, el agente puede resumir:

Decisions made:
- v1 supports email invites only.
- only workspace admins can invite users.
- invites expire after 7 days.
- accepting an invite requires login or signup with the invited email.
- deleted workspaces invalidate pending invites.

Unresolved:
- whether to support resend invite in v1
- whether invited users count toward billing before acceptance

Recommended next step:
- create a short PRD and split implementation into API, email, UI, and tests.

Esa es una entrada mucho mejor para un agente de implementación que la idea original de una sola línea.

Adáptala a tu proyecto

La skill pública grill-me es genérica de manera intencional. La versión de tu equipo no debería seguir siendo genérica para siempre.

Agrega tus reglas locales:

## Project-Specific Checks

For this repo, always ask about:

- tenant boundaries before changing data access
- audit events before changing admin workflows
- backward compatibility for mobile clients
- feature flag and rollback strategy
- whether the change needs an ADR under docs/adr/

Agrega artefactos locales:

## Repository Context

If the plan touches permissions, read:

- references/permissions-model.md
- docs/adr/004-authorization-boundaries.md

If the plan touches billing, inspect:

- src/billing/
- worker/billing-sync/
- references/billing-provider-contract.md

Aquí es donde las skills se convierten en mucho más que prompts. Se vuelven memoria reutilizable del proyecto, pero se cargan solo cuando la tarea lo requiere.

Cuándo no usar grill-me

No la uses para cada tarea pequeña.

Omítela cuando:

• el cambio es mecánico
• la implementación es obvia y de bajo riesgo
• el plan ya tiene criterios de aceptación claros
• el usuario quiere explícitamente una ejecución rápida
• el costo de hacer preguntas es mayor que el de aplicar un parche rápido

Úsala cuando:

• el trabajo abarca varios equipos o módulos
• el plan afecta el comportamiento visible para el usuario
• los requisitos son ambiguos
• la arquitectura o la estructura de datos podrían cambiar
• un rollback sería complicado
• los PMs y los ingenieros necesitan un lenguaje compartido antes de empezar a trabajar

Errores comunes

El primer error es hacer que la skill sea demasiado complaciente. Una buena sesión de preguntas debe ser amigable, pero no pasiva. El agente debe cuestionar los supuestos y pedir la evidencia que falta.

El segundo error es hacer demasiadas preguntas a la vez. Una lista interminable de veinte preguntas se siente como una tarea escolar. La skill debe hacer primero la pregunta de mayor impacto y luego adaptarse.

El tercer error es no dejar nunca que el agente inspeccione el código. Si el repositorio puede responder una pregunta, el agente debería buscar la respuesta. Pedirle a una persona que repita hechos que ya están en el código desperdicia su atención.

El cuarto error es dejar que la misma sesión derive hacia la implementación. Mantén el límite claro:

Grill first.
Decide second.
Implement third.
Review fourth.

Limitaciones actuales y advertencias honestas

Hay evidencia práctica sólida de que el patrón grill-me ayuda a los equipos a pensar antes de programar, pero todavía no existe un benchmark público a gran escala que demuestre que esta skill exacta reduce los defectos, el tiempo de ciclo o el retrabajo en muchos repositorios.

La evidencia actual proviene principalmente de:

• la adopción y reutilización de skills públicas
• la documentación de sus creadores
• las especificaciones de skills para agentes
• la experiencia de ingeniería con ciclos de planificación, revisión y aclaración
• la investigación y la práctica más amplias en torno a las skills para agentes, la divulgación progresiva y el empaquetado de flujos de trabajo

Eso significa que la postura adecuada es pragmática, no mágica. Trata grill-me como una herramienta de alineación de bajo costo. Pruébala en trabajo real del proyecto. Conserva las preguntas que detectan problemas reales. Elimina las que agregan burocracia.

Mejoras recomendadas

Si quieres hacer que el flujo de este artículo sea más operativo dentro de un equipo, las siguientes adiciones serían útiles:

• una transcripción de ejemplo de una conversación real sobre una funcionalidad
• una comparación de antes y después de una funcionalidad construida por un agente con y sin grill-me
• una plantilla de proyecto que incluya .agents/skills/grill-me/SKILL.md
• una configuración predefinida de Spec Kit o una personalización local del proyecto que inserte automáticamente un punto de control grill-me antes de /speckit.specify y /speckit.plan
• una lista de verificación para que los PMs decidan cuándo activar la skill
• un harness de pruebas para comprobar si la skill hace preguntas útiles
• ejemplos para dominios específicos: facturación, autenticación, migraciones de datos, lanzamientos móviles y herramientas internas

Lista de fuentes

• OpenAI Developers: Agent Skills en Codex
• Catálogo de skills de OpenAI para Codex
• Agent Skills: inicio rápido
• Agent Skills: especificación
• Agent Skills: mejores prácticas para creadores de skills
• Documentación de Claude Code: skills
• Documentación de GitHub Spec Kit
• README de GitHub Spec Kit
• Guía de inicio rápido de GitHub Spec Kit
• GitHub Spec Kit: desarrollo guiado por especificaciones
• Matt Pocock: skills para ingenieros reales
• SKILL.md de grill-me de Matt Pocock
• Agent Skills Lab: grill-me
• SKILL.md de grill-me de Bjorn Melin