Cómo crear una skill que funcione: descripción, SKILL.md y references

Estas dos descripciones podrían pertenecer a la misma skill:

# Versión A (ejemplo inventado)
description: Ayuda con consultas SQL de Illuminate.

# Versión B (la descripción real de la skill illuminate-sql-support)
description: Create, validate, explain, debug, and improve Snowflake SQL for
  Blackboard Data / Illuminate using the packaged current schema, documented
  fields, relationship candidates, examples, and domain notes. Use for
  Illuminate reporting questions and SQL involving the supported CDM_ALY,
  CDM_CLB, CDM_LMS, CDM_MAP, CDM_MEDIA, CDM_META, or CDM_TLM schemas.

La A es la que escribe casi cualquiera la primera vez, y no tiene nada incorrecto. Lo que no le da al agente es un motivo para cargar la skill cuando alguien pega una consulta con CDM_LMS.COURSE_ACTIVITY y pregunta por qué devuelve el doble de filas, que es justo el momento en el que la skill tiene algo que aportar. La B dice qué tareas cubre (crear, validar, explicar, depurar, mejorar), con qué material trabaja y en qué esquemas aplica, por su nombre exacto.

Este artículo recorre la anatomía de una skill a partir de esa diferencia, usando como hilo illuminate-sql-support, una skill que hemos desarrollado en eLearning Media y que genera y revisa SQL de Snowflake para Blackboard Data / Illuminate, el almacén de datos analíticos de ese LMS. La reconstruyo como un ejemplo que evoluciona: las etapas intermedias son ilustrativas y los fragmentos finales son literales de la skill.

Todavía no se puede instalar: ChatGPT no admite skills nuevas en este momento. Cuando lo permita, o cuando esté publicada en un repositorio, añadiremos cómo instalarla en Consultas SQL para Blackboard.

Si todavía no tienes clara la diferencia entre una skill y un servidor MCP, empieza por MCP vs Skills; para el mapa completo del tema, la guía de agent skills en un equipo de desarrollo.

Lo que el agente ve antes de decidir

Una skill es una carpeta con un SKILL.md y, opcionalmente, más ficheros. El SKILL.md empieza con un frontmatter YAML con dos campos obligatorios, name y description, y sigue con instrucciones en Markdown. Hasta ahí llegan casi todos los tutoriales.

Lo que de verdad condiciona cómo escribirla es la forma en que se carga. El agente no lee todas las skills disponibles en cada conversación. Al arrancar solo tiene en contexto el nombre y la descripción de cada una. Cuando decide que una encaja con la tarea, carga el cuerpo del SKILL.md. Y solo lee otro fichero de la carpeta si ese cuerpo le dice que lo abra. El estándar abierto de Agent Skills llama a esto carga progresiva.

De ahí salen las decisiones de diseño de este artículo. La descripción es lo único que existe para el agente mientras no active la skill, así que su trabajo es provocar la activación en el momento correcto. El cuerpo del SKILL.md se carga entero cada vez que la skill se usa, así que debe contener lo que aplica a cualquier tarea de su ámbito y poco más. Y los ficheros de apoyo apenas cuestan nada hasta que se leen, así que pueden ser enormes siempre que el cuerpo sepa dirigir hacia ellos.

En la skill de Illuminate esto se nota en las proporciones. El SKILL.md tiene 95 líneas. Las references suman unas 5.200: la estructura completa de la base de datos (1.595 líneas), un CSV de relaciones candidatas entre tablas (1.499), un índice plano de campos válidos (998), ejemplos de SQL (475) y notas de dominio sobre tipos de herramienta y datos semiestructurados (588). Cargar todo eso en cada pregunta sería absurdo; no cargar nada obligaría al modelo a inventar nombres de columnas.

Primera versión: todo en un fichero

Supongamos que alguien decide convertir su conocimiento de Illuminate en una skill. La primera versión suele parecerse a esto (ejemplo ilustrativo):

---
name: illuminate
description: Ayuda con consultas SQL de Illuminate.
---

# Illuminate

Eres un experto en Illuminate. Estas son las tablas disponibles:

CDM_LMS.COURSE: ID, NAME, COURSE_NUMBER, ...
CDM_LMS.PERSON: ID, FIRST_NAME, LAST_NAME, ...
(cientos de líneas con tablas, columnas y algunas consultas de ejemplo)

Tiene dos defectos que se refuerzan entre sí. La descripción compite con cualquier otra cosa que hable de SQL: otra skill de bases de datos, un servidor MCP conectado a Snowflake o el conocimiento general del modelo, que cree saber cómo es el modelo de datos de un LMS. Nada en ella indica qué esquemas cubre ni qué tipo de preguntas resuelve. Y si por fin se activa, mete en contexto cientos de líneas aunque la pregunta sea solo cómo se llama la columna de la fecha de un evento.

El name también importa, aunque menos. El estándar exige que coincida con el nombre de la carpeta, y conviene que sea específico: illuminate deja de servir en cuanto aparece una segunda skill sobre el mismo producto con otro propósito. illuminate-sql-support dice qué hace.

Segunda versión: una descripción escrita para activarse

La descripción real tiene dos partes. La primera frase dice qué hace la skill, enumerando verbos que corresponden a peticiones distintas: crear una consulta desde cero, validar una existente, explicar qué hace, depurar un error, mejorarla. Cada verbo es una forma diferente en la que alguien puede pedir ayuda, y una descripción que solo dijera «genera SQL» no se activaría con «¿por qué falla esta query?».

La segunda parte, «Use for Illuminate reporting questions and SQL involving the supported … schemas», acota el ámbito con identificadores exactos. Los nombres de esquema (CDM_LMS, CDM_TLM…) son la mejor señal de activación que tiene esta skill, porque aparecen literalmente en el SQL que la gente pega en el chat. Un identificador concreto es mucho más fiable que una descripción temática.

Comparando esta descripción con las del plugin interno de mi equipo, los triggers caen en unas pocas familias: las palabras con las que se piden las cosas, los identificadores del dominio (nombres de esquema, de clase o de fichero), los mensajes de error tal como aparecen y el ámbito que separa la skill de sus vecinas. Los mensajes de error tienen especial peso en skills operativas, porque quien pega un log no describe la tarea, pega el error.

La descripción de Illuminate tiene una limitación que merece la pena señalar. Está en inglés, igual que el resto de la skill, y la propia skill indica que responda en el idioma del usuario. Quien pregunte en castellano «¿cuántos alumnos entraron al curso la semana pasada?», sin mencionar ningún esquema, depende de que el modelo relacione esa pregunta con «Illuminate reporting questions». Añadir algunas formulaciones en castellano a la descripción reduciría esa dependencia.

Tercera versión: SKILL.md como router

Resuelta la activación, queda el cuerpo. El patrón que usamos es tratar el SKILL.md como un router: un fichero corto con el propósito, los límites, el flujo de trabajo, las reglas que no se pueden saltar y una sección que dice qué fichero abrir para cada necesidad. En la skill de Illuminate esa sección se llama «Route the references»:

## Route the references

Read references/reference-guide.md first whenever the request requires
schema-specific SQL. It explains source priority and how to use the
packaged references.

Then load only what the task needs:

- Search references/valid-fields.txt to confirm exact SCHEMA.TABLE.COLUMN
  names quickly.
- Read the relevant table sections in references/database-structure.md for
  data types, nullability, and table context.
- Search references/illuminate-relations.csv for join candidates, then verify
  both sides against the schema and business meaning.
- Consult references/sql-examples.md for patterns and style only after
  validating every referenced object against the current schema.
- Consult references/tool-assignment-types-stage.md for assignment/tool
  categorization and documented STAGE JSON access patterns.

Tres detalles de este fragmento valen para cualquier skill.

Cada línea empieza por un verbo distinto según el tipo de fichero. «Search» para el índice de campos y el CSV, que se consultan buscando una cadena exacta; «Read the relevant table sections» para la estructura de la base de datos, que se lee por secciones; «Consult» para los ejemplos y las notas. Le dice al agente cómo usar cada fichero, no solo que existe.

Hay un fichero de entrada obligatorio. reference-guide.md tiene 45 líneas y explica el orden de prioridad cuando las fuentes no coinciden: la estructura actual de la base de datos manda sobre el índice de campos, este sobre las relaciones y las relaciones sobre los ejemplos. Esa jerarquía resuelve conflictos que el agente encontraría tarde o temprano, porque las fuentes de una skill real nunca son perfectamente coherentes.

Cada reference lleva su grado de confianza. El CSV de relaciones se presenta como «candidatos», con una advertencia explícita en la guía: que dos tablas compartan una columna como PERSON_ID o COURSE_ID no prueba que se puedan unir. Los ejemplos de SQL se usan «for intent and style, not object validation», porque algunos están incompletos o son anteriores al esquema actual. Sin esas etiquetas, el agente trataría un ejemplo antiguo con la misma autoridad que el esquema.

Este patrón no es exclusivo de una skill grande. En el plugin interno de mi equipo lo usamos también en skills pequeñas; lo que cambia es la longitud de la lista.

Qué va en el SKILL.md y qué en las references

El criterio es bastante simple. En el SKILL.md va lo que aplica a cualquier tarea de la skill y lo que, si se ignora, rompe algo. En las references va lo que solo hace falta para una tarea concreta.

En Illuminate, el cuerpo contiene el alcance soportado, el flujo de trabajo en siete pasos, las reglas de SQL, el aviso de coste, una comprobación previa y el formato de respuesta. Los nombres de tablas y columnas, las relaciones y los ejemplos están fuera. La línea que separa una cosa de otra es si el agente la necesita para decidir qué hacer o solo para hacerlo.

Cuarta versión: reglas, límites y verificación

Con el router, la skill ya carga lo que necesita. Lo que la convierte en fiable es el resto del cuerpo, y aquí la skill de Illuminate tiene varias decisiones que merece la pena copiar.

El alcance está cerrado en ambas direcciones. Lista los siete esquemas soportados y nombra los que excluye: «Do not generate, suggest, or reconstruct queries against LEARN, CDM_CRM, or CDM_SIS». Si se pide algo que no está en el esquema empaquetado, la instrucción es decir que queda fuera del modelo soportado, en lugar de intentarlo.

La regla contra la invención es explícita y concreta: «Never invent schemas, tables, fields, payload keys, relationships, or enum meanings». Y un paso del flujo la refuerza para el caso más tentador: «Never infer undocumented LMS objects from general product knowledge». Un modelo sabe muchas cosas sobre LMS en general, y precisamente por eso tiende a rellenar huecos con nombres plausibles que no existen.

El límite de lo que hace la skill está escrito al principio: no se autentica, no se conecta a un tenant, no ejecuta consultas y no puede probar que una consulta funcione en un entorno concreto. Y una regla al final lo cierra: «Do not claim that SQL has been executed or validated against live tenant data». Sin esa frase, una respuesta que diga «esta consulta es correcta» puede sonar a algo comprobado cuando solo es una consulta bien escrita.

Hay un aviso obligatorio ligado a un riesgo real. Las consultas sobre CDM_TLM, los datos de telemetría, pueden escanear volúmenes enormes y consumir créditos de Illuminate. La skill obliga a incluir un aviso literal junto a cualquier consulta que toque ese esquema y a priorizar filtros por EVENT_TIME. Cuando una regla tiene coste económico, no se deja a criterio del modelo.

La verificación ocurre antes de responder. La sección «Preflight before returning SQL» pide comprobar en silencio que todos los esquemas están soportados, que todas las tablas y columnas existen, que las tablas van cualificadas, que cada join tiene un camino documentado, que el grano del resultado coincide con lo pedido, que hay filtros o límites en las consultas de alto volumen y que el aviso de coste está donde toca. Es una checklist que el agente aplica a su propia salida, y la palabra «silently» evita que la respuesta se llene de comprobaciones narradas.

El formato de respuesta está fijado: supuestos materiales, un bloque de SQL y notas sobre parámetros, joins, grano y riesgos. Y una última regla protege el contexto de la conversación: «Do not reproduce the packaged reference files wholesale».

Cuándo una regla debería ser un script

La skill de Illuminate no lleva scripts. Todo su material son datos (Markdown, CSV y un TXT) que el agente consulta con búsquedas. Para validar que una columna existe basta con buscar CDM_LMS.COURSE.COURSE_NUMBER en el índice plano, y eso un agente lo hace bien.

El límite aparece cuando la comprobación es larga y mecánica. Como ejemplo, un script que extrajera de una consulta todas las referencias SCHEMA.TABLE.COLUMN y las comparase con valid-fields.txt haría en milisegundos y sin errores lo que el preflight pide al modelo que haga leyendo. Con una consulta de diez líneas no compensa; con una de doscientas, probablemente sí.

El criterio que aplicaría para meter un script en una skill es que la comprobación sea determinista, que el material de referencia sea demasiado grande para leerlo con atención en cada uso y que el resultado sirva también fuera del agente (una persona puede lanzarlo, una pipeline también). Cuando la comprobación tiene que ejecutarse siempre, y no solo cuando el agente se acuerda de llamarla, el sitio ya no es la skill sino un hook; lo cuento en el artículo sobre cómo organizar skills, comandos y hooks en un plugin.

Y a veces la respuesta no es ni skill ni script. Hemos tenido muchas skills que parecían buena idea al principio y que en realidad solo añadían una capa de complejidad a procesos de la empresa que necesitaban procedimentarse o automatizarse, no empaquetarse para un agente. Ese criterio lo desarrollo en cuándo no crear una skill.

Errores al estructurar una skill

Casi todos se deducen de cómo funciona la carga.

Duplicar contenido entre el SKILL.md y las references. Si una regla aparece resumida en el cuerpo y desarrollada en un fichero, las dos versiones acabarán diciendo cosas distintas. La skill de Illuminate evita esto con la guía de prioridades: cuando dos fuentes discrepan, está escrito cuál gana.

Dejar ficheros huérfanos. Una reference que el router no menciona es invisible: el agente no recorre la carpeta por su cuenta. Las cinco references de Illuminate aparecen en «Route the references» y en la guía.

No marcar los límites con otras skills o herramientas. Illuminate dice qué no hace (conectarse, ejecutar) y qué esquemas no cubre. En un plugin con varias skills, cada una debería decir además qué cubre la de al lado, para que el agente no intente resolver con una lo que está documentado en otra.

Meter credenciales o datos internos. Una skill se carga en el contexto de un modelo y se distribuye con el plugin; trátala como código que puede acabar en cualquier repositorio. Si instalas skills de terceros, el riesgo va en la otra dirección, y lo trato en el artículo sobre seguridad de skills de terceros.

Escribir para la persona y no para el agente. Una skill no necesita introducción ni contexto histórico; necesita el orden de los pasos, las reglas, los límites y qué hacer cuando algo no se puede verificar. Qué conocimiento merece estar ahí lo desarrollé en skills como documentación viva. De dónde salió el conocimiento de esta skill (un Custom GPT previo) y cómo se destila, en el artículo sobre destilar el conocimiento del equipo.

Hasta dónde llega una buena descripción

Todo lo anterior aumenta las probabilidades de que la skill se active cuando toca y de que, una vez activa, el agente lea lo que necesita y no invente lo que no encuentra. No lo garantiza. La activación la decide el modelo con la información que tiene en cada conversación, y puede cambiar entre versiones del modelo sin que nadie haya tocado la skill. Incluso el preflight de Illuminate es una instrucción, no una comprobación ejecutada: el modelo puede saltársela. La única forma de saber si una skill acierta es probarla con peticiones que deberían activarla y con otras que no, y comparar sus respuestas con y sin ella. Eso ya es materia de evals de skills: sin ellas, cualquier mejora de la descripción es una suposición que nadie ha comprobado.