De la wiki, el Custom GPT y el CLAUDE.md a una skill: cómo destilar el conocimiento de un equipo

El fichero más grande de la skill de Illuminate todavía dice que es para un Custom GPT.

Está en la cabecera de database-structure.md, las casi 1.600 líneas que describen el esquema de Blackboard Data / Illuminate: «Do not use, index, retrieve, or generate SQL against LEARN, CDM_CRM, or CDM_SIS for this custom GPT». La skill, illuminate-sql-support, la hemos desarrollado en eLearning Media y se empaqueta como plugin; nació a partir de un Custom GPT previo que hacía el mismo trabajo, generar y revisar SQL de Snowflake para ese almacén de datos. La frase sobrevivió a la migración, probablemente porque estaba en un fichero de datos y no en las instrucciones, que es donde se suele revisar.

La información para instalarla se publicará en Consultas SQL para Blackboard cuando ChatGPT vuelva a admitir skills nuevas o cuando la subamos a un repositorio.

Esa línea resume bien lo que pasa al convertir conocimiento existente en skills. El contenido casi nunca se escribe desde cero: se traslada desde algún sitio donde ya funcionaba para otro lector y otro formato, y arrastra restos de ese origen. En el plugin interno de mi equipo pasa lo mismo, con fuentes de todo tipo. Este artículo recorre el caso de Illuminate en detalle y después el resto de fuentes habituales, centrado en el proceso y en lo que cada una obliga a cambiar. Qué contenido merece estar en una skill lo traté en skills como documentación viva.

Qué necesita el agente que las fuentes no le dan

Una skill útil le da al agente tres cosas: las reglas que no se pueden saltar, con su consecuencia; el material que necesita consultar sin inventar (esquemas, firmas, catálogos); y los límites de lo que puede afirmar. Además necesita una descripción que la active en el momento correcto, y una forma de llegar solo a la parte del material que le hace falta. Esas dos piezas las desarrollo en cómo crear una skill que funcione.

Las fuentes de las que se parte rara vez vienen en esa forma. La documentación explica todo con el mismo peso. Un CLAUDE.md da por hecho su repositorio. Un Custom GPT está pensado para una persona que pregunta en una ventana aparte. Y la operativa no está escrita en ningún sitio.

Del Custom GPT a la skill: el caso de Illuminate

El paso de GPT a skill vino forzado por la deprecación de los GPT de Illuminate, y trajo un cambio que no tiene nada que ver con el formato. El GPT tenía control de acceso: una custom action validaba un token, y solo lo usaba quien tenía uno. La skill se ha dejado abierta para todo el mundo.

Es una consecuencia de pasar a skill que se comenta poco. Un GPT vive dentro de una plataforma que permite poner una comprobación delante; una skill es una carpeta de ficheros que se instala y se lee, y no hay ningún punto donde validar quién la usa. Lo que se empaqueta en ella pasa a ser, a efectos prácticos, conocimiento abierto. En este caso encaja, porque la skill no se conecta a ningún tenant ni ejecuta consultas: distribuye conocimiento sobre el esquema, y los datos siguen detrás del acceso a Snowflake de quien la use. Pero cambia la pregunta con la que se revisa el contenido. Antes bastaba con saber quién tenía token; ahora hay que mirar fichero a fichero si todo puede leerlo cualquiera, y si algo no puede, sacarlo de la skill y dejar el control donde todavía exista, en el canal de distribución o en el acceso a los datos.

Un Custom GPT tiene instrucciones y ficheros de conocimiento que el propio producto consulta cuando lo necesita. Quien lo usa abre una conversación, pide una consulta, la copia y la lleva a su cliente de Snowflake. Una skill, en cambio, la carga un agente que puede estar trabajando en un repositorio, dentro de una herramienta como Claude Code o Codex, y que solo lee los ficheros que el SKILL.md le indica.

Ese cambio de lector explica casi todas las decisiones que se ven en la skill.

El esquema se regenera, no se copia

La estructura de la base de datos no viene de documentación, sino de una exportación del esquema actual. La cabecera del fichero lo dice («Generated from database export/query-1») y añade una instrucción que delata la fuente anterior: «Prefer this file over older PDF-derived schema lists when there is a conflict». Había listas de esquema sacadas de PDF, y la skill las relega explícitamente.

Es la decisión más importante de la migración. Un modelo que genera SQL falla sobre todo inventando nombres plausibles de tablas y columnas, y la única defensa es un esquema que coincida con la base de datos real. El fichero resume siete esquemas con 72 vistas y 998 columnas, y cada tabla tiene su sección con tipos y nulabilidad.

Material derivado para que el agente busque bien

Junto al esquema hay dos ficheros que no aportan información nueva: son formas de llegar a ella. valid-fields.txt tiene una línea por columna (CDM_LMS.COURSE.COURSE_NUMBER), 998 en total, para validar un nombre con una búsqueda exacta sin leer secciones enteras. illuminate-relations.csv indexa qué tablas comparten columnas con aspecto de clave.

Destilar para un agente incluye este tipo de trabajo: generar índices pensados para cómo va a buscar. Una persona navega un documento; un agente busca cadenas.

Cada fuente lleva su grado de confianza

El CSV de relaciones no se presenta como verdad. La guía de references aclara que no incluye la columna del lado primario ni la cardinalidad, y que cada fila es «a candidate navigation hint, not a guaranteed foreign-key declaration». Antes de usar un join, el agente tiene que comprobar la columna en las dos tablas, comparar tipos, confirmar que el significado de negocio encaja y preferir joins que ya aparezcan en un ejemplo válido.

Los ejemplos de SQL bajan todavía más de rango: «Some examples are duplicated, abbreviated, incomplete, or may predate the current schema. Use them for intent and style, not object validation». Y la guía fija un orden de prioridad para cuando las fuentes no coinciden: esquema actual, índice de campos, relaciones, ejemplos y notas de dominio.

Esto es lo que más diferencia una destilación cuidada de un volcado. En un Custom GPT es habitual subir los ficheros de conocimiento tal cual, y el modelo los trata a todos igual. En la skill, cada fichero dice cuánto hay que fiarse de él.

No todo se limpia

El fichero de notas sobre tipos de herramienta y datos semiestructurados (tool-assignment-types-stage.md) conserva marcas de haber sido extraído de otro documento: empieza con «Here is a detailed breakdown of what this SQL query does» y tiene viñetas vacías antes de la lista que deberían encabezar. Está en la skill porque contiene algo que no está en ningún otro sitio, cómo acceder a las claves del JSON de la columna STAGE, y la guía lo etiqueta como notas de dominio cuyas claves «are payload keys, not physical database columns».

Es una decisión razonable. Reescribir ese fichero no cambiaría lo que el agente necesita de él, y el router ya limita su uso a una tarea concreta. Destilar no obliga a pulir todo; obliga a saber qué papel tiene cada pieza.

Lo que no existía en el GPT, o no hacía falta

Hay partes de la skill que responden directamente al nuevo contexto. El límite escrito al principio («It does not authenticate users, connect to an Illuminate tenant, inspect live data, execute queries…») importa más cuando el agente tiene acceso a una terminal y podría intentar ejecutar algo. El aviso de coste obligatorio para cualquier consulta sobre CDM_TLM, que puede escanear muchos datos de eventos y consumir créditos de Illuminate, separa un hecho del sistema (el coste) de una política (avisar siempre). Y el plugin incluye un agents/openai.yaml para Codex: la misma carpeta de skill sirve en más de una herramienta, cosa que un Custom GPT no permite.

Las otras fuentes: wiki, CLAUDE.md, documentación y operativa

El caso de Illuminate es un tipo de fuente. Hay otras habituales, y cada una obliga a un trabajo diferente.

Los CLAUDE.md ya están escritos para un modelo, pero para un repositorio concreto, y se cargan siempre. Si se juntan los de varios proyectos, lo habitual es encontrar texto repetido con pequeñas diferencias. Destilarlos es quedarse con lo común en una skill y dejar en cada CLAUDE.md solo lo propio del proyecto, y decidir, cuando dos repos discrepan, cuál de los dos refleja la convención real.

Una wiki está escrita para personas, con contexto, historia y decisiones que ya no aplican. Lo que se aprovecha de ella son las decisiones vigentes, y para saber cuáles lo son hay que contrastarlas con el código. Una convención que nadie ha comprobado contra los repositorios es una opinión, y un agente la aplica igual que si fuera una regla.

La documentación oficial de un fabricante tiene dos trabajos propios. Hay que extraer las decisiones de entre explicaciones que tienen todas el mismo peso, y separar lo que dice el fabricante de lo que decide el equipo, marcando cada cosa. Si la documentación tiene erratas o contradicciones, la skill debe registrarlas junto con la versión que se usa, porque si no el agente copiará la errata.

La operativa (despliegues, pipelines, incidencias) es la fuente que más conocimiento nuevo aporta, porque no estaba escrita. Dos decisiones de formato la hacen útil: escribir los errores tal como aparecen, porque así llegan al agente, y marcar como «por confirmar» los valores que no se conocen para que el agente los pregunte en lugar de deducirlos. Este tipo de skill encaja con algo que vemos en el trabajo: cada vez usamos menos n8n para automatizaciones, porque con IA un script se escribe rápido y se despliega dockerizado. Una skill que sabe cómo hacerlo en nuestro entorno es la que hace que ese script salga bien a la primera.

El proceso que se repite

Con cualquier fuente, el recorrido hasta la skill tiene los mismos pasos, aunque cada fuente pese más en uno:

1. Identificar la fuente de verdad y regenerar desde ella lo que se pueda (un esquema desde la base de datos, no desde un PDF).
2. Separar reglas, material de consulta y límites. Las reglas van al SKILL.md con su consecuencia; el material, a references.
3. Etiquetar cada reference con su grado de confianza y fijar qué fuente gana cuando discrepan.
4. Generar los índices que el agente necesita para buscar, aunque no aporten información nueva.
5. Marcar lo que no se sabe y separar lo que dice el fabricante de lo que decide el equipo.
6. Buscar restos del origen (rutas, nombres de proyecto, «this custom GPT») también en los ficheros de datos, no solo en las instrucciones.
7. Escribir la descripción al final, a partir de las peticiones reales, no del título del tema.

Cómo se empaquetan después esas skills junto a comandos y hooks está en el artículo sobre plugins de Claude Code, y el mapa general, en la guía de agent skills.

La pregunta que sigue abierta

Destilar una skill la separa de su fuente, y la fuente sigue cambiando. El esquema de Illuminate cambiará con las versiones del producto, y la skill solo será fiable mientras su exportación coincida con la base de datos real. El índice de campos y el CSV de relaciones dependen de ese mismo esquema, así que cualquier regeneración tiene que arrastrar los tres ficheros.

Para un esquema, la respuesta parece clara: automatizar la exportación y regenerar los ficheros derivados en cada cambio. Para una convención de equipo o una operativa de despliegue no hay exportación posible, y no tengo claro qué debería disparar la revisión. Lo que sí sé es que una skill destilada sin nadie que la mantenga acaba siendo exactamente la documentación muerta que se quería evitar, con el agravante de que el agente la sigue al pie de la letra.