El Modelo de Habilidad del Agente
Una habilidad de agente es un playbook estructurado, escrito como un archivo SKILL.md, que le dice a un asistente de IA exactamente qué hacer, qué pedir y qué nunca hacer en una tarea específica de la base de datos.
Esta página construye el modelo mental detrás de esa estructura para equipos de PostgreSQL 18.4: por qué una habilidad tiene el aspecto que tiene, cómo interactúan sus partes y dónde termina y comienza el juicio humano.
Resumen
- Una habilidad es un contrato operativo con partes fijas —disparador, entradas, barreras de seguridad, salidas— que restringe a un agente a un dominio de decisión a la vez.
- Por Qué Importa: Sin un contrato, un agente recurre a suposiciones genéricas de datos de entrenamiento, lo que habitualmente significa sintaxis obsoleta y valores predeterminados inseguros en un clúster moderno y con versiones fijadas.
- Conceptos Clave: dominio de decisión, barreras de seguridad, pin de pila (stack pin), salida verificable, composición de habilidades.
- Cuándo Usar: Utiliza este modelo siempre que estés decidiendo si una tarea pertenece a la invocación de una habilidad, a un runbook humano o a una conversación simple con el agente.
- Limitaciones / Compensaciones: Una habilidad solo codifica lo que sus autores ya han aprendido, por lo que es un artefacto tardío que debe actualizarse después de cada incidente relevante o cambio de política.
- Temas Relacionados: puntuación de seguridad de migración, revisión de planes EXPLAIN, simulacros de failover, triaje de incidentes.
Fundamentos
Una habilidad existe para responder bien a una pregunta específica y estrecha, y esa estrechez es deliberada en lugar de una limitación.
Cada archivo SKILL.md nombra un único dominio de decisión —puntuación de riesgo de bloqueo de migración, crítica de plan EXPLAIN, un simulacro de failover de Patroni, o triaje de incidentes SEV1— y no intenta cubrir conocimiento general de bases de datos.
El archivo en sí está estructurado, no es prosa, con secciones fijas: qué hace la habilidad, cuándo invocarla, sus entradas requeridas, sus salidas esperadas y sus barreras de seguridad.
Las barreras de seguridad son la sección que diferencia una habilidad de un tutorial, porque un tutorial enseña a un humano cómo pensar mientras una barrera de seguridad le dice a un agente qué nunca tiene permitido hacer independientemente del contexto.
Una analogía útil es la lista de verificación de un piloto: no explica la aerodinámica, sino que restringe una decisión específica y repetible a un procedimiento conocido como seguro cada vez que se ejecuta.
Las habilidades viven junto al repositorio de la plataforma o aplicación, típicamente bajo una ruta como .cursor/skills/ o un registro a nivel de organización, de modo que viajan con la base de código que gobiernan.
Las páginas del manual humano en otros lugares de este sitio, como las secciones de EXPLAIN y migraciones, siguen siendo la fuente autorizada de conocimiento de bases de datos; una habilidad solo orquesta cómo un agente debe aplicar ese conocimiento en el momento.
Mecánica e Interacciones
La razón por la que las habilidades necesitan un pin de pila (stack pin) es que los datos de entrenamiento de un modelo de lenguaje tienen una fecha de corte, y Postgres ha seguido avanzando más allá de ella.
Sin un pin explícito, un agente utilizará por defecto modismos más antiguos —SERIAL en lugar de IDENTITY, o un simple CREATE INDEX donde se requiere CONCURRENTLY— porque esos patrones dominaron su distribución de entrenamiento.
Fijar la pila dentro del propio archivo de habilidad, en lugar de confiar en que el agente lo infiera, convierte una suposición implícita en una restricción explícita y auditable que viaja con cada invocación.
Las barreras de seguridad interactúan con las salidas de una manera específica: una habilidad bien formada nunca permite que un agente reclame éxito sin producir algo que un humano pueda verificar de forma independiente, como una consulta de verificación de bloqueos o un registro de migración en staging.
Esta es la diferencia entre un agente que afirma "la migración del índice es segura" y un agente que produce la consulta real de pg_locks que un revisor puede volver a ejecutar para confirmar esa afirmación.
Las habilidades también se componen, lo que significa que la salida de una invocación puede convertirse en el disparador de la siguiente: una puntuación de seguridad de migración por encima de un umbral puede pasar a una revisión EXPLAIN de la consulta que el nuevo índice debe servir.
El fragmento a continuación muestra la forma de ese contrato de traspaso tal como podría aparecer dentro de la sección de Salidas de un archivo de habilidad, mantenido intencionalmente pequeño ya que el punto es la forma, no el playbook completo.
## Salidas
- Puntuación de riesgo de bloqueo (bajo/medio/alto)
- Alternativa DDL más segura si aplica
- Consulta de verificación que un humano puede volver a ejecutar en staging
## Barreras de Seguridad
- Nunca sugerir un índice no CONCURRENT en una tabla de producción activa
- Nunca ejecutar DDL sin aprobación humana explícitaEsa estructura es lo que permite a un revisor confiar en la salida sin tener que derivarla desde cero.
Consideraciones Avanzadas y Aplicaciones
La elección de diseño más importante en un archivo de habilidad es qué pertenece a las barreras de seguridad frente a qué pertenece a la guía, y los equipos maduros tienden a escribir sus barreras de seguridad directamente a partir de los postmortems.
Cada incidente SEV1 o SEV2 que se rastreó hasta una acción sugerida por el agente es un candidato para una nueva línea de barrera de seguridad, lo que significa que la sección de barreras de seguridad es efectivamente el historial acumulado de casi accidentes de un equipo en forma ejecutable.
La autoridad de una habilidad también está limitada por el alcance: una habilidad de seguridad de migración nunca debe expandirse silenciosamente a consejos de optimización de consultas, porque mezclar dominios de decisión erosiona la estrechez que hizo que el contrato fuera confiable en primer lugar.
La política de invocación del equipo importa tanto como el contenido del archivo, ya que una habilidad que cualquiera puede activar contra producción sin un aprobador humano designado derrota por completo el modelo de barreras de seguridad.
A escala, las organizaciones mantienen un registro de habilidades —un índice que mapea cada habilidad a su condición de disparador y a una rotación propietaria— de modo que "a quién debo preguntar" y "qué habilidad aplica" se respondan de la misma manera cada vez.
A medida que el propio Postgres evoluciona a través de versiones principales, el pin de pila de cada habilidad se convierte en una responsabilidad de mantenimiento que debe revisarse con la misma cadencia que el calendario de actualización del propio clúster.
| Enfoque | Fortaleza | Debilidad | Mejor Ajuste |
|---|---|---|---|
| Sin habilidad, prompting ad hoc | Más rápido para empezar, cero mantenimiento | El agente recurre a suposiciones de datos de entrenamiento obsoletos cada vez | Preguntas exploratorias únicas, no tareas operativas repetidas |
| Habilidad sin barreras de seguridad forzadas | Autoría más rápida, menor sobrecarga de revisión | Nada impide que un agente proponga una acción insegura | Tareas de solo lectura de bajo riesgo como búsquedas de documentación |
| Contrato de habilidad completo (disparador + entradas + barreras de seguridad + salidas verificables) | Reproducible, auditable, seguro para entregar a operadores menos experimentados | Requiere autoría continua y mantenimiento impulsado por postmortems | Cualquier decisión recurrente de alto riesgo: migraciones, failover, respuesta a incidentes |
Conceptos Erróneos Comunes
- "Una habilidad reemplaza el runbook humano en el que se basa" — una habilidad orquesta cómo debe actuar un agente, mientras que la página del manual humano a la que hace referencia sigue siendo la explicación autorizada del por qué.
- "Las habilidades y las reglas siempre activas son lo mismo" — una regla es una restricción constante como "no DDL de producción en el chat", mientras que una habilidad es un playbook invocado con sus propias entradas y salidas; los equipos típicamente necesitan ambas.
- "Una vez escrita, una habilidad se mantiene correcta" — el pin de pila y las barreras de seguridad de una habilidad quedan obsoletos en el momento en que la versión subyacente de Postgres, el conjunto de extensiones o el historial de incidentes se mueven más allá de lo que el archivo asume.
- "Un agente que sigue una habilidad puede confiar en ejecutar DDL de producción sin supervisión" — incluso las salidas de una habilidad bien protegida están diseñadas para la verificación humana antes de la ejecución, no para la acción autónoma.
- "Más habilidades siempre significan más seguridad" — un registro de habilidades superpuesto o mal definido crea confusión sobre qué playbook aplica realmente, lo que en sí mismo se convierte en un nuevo modo de fallo.
Preguntas Frecuentes
¿Qué es exactamente una "habilidad de agente" en el contexto del trabajo de Postgres?
Un archivo SKILL.md estructurado que restringe a un asistente de IA a un dominio de decisión —como la seguridad de migración o la revisión de EXPLAIN— con entradas explícitas, barreras de seguridad y salidas verificables.
¿Cómo se diferencia una habilidad de simplemente hacerle una buena pregunta al agente?
- Una habilidad se escribe una vez y se reutiliza, mientras que una pregunta se escribe fresca cada vez.
- Las barreras de seguridad de una habilidad se aplican independientemente de cómo se formule la pregunta invocadora.
- Las salidas de una habilidad están estructuradas para su verificación; una respuesta ad hoc generalmente no lo está.
¿Por qué una habilidad necesita fijar explícitamente la versión de PostgreSQL?
Porque los datos de entrenamiento de un modelo de lenguaje son anteriores a los modismos actuales, y sin un pin explícito recurrirá a sintaxis más antigua y valores predeterminados menos seguros de lo que un clúster moderno realmente necesita.
¿Cuál es la sección más importante de un archivo de habilidad?
La sección de barreras de seguridad, ya que codifica las acciones específicas que un equipo ha aprendido —a menudo a través de un postmortem— que un agente nunca debe tomar.
¿Pueden las habilidades llamar a otras habilidades?
Sí: un patrón común es que la salida de una habilidad se convierta en el disparador de una segunda habilidad, como una puntuación de migración que pasa a una revisión EXPLAIN de la consulta afectada.
¿Reemplaza una habilidad alguna vez las páginas del manual humano en este sitio?
No: las páginas humanas siguen siendo la explicación autorizada del concepto subyacente, y la habilidad solo gobierna cómo un agente aplica ese concepto en un momento específico.
¿Qué sucede si dos habilidades parecen aplicarse a la misma tarea?
Esa superposición es en sí misma una señal de que el registro de habilidades necesita ser ajustado, ya que la ambigüedad sobre qué playbook aplica socava el propósito de tener habilidades específicas y nombradas.
¿Debería una habilidad permitir alguna vez que un agente ejecute DDL en producción automáticamente?
No: incluso una habilidad completamente protegida está diseñada para producir una propuesta y pasos de verificación para que un humano los apruebe, no para ejecutar cambios sin supervisión.
¿Cómo deciden los equipos cuándo se necesita una nueva barrera de seguridad?
La mayoría de los equipos escriben una nueva línea de barrera de seguridad directamente de cada postmortem, convirtiendo un casi accidente o incidente específico en una restricción permanente para invocaciones futuras.
¿Dónde deberían vivir los archivos SKILL.md en un repo?
Típicamente junto al código de la plataforma o aplicación que gobiernan, como .cursor/skills/, para que el playbook viaje con el mismo historial de versiones que el esquema sobre el que opera.
¿Qué es una "salida verificable" y por qué es tan importante?
Es una salida que un humano puede volver a ejecutar y confirmar de forma independiente, como una consulta de verificación de bloqueos, en lugar de una simple afirmación de éxito que debe tomarse por fe.
¿Es este modelo específico de Postgres, o se aplica a cualquier base de datos?
Los dominios de decisión específicos tienen sabor a Postgres, pero la forma del contrato —disparador, entradas, barreras de seguridad, salidas verificables— es un patrón general para cualquier tarea operativa repetida de alto riesgo.
Relacionado
- Conceptos Básicos de Habilidades de Agente - los diez ejemplos concretos de los que se generaliza el modelo de esta página.
- Habilidad de Seguridad de Migración - una habilidad completa construida sobre esta forma de contrato.
- Habilidad de Revisión EXPLAIN - el dominio de decisión del plan de consulta en la práctica.
- Habilidad de Simulacro de Failover - el dominio de decisión de HA en la práctica.
- Habilidad de Triaje de Incidentes - el dominio de decisión SEV1 en la práctica.
- Conceptos Básicos de Migraciones - el manual humano al que una habilidad de migración delega.
Versiones de la Pila: Esta página fue escrita para clústeres de PostgreSQL 18.4 que usan Patroni 3.x para alta disponibilidad; las versiones específicas de las herramientas de migración y copia de seguridad referenciadas por habilidades individuales se fijan en sus propias páginas.