De la wiki, el Custom GPT i el CLAUDE.md a una skill: com destil·lar el coneixement d'un equip

El fitxer més gran de la skill d’Illuminate encara diu que és per a un Custom GPT.

És a la capçalera de database-structure.md, les gairebé 1.600 línies que descriuen l’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, l’hem desenvolupada a eLearning Media i s’empaqueta com a plugin; va néixer a partir d’un Custom GPT previ que feia la mateixa feina, generar i revisar SQL de Snowflake per a aquest magatzem de dades. La frase va sobreviure a la migració, probablement perquè era en un fitxer de dades i no a les instruccions, que és on se sol revisar.

La informació per instal·lar-la es publicarà a Consultas SQL para Blackboard (web en castellà) quan ChatGPT torni a admetre skills noves o quan la pugem a un repositori.

Aquesta línia resumeix bé el que passa quan es converteix coneixement existent en skills. El contingut gairebé mai no s’escriu des de zero: es trasllada des d’algun lloc on ja funcionava per a un altre lector i un altre format, i arrossega restes d’aquest origen. Al plugin intern del meu equip passa el mateix, amb fonts de tota mena. Aquest article recorre el cas d’Illuminate amb detall i després la resta de fonts habituals, centrat en el procés i en el que cadascuna obliga a canviar. Quin contingut mereix ser en una skill ho vaig tractar a skills com a documentació viva.

Què necessita l’agent que les fonts no li donen

Una skill útil dona a l’agent tres coses: les regles que no es poden saltar, amb la seva conseqüència; el material que ha de consultar sense inventar (esquemes, signatures, catàlegs); i els límits del que pot afirmar. A més, necessita una descripció que l’activi en el moment correcte, i una manera d’arribar només a la part del material que li cal. Aquestes dues peces les desenvolupo a com crear una skill que funcioni.

Les fonts de què es parteix rarament tenen aquesta forma. La documentació ho explica tot amb el mateix pes. Un CLAUDE.md dona per descomptat el seu repositori. Un Custom GPT està pensat per a una persona que pregunta en una finestra a part. I l’operativa no està escrita enlloc.

Del Custom GPT a la skill: el cas d’Illuminate

El pas de GPT a skill va venir forçat per la deprecació dels GPT d’Illuminate, i va portar un canvi que no té res a veure amb el format. El GPT tenia control d’accés: una custom action validava un token, i només el feia servir qui en tenia un. La skill s’ha deixat oberta per a tothom.

És una conseqüència de passar a skill de la qual es parla poc. Un GPT viu dins d’una plataforma que permet posar-hi una comprovació al davant; una skill és una carpeta de fitxers que s’instal·la i es llegeix, i no hi ha cap punt on validar qui la fa servir. El que s’hi empaqueta passa a ser, a efectes pràctics, coneixement obert. En aquest cas encaixa, perquè la skill no es connecta a cap tenant ni executa consultes: distribueix coneixement sobre l’esquema, i les dades continuen darrere de l’accés a Snowflake de qui la faci servir. Però canvia la pregunta amb què es revisa el contingut. Abans n’hi havia prou de saber qui tenia token; ara cal mirar fitxer per fitxer si tot ho pot llegir qualsevol, i si alguna cosa no, treure-la de la skill i deixar el control on encara existeixi, al canal de distribució o a l’accés a les dades.

Un Custom GPT té instruccions i fitxers de coneixement que el mateix producte consulta quan els necessita. Qui el fa servir obre una conversa, demana una consulta, la copia i la porta al seu client de Snowflake. Una skill, en canvi, la carrega un agent que pot estar treballant en un repositori, dins d’una eina com Claude Code o Codex, i que només llegeix els fitxers que el SKILL.md li indica.

Aquest canvi de lector explica gairebé totes les decisions que es veuen a la skill.

L’esquema es regenera, no es copia

L’estructura de la base de dades no ve de documentació, sinó d’una exportació de l’esquema actual. La capçalera del fitxer ho diu («Generated from database export/query-1») i hi afegeix una instrucció que delata la font anterior: «Prefer this file over older PDF-derived schema lists when there is a conflict». Hi havia llistes d’esquema extretes de PDF, i la skill les relega explícitament.

És la decisió més important de la migració. Un model que genera SQL falla sobretot inventant noms plausibles de taules i columnes, i l’única defensa és un esquema que coincideixi amb la base de dades real. El fitxer resumeix set esquemes amb 72 vistes i 998 columnes, i cada taula té la seva secció amb tipus i nul·labilitat.

Material derivat perquè l’agent busqui bé

Al costat de l’esquema hi ha dos fitxers que no aporten informació nova: són maneres d’arribar-hi. valid-fields.txt té una línia per columna (CDM_LMS.COURSE.COURSE_NUMBER), 998 en total, per validar un nom amb una cerca exacta sense llegir seccions senceres. illuminate-relations.csv indexa quines taules comparteixen columnes amb aspecte de clau.

Destil·lar per a un agent inclou aquest tipus de feina: generar índexs pensats per a com buscarà. Una persona navega per un document; un agent busca cadenes.

Cada font porta el seu grau de confiança

El CSV de relacions no es presenta com a veritat. La guia de references aclareix que no inclou la columna del costat primari ni la cardinalitat, i que cada fila és «a candidate navigation hint, not a guaranteed foreign-key declaration». Abans de fer servir un join, l’agent ha de comprovar la columna a les dues taules, comparar tipus, confirmar que el significat de negoci encaixa i preferir joins que ja apareguin en un exemple vàlid.

Els exemples de SQL baixen encara més de rang: «Some examples are duplicated, abbreviated, incomplete, or may predate the current schema. Use them for intent and style, not object validation». I la guia fixa un ordre de prioritat per quan les fonts no coincideixen: esquema actual, índex de camps, relacions, exemples i notes de domini.

Això és el que més diferencia una destil·lació acurada d’un bolcat. En un Custom GPT és habitual pujar els fitxers de coneixement tal qual, i el model els tracta tots igual. A la skill, cada fitxer diu quant s’hi ha de refiar l’agent.

No tot es neteja

El fitxer de notes sobre tipus d’eina i dades semiestructurades (tool-assignment-types-stage.md) conserva marques d’haver estat extret d’un altre document: comença amb «Here is a detailed breakdown of what this SQL query does» i té pics buits abans de la llista que haurien d’encapçalar. És a la skill perquè conté una cosa que no és enlloc més, com accedir a les claus del JSON de la columna STAGE, i la guia l’etiqueta com a notes de domini les claus de les quals «are payload keys, not physical database columns».

És una decisió raonable. Reescriure aquest fitxer no canviaria el que l’agent en necessita, i el router ja en limita l’ús a una tasca concreta. Destil·lar no obliga a polir-ho tot; obliga a saber quin paper té cada peça.

El que no existia al GPT, o no feia falta

Hi ha parts de la skill que responen directament al nou context. El límit escrit al principi («It does not authenticate users, connect to an Illuminate tenant, inspect live data, execute queries…») importa més quan l’agent té accés a una terminal i podria intentar executar alguna cosa. L’avís de cost obligatori per a qualsevol consulta sobre CDM_TLM, que pot escanejar moltes dades d’esdeveniments i consumir crèdits d’Illuminate, separa un fet del sistema (el cost) d’una política (avisar sempre). I el plugin inclou un agents/openai.yaml per a Codex: la mateixa carpeta de skill serveix en més d’una eina, cosa que un Custom GPT no permet.

Les altres fonts: wiki, CLAUDE.md, documentació i operativa

El cas d’Illuminate és un tipus de font. N’hi ha d’altres d’habituals, i cadascuna obliga a una feina diferent.

Els CLAUDE.md ja estan escrits per a un model, però per a un repositori concret, i es carreguen sempre. Si s’ajunten els de diversos projectes, el més habitual és trobar text repetit amb petites diferències. Destil·lar-los és quedar-se amb el que és comú en una skill i deixar a cada CLAUDE.md només el que és propi del projecte, i decidir, quan dos repos discrepen, quin dels dos reflecteix la convenció real.

Una wiki està escrita per a persones, amb context, història i decisions que ja no s’apliquen. El que se n’aprofita són les decisions vigents, i per saber quines ho són cal contrastar-les amb el codi. Una convenció que ningú no ha comprovat contra els repositoris és una opinió, i un agent l’aplica igual que si fos una regla.

La documentació oficial d’un fabricant té dues feines pròpies. Cal extreure les decisions d’entre explicacions que tenen totes el mateix pes, i separar el que diu el fabricant del que decideix l’equip, marcant cada cosa. Si la documentació té errates o contradiccions, la skill les ha de registrar juntament amb la versió que es fa servir, perquè si no l’agent copiarà l’errata.

L’operativa (desplegaments, pipelines, incidències) és la font que aporta més coneixement nou, perquè no estava escrita. Dues decisions de format la fan útil: escriure els errors tal com apareixen, perquè així arriben a l’agent, i marcar com a «per confirmar» els valors que no es coneixen perquè l’agent els pregunti en lloc de deduir-los. Aquest tipus de skill encaixa amb una cosa que veiem a la feina: cada vegada fem servir menys n8n per a automatitzacions, perquè amb IA un script s’escriu ràpid i es desplega dockeritzat. Una skill que sap com fer-ho al nostre entorn és la que fa que aquest script surti bé a la primera.

El procés que es repeteix

Amb qualsevol font, el recorregut fins a la skill té els mateixos passos, encara que cada font pesi més en un:

1. Identificar la font de veritat i regenerar-ne el que es pugui (un esquema des de la base de dades, no des d’un PDF).
2. Separar regles, material de consulta i límits. Les regles van al SKILL.md amb la seva conseqüència; el material, a references.
3. Etiquetar cada reference amb el seu grau de confiança i fixar quina font guanya quan discrepen.
4. Generar els índexs que l’agent necessita per buscar, encara que no aportin informació nova.
5. Marcar el que no se sap i separar el que diu el fabricant del que decideix l’equip.
6. Buscar restes de l’origen (rutes, noms de projecte, «this custom GPT») també als fitxers de dades, no només a les instruccions.
7. Escriure la descripció al final, a partir de les peticions reals, no del títol del tema.

Com s’empaqueten després aquestes skills al costat de comandes i hooks és a l’article sobre plugins de Claude Code, i el mapa general, a la guia d’agent skills.

La pregunta que continua oberta

Destil·lar una skill la separa de la seva font, i la font continua canviant. L’esquema d’Illuminate canviarà amb les versions del producte, i la skill només serà fiable mentre la seva exportació coincideixi amb la base de dades real. L’índex de camps i el CSV de relacions depenen d’aquest mateix esquema, així que qualsevol regeneració ha d’arrossegar els tres fitxers.

Per a un esquema, la resposta sembla clara: automatitzar l’exportació i regenerar els fitxers derivats a cada canvi. Per a una convenció d’equip o una operativa de desplegament no hi ha exportació possible, i no tinc clar què hauria de disparar la revisió. El que sí que sé és que una skill destil·lada sense ningú que la mantingui acaba sent exactament la documentació morta que es volia evitar, amb l’agreujant que l’agent la segueix al peu de la lletra.