sql-optimization-patterns

Visión general de la skill sql-optimization-patterns

Qué hace sql-optimization-patterns

La skill sql-optimization-patterns ayuda a un agente a diagnosticar SQL lento, explicar por qué una consulta es lenta y proponer correcciones concretas sobre la forma de la query, indexación, joins, paginación y lectura de planes de ejecución. Resulta especialmente útil cuando ya tienes un problema real de rendimiento y quieres seguir un flujo de optimización estructurado, en lugar de limitarte a consejos genéricos del tipo “añade un índice”.

Quién debería instalarla

Esta skill encaja bien para backend engineers, database engineers, equipos de plataforma y desarrolladores de aplicaciones que necesitan acelerar consultas sin ir a ciegas. Es especialmente relevante para equipos que trabajan con salida de EXPLAIN al estilo PostgreSQL, aunque los patrones de razonamiento también se trasladan a otras bases de datos relacionales.

Trabajo real que resuelve

Normalmente, los usuarios necesitan algo más que una revisión de sintaxis. Necesitan:

• identificar por qué una consulta es lenta
• relacionar los síntomas del plan con causas raíz probables
• decidir entre reescribir la query o cambiar índices
• evitar “arreglos” que aceleren una consulta pero perjudiquen escrituras o almacenamiento
• comunicar con claridad los tradeoffs al equipo

Ahí es donde sql-optimization-patterns aporta más valor que un prompt genérico.

Qué diferencia a esta skill

Su principal diferencial es el enfoque basado en patrones. No se limita a decir “optimiza el SQL”; empuja al agente hacia problemas prácticos de ingeniería de bases de datos, como:

• leer EXPLAIN y EXPLAIN ANALYZE
• detectar sequential scans, joins mal elegidos y paginación ineficiente
• elegir estrategias de indexación de forma intencional
• tratar anti-patrones habituales como los accesos N+1

Casos ideales y casos menos adecuados

Mejor encaje:

• una consulta lenta ya identificada
• un plan de consulta que puedas pegar
• detalles del esquema, índices y contexto de volumen de filas disponibles
• trabajo de rendimiento ligado a latencia de API o carga de base de datos

Peor encaje:

• no hay texto de la consulta
• no hay plan de ejecución
• preguntas puramente de arquitectura a nivel ORM sin visibilidad del SQL
• tuning específico del proveedor que depende de internals del motor no incluidos en el prompt

Cómo usar la skill sql-optimization-patterns

Contexto de instalación de sql-optimization-patterns

El repositorio no muestra un instalador personalizado dentro de SKILL.md, así que debes instalarla mediante tu flujo de carga de skills para el repositorio wshobson/agents y, después, asegurarte de que tu agente pueda acceder a la skill llamada sql-optimization-patterns.

Si tu entorno usa el flujo habitual de Skills, el patrón práctico es añadir el repositorio y luego invocar la skill por nombre dentro de una tarea que pida con claridad un análisis de optimización SQL.

Lee primero este archivo

Empieza por:

• plugins/developer-essentials/skills/sql-optimization-patterns/SKILL.md

Esta skill es autocontenida. No hay references/, rules/ ni scripts de apoyo dentro de la carpeta de la skill, así que casi toda la guía útil está en ese único archivo. Eso facilita una adopción rápida, pero también significa que la calidad de tu input importa todavía más.

Qué input necesita la skill

Para obtener un buen resultado, dale al agente:

• la consulta SQL
• el motor de base de datos y la versión, si se conocen
• los esquemas de tablas o las columnas relevantes
• los índices existentes
• la escala de filas o tamaños aproximados de tablas
• la salida de EXPLAIN o EXPLAIN ANALYZE
• el objetivo de negocio, por ejemplo “reducir la latencia P95 del endpoint”

Sin datos del plan, el agente puede seguir sugiriendo patrones, pero las recomendaciones serán menos fiables.

Prompt mínimo viable

Un prompt funcional de sql-optimization-patterns usage se parece a este:

Use the sql-optimization-patterns skill.

Database: PostgreSQL 15
Goal: reduce this query from 2.4s to under 200ms
Tables:
- users(id, email, created_at, status)
- orders(id, user_id, order_total, created_at)

Current indexes:
- users_pkey(id)
- orders_user_id_idx(user_id)

Query:
SELECT u.*, o.order_total
FROM users u
JOIN orders o ON u.id = o.user_id
WHERE u.created_at > NOW() - INTERVAL '30 days'
ORDER BY u.created_at DESC
LIMIT 100;

EXPLAIN ANALYZE:
[paste full plan]

Please identify likely bottlenecks, explain the plan, recommend query/index changes, and rank fixes by expected impact and risk.

Cómo convertir una petición vaga en una buena petición

Petición débil:

Make this SQL faster.

Petición sólida:

Use sql-optimization-patterns for Database Engineering.

I need:
1. plan interpretation
2. likely root cause
3. index recommendations with rationale
4. query rewrite options
5. tradeoffs for write amplification and storage
6. a safe rollout order

Engine: PostgreSQL 14
Traffic pattern: read-heavy API endpoint
Data scale: users 8M rows, orders 120M rows
Current problem: endpoint P95 is 1.8s, DB CPU spikes during peak
Query: [paste]
Plan: [paste]
Existing indexes: [paste]

El segundo prompt funciona mejor porque da a la skill suficiente contexto operativo para priorizar soluciones, en vez de limitarse a enumerar consejos genéricos.

Flujo práctico para sacar los mejores resultados

Un buen flujo de trabajo es:

1. pegar la consulta exacta y el plan completo
2. pedir al agente que explique en lenguaje claro qué factores generan más coste
3. pedir 2-3 soluciones candidatas, no 10
4. solicitar la ventaja esperada y la desventaja de cada una
5. implementar primero el cambio de menor riesgo
6. volver a ejecutar EXPLAIN ANALYZE
7. comparar el antes y el después

Así mantienes la skill centrada en resultados medibles y no en tuning especulativo.

En qué destaca especialmente la skill

El material fuente pone mucho énfasis en:

• interpretación de EXPLAIN
• estrategia de índices
• análisis de patrones de joins
• eficiencia de la paginación
• problemas de consultas N+1

Eso convierte a sql-optimization-patterns en una opción muy sólida para optimización a nivel de query y decisiones de esquema/indexación, no solo para formatear SQL.

Qué conviene pedir explícitamente

Para obtener resultados más útiles al instalar y usar sql-optimization-patterns install, pídele al agente:

• “the single biggest bottleneck in this plan”
• “whether a new index or a query rewrite is the better first move”
• “which scan/join types are hurting me”
• “whether the query can become index-only”
• “how this change affects writes, vacuum, or storage”
• “what to measure after rollout”

Estas peticiones fuerzan la priorización, que muchas veces marca la diferencia entre una respuesta útil y otra llena de ruido.

Bloqueos habituales durante la adopción

Los principales bloqueos no suelen ser de instalación, sino de falta de evidencia:

• salida parcial del plan
• sin información sobre tamaño de tablas
• sin lista de índices actuales
• SQL generado por ORM pegado sin contexto de negocio
• pedir “best practices” en lugar de diagnosticar una ruta real

Si solo das el texto de la consulta, espera sugerencias amplias. Si aportas el plan, el esquema y el contexto de carga, la skill se vuelve mucho más útil para tomar decisiones.

Cómo interpretar la salida con seguridad

No des por hecho que cada índice sugerido es una mejora gratis. Una buena mentalidad de sql-optimization-patterns guide consiste en validar:

• si los filtros o predicados de join realmente coinciden con el orden del índice propuesto
• si la query es lo bastante selectiva como para beneficiarse
• si conviene más un índice compuesto que varios índices de una sola columna
• si la solución ayuda a una consulta pero empeora el rendimiento de inserts/updates

La skill da lo mejor de sí cuando se usa para generar hipótesis que puedas validar de inmediato.

Preguntas frecuentes sobre la skill sql-optimization-patterns

¿Vale la pena instalar sql-optimization-patterns si ya sé SQL?

Sí, si quieres un análisis de optimización consistente cuando hay presión. El valor no está en conocimientos básicos de SQL, sino en el conjunto estructurado de patrones sobre planes, tipos de scan, joins y elección de índices.

¿Es una skill apta para principiantes?

Sí, hasta cierto punto, pero los principiantes deberían usarla con ejemplos reales. La skill se entiende mucho mejor cuando comparas el texto de la consulta con la salida de EXPLAIN ANALYZE. Si eres nuevo en planes de ejecución, pídele al agente que defina cada nodo importante en lenguaje sencillo antes de recomendar cambios.

¿En qué mejora esto a un prompt normal de IA?

Un prompt normal suele devolver consejos genéricos de tuning. La sql-optimization-patterns skill está orientada a un flujo de optimización repetible y a las señales prácticas que importan en ingeniería de bases de datos, especialmente la interpretación de planes y la estrategia de índices.

¿Requiere PostgreSQL?

No, aunque los ejemplos tienen claramente un enfoque PostgreSQL. Si usas MySQL, SQLite, SQL Server u otro motor, incluye el nombre del motor y la salida equivalente del plan para que el agente pueda adaptar la orientación.

¿Cuándo no debería usar sql-optimization-patterns?

No empieces por aquí si el problema principal es:

• connection pooling
• lock contention sin evidencia de consultas
• saturación de infraestructura fuera de la base de datos
• ausencia de una estrategia de caché en la aplicación
• mal uso del ORM que oculta el SQL real

En esos casos, esta skill puede ayudar más adelante, pero no es la primera herramienta que deberías usar.

¿Puede ayudar con diseño de esquema y no solo con una consulta lenta?

Sí. La skill cubre estrategia de indexación y patrones de consulta escalables, por lo que también puede apoyar decisiones de esquema. Aun así, funciona mejor cuando se vincula a patrones de acceso, filtros esperados, joins, criterios de ordenación y volumen de datos.

Cómo mejorar la skill sql-optimization-patterns

Dale a sql-optimization-patterns mejor evidencia

La forma más rápida de mejorar los resultados es aportar:

• el texto completo de la consulta, no una paráfrasis
• la salida completa del plan, no solo las primeras líneas
• tiempos reales de EXPLAIN ANALYZE cuando sea seguro
• índices existentes
• cardinalidad aproximada y número de filas
• si la carga es principalmente de lectura o de escritura

Una mejor evidencia produce recomendaciones más creíbles y menos índices irrelevantes.

Pide recomendaciones priorizadas

La skill es más útil cuando le pides que ordene las soluciones según:

• impacto esperado en latencia
• esfuerzo de implementación
• riesgo operativo
• sobrecoste en escritura
• reversibilidad

Esa priorización ayuda a los equipos a elegir una acción, no solo a recopilar ideas.

Obliga a analizar tradeoffs

Un fallo habitual es aceptar una solución de lectura rápida que encarece las escrituras o infla los índices. Mejora la salida de sql-optimization-patterns preguntando:

• “What does this index cost on inserts and updates?”
• “Will this create redundant indexes?”
• “Would partitioning or a rewrite be better than another index?”
• “Is keyset pagination better here than offset pagination?”

Usa iteración con antes y después

Tras la primera recomendación, vuelve a ejecutar el plan y pide a la skill que compare:

• el cuello de botella original
• el nuevo cuello de botella
• qué mejoró
• qué sigue siendo costoso
• si la siguiente optimización sigue mereciendo la pena

Es la forma más fiable de convertir la skill en un bucle de optimización y no en una respuesta puntual.

Vigila los modos de fallo más comunes

Los errores más habituales son:

• optimizar sin datos de ANALYZE
• añadir índices para filtros con baja selectividad
• ignorar el orden de los joins y las estimaciones de cardinalidad
• reescribir SQL sin validar el nuevo plan
• centrarse en una sola query mientras se pasa por alto un patrón N+1 aguas arriba

Puedes reducir estos errores si pides al agente que exponga sus supuestos de forma explícita antes de sugerir cambios.

Patrones de prompt que mejoran la calidad de salida

Usa prompts como este:

Use the sql-optimization-patterns skill and do not give generic advice.
Base recommendations on the query plan provided.
For each proposed fix, explain:
1. why it should help
2. what plan node it targets
3. what tradeoff it introduces
4. how to validate it after deployment

Ese formato obliga al agente a conectar cada sugerencia con la evidencia disponible.

Mejora la adopción en equipo

Si quieres que esta skill ayude de verdad a un equipo, estandariza la plantilla de entrada:

• engine/version
• query
• schema
• indexes
• plan
• table sizes
• target latency
• workload notes

Así reduces la variabilidad y haces que sql-optimization-patterns for Database Engineering sea mucho más repetible entre incidencias y revisiones de código.