Com crear una skill que funcioni: descripció, SKILL.md i references

Aquestes dues descripcions podrien pertànyer a la mateixa skill:

# Versió A (exemple inventat)
description: Ajuda amb consultes SQL d'Illuminate.

# Versió B (la descripció 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 és la que escriu gairebé tothom la primera vegada, i no té res d’incorrecte. El que no dona a l’agent és un motiu per carregar la skill quan algú enganxa una consulta amb CDM_LMS.COURSE_ACTIVITY i pregunta per què retorna el doble de files, que és just el moment en què la skill té alguna cosa a aportar. La B diu quines tasques cobreix (crear, validar, explicar, depurar, millorar), amb quin material treballa i en quins esquemes s’aplica, pel seu nom exacte.

Aquest article recorre l’anatomia d’una skill a partir d’aquesta diferència, amb illuminate-sql-support com a fil conductor: una skill que hem desenvolupat a eLearning Media i que genera i revisa SQL de Snowflake per a Blackboard Data / Illuminate, el magatzem de dades analítiques d’aquest LMS. La reconstrueixo com un exemple que evoluciona: les etapes intermèdies són il·lustratives i els fragments finals són literals de la skill.

Encara no es pot instal·lar: ChatGPT no admet skills noves en aquest moment. Quan ho permeti, o quan estigui publicada en un repositori, afegirem com instal·lar-la a Consultas SQL para Blackboard (web en castellà).

Si encara no tens clara la diferència entre una skill i un servidor MCP, comença per MCP vs Skills; per al mapa complet del tema, la guia d’agent skills en un equip de desenvolupament.

Què veu l’agent abans de decidir

Una skill és una carpeta amb un SKILL.md i, opcionalment, més fitxers. El SKILL.md comença amb un frontmatter YAML amb dos camps obligatoris, name i description, i continua amb instruccions en Markdown. Fins aquí arriben gairebé tots els tutorials.

El que de debò condiciona com s’ha d’escriure és la manera com es carrega. L’agent no llegeix totes les skills disponibles a cada conversa. En arrencar, només té en context el nom i la descripció de cadascuna. Quan decideix que una encaixa amb la tasca, carrega el cos del SKILL.md. I només llegeix un altre fitxer de la carpeta si aquest cos li diu que l’obri. L’estàndard obert d’Agent Skills en diu càrrega progressiva.

D’aquí surten les decisions de disseny d’aquest article. La descripció és l’única cosa que existeix per a l’agent mentre no activi la skill, així que la seva feina és provocar l’activació en el moment correcte. El cos del SKILL.md es carrega sencer cada vegada que es fa servir la skill, així que ha de contenir el que s’aplica a qualsevol tasca del seu àmbit i poca cosa més. I els fitxers de suport gairebé no costen res fins que es llegeixen, així que poden ser enormes sempre que el cos sàpiga adreçar-hi l’agent.

En la skill d’Illuminate això es nota en les proporcions. El SKILL.md té 95 línies. Les references en sumen unes 5.200: l’estructura completa de la base de dades (1.595 línies), un CSV de relacions candidates entre taules (1.499), un índex pla de camps vàlids (998), exemples de SQL (475) i notes de domini sobre tipus d’eina i dades semiestructurades (588). Carregar tot això a cada pregunta seria absurd; no carregar-ne res obligaria el model a inventar noms de columnes.

Primera versió: tot en un fitxer

Suposem que algú decideix convertir el seu coneixement d’Illuminate en una skill. La primera versió acostuma a assemblar-se a això (exemple il·lustratiu):

---
name: illuminate
description: Ajuda amb consultes SQL d'Illuminate.
---

# Illuminate

Ets un expert en Illuminate. Aquestes són les taules disponibles:

CDM_LMS.COURSE: ID, NAME, COURSE_NUMBER, ...
CDM_LMS.PERSON: ID, FIRST_NAME, LAST_NAME, ...
(centenars de línies amb taules, columnes i algunes consultes d'exemple)

Té dos defectes que es reforcen entre si. La descripció competeix amb qualsevol altra cosa que parli de SQL: una altra skill de bases de dades, un servidor MCP connectat a Snowflake o el coneixement general del model, que es pensa que sap com és el model de dades d’un LMS. Res no hi indica quins esquemes cobreix ni quin tipus de preguntes resol. I si finalment s’activa, posa en context centenars de línies encara que la pregunta sigui només com es diu la columna de la data d’un esdeveniment.

El name també importa, tot i que menys. L’estàndard exigeix que coincideixi amb el nom de la carpeta, i convé que sigui específic: illuminate deixa de servir així que apareix una segona skill sobre el mateix producte amb un altre propòsit. illuminate-sql-support diu què fa.

Segona versió: una descripció escrita per activar-se

La descripció real té dues parts. La primera frase diu què fa la skill i enumera verbs que corresponen a peticions diferents: crear una consulta des de zero, validar-ne una d’existent, explicar què fa, depurar un error, millorar-la. Cada verb és una manera diferent com algú pot demanar ajuda, i una descripció que només digués «genera SQL» no s’activaria amb «per què falla aquesta query?».

La segona part, «Use for Illuminate reporting questions and SQL involving the supported … schemas», acota l’àmbit amb identificadors exactes. Els noms d’esquema (CDM_LMS, CDM_TLM…) són el millor senyal d’activació que té aquesta skill, perquè apareixen literalment en el SQL que la gent enganxa al xat. Un identificador concret és molt més fiable que una descripció temàtica.

Si comparo aquesta descripció amb les del plugin intern del meu equip, els triggers cauen en unes poques famílies: les paraules amb què es demanen les coses, els identificadors del domini (noms d’esquema, de classe o de fitxer), els missatges d’error tal com apareixen i l’àmbit que separa la skill de les seves veïnes. Els missatges d’error tenen un pes especial en skills operatives, perquè qui enganxa un log no descriu la tasca, enganxa l’error.

La descripció d’Illuminate té una limitació que val la pena assenyalar. Està en anglès, igual que la resta de la skill, i la mateixa skill indica que respongui en l’idioma de l’usuari. Qui pregunti en català «quants alumnes van entrar al curs la setmana passada?», sense esmentar cap esquema, depèn que el model relacioni aquesta pregunta amb «Illuminate reporting questions». Afegir algunes formulacions en català o castellà a la descripció reduiria aquesta dependència.

Tercera versió: SKILL.md com a router

Un cop resolta l’activació, queda el cos. El patró que fem servir és tractar el SKILL.md com un router: un fitxer curt amb el propòsit, els límits, el flux de treball, les regles que no es poden saltar i una secció que diu quin fitxer s’ha d’obrir per a cada necessitat. En la skill d’Illuminate aquesta secció es diu «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 detalls d’aquest fragment valen per a qualsevol skill.

Cada línia comença amb un verb diferent segons el tipus de fitxer. «Search» per a l’índex de camps i el CSV, que es consulten buscant una cadena exacta; «Read the relevant table sections» per a l’estructura de la base de dades, que es llegeix per seccions; «Consult» per als exemples i les notes. Diu a l’agent com ha de fer servir cada fitxer, no només que existeix.

Hi ha un fitxer d’entrada obligatori. reference-guide.md té 45 línies i explica l’ordre de prioritat quan les fonts no coincideixen: l’estructura actual de la base de dades mana sobre l’índex de camps, aquest sobre les relacions i les relacions sobre els exemples. Aquesta jerarquia resol conflictes que l’agent trobaria tard o d’hora, perquè les fonts d’una skill real mai no són perfectament coherents.

Cada reference porta el seu grau de confiança. El CSV de relacions es presenta com a «candidats», amb una advertència explícita a la guia: que dues taules comparteixin una columna com PERSON_ID o COURSE_ID no prova que es puguin unir. Els exemples de SQL es fan servir «for intent and style, not object validation», perquè alguns estan incomplets o són anteriors a l’esquema actual. Sense aquestes etiquetes, l’agent tractaria un exemple antic amb la mateixa autoritat que l’esquema.

Aquest patró no és exclusiu d’una skill gran. Al plugin intern del meu equip també el fem servir en skills petites; el que canvia és la llargada de la llista.

Què va al SKILL.md i què a les references

El criteri és força simple. Al SKILL.md hi va el que s’aplica a qualsevol tasca de la skill i el que, si s’ignora, trenca alguna cosa. A les references hi va el que només cal per a una tasca concreta.

A Illuminate, el cos conté l’abast suportat, el flux de treball en set passos, les regles de SQL, l’avís de cost, una comprovació prèvia i el format de resposta. Els noms de taules i columnes, les relacions i els exemples són a fora. La línia que separa una cosa de l’altra és si l’agent la necessita per decidir què fer o només per fer-ho.

Quarta versió: regles, límits i verificació

Amb el router, la skill ja carrega el que necessita. El que la fa fiable és la resta del cos, i aquí la skill d’Illuminate té diverses decisions que val la pena copiar.

L’abast està tancat en totes dues direccions. Llista els set esquemes suportats i anomena els que exclou: «Do not generate, suggest, or reconstruct queries against LEARN, CDM_CRM, or CDM_SIS». Si es demana alguna cosa que no és a l’esquema empaquetat, la instrucció és dir que queda fora del model suportat, en lloc d’intentar-ho.

La regla contra la invenció és explícita i concreta: «Never invent schemas, tables, fields, payload keys, relationships, or enum meanings». I un pas del flux la reforça per al cas més temptador: «Never infer undocumented LMS objects from general product knowledge». Un model sap moltes coses sobre els LMS en general, i precisament per això tendeix a omplir buits amb noms plausibles que no existeixen.

El límit del que fa la skill està escrit al principi: no s’autentica, no es connecta a un tenant, no executa consultes i no pot provar que una consulta funcioni en un entorn concret. I una regla al final ho tanca: «Do not claim that SQL has been executed or validated against live tenant data». Sense aquesta frase, una resposta que digui «aquesta consulta és correcta» pot semblar una cosa comprovada quan només és una consulta ben escrita.

Hi ha un avís obligatori lligat a un risc real. Les consultes sobre CDM_TLM, les dades de telemetria, poden escanejar volums enormes i consumir crèdits d’Illuminate. La skill obliga a incloure un avís literal al costat de qualsevol consulta que toqui aquest esquema i a prioritzar filtres per EVENT_TIME. Quan una regla té un cost econòmic, no es deixa a criteri del model.

La verificació passa abans de respondre. La secció «Preflight before returning SQL» demana comprovar en silenci que tots els esquemes estan suportats, que totes les taules i columnes existeixen, que les taules van qualificades, que cada join té un camí documentat, que el gra del resultat coincideix amb el que s’ha demanat, que hi ha filtres o límits a les consultes d’alt volum i que l’avís de cost és on toca. És una checklist que l’agent aplica a la seva pròpia sortida, i la paraula «silently» evita que la resposta s’ompli de comprovacions narrades.

El format de resposta està fixat: supòsits materials, un bloc de SQL i notes sobre paràmetres, joins, gra i riscos. I una última regla protegeix el context de la conversa: «Do not reproduce the packaged reference files wholesale».

Quan una regla hauria de ser un script

La skill d’Illuminate no porta scripts. Tot el seu material són dades (Markdown, CSV i un TXT) que l’agent consulta amb cerques. Per validar que una columna existeix n’hi ha prou de buscar CDM_LMS.COURSE.COURSE_NUMBER a l’índex pla, i això un agent ho fa bé.

El límit apareix quan la comprovació és llarga i mecànica. Per exemple, un script que extragués d’una consulta totes les referències SCHEMA.TABLE.COLUMN i les comparés amb valid-fields.txt faria en mil·lisegons i sense errors el que el preflight demana al model que faci llegint. Amb una consulta de deu línies no surt a compte; amb una de dues-centes, probablement sí.

El criteri que aplicaria per posar un script en una skill és que la comprovació sigui determinista, que el material de referència sigui massa gran per llegir-lo amb atenció a cada ús i que el resultat serveixi també fora de l’agent (una persona el pot llançar, una pipeline també). Quan la comprovació s’ha d’executar sempre, i no només quan l’agent se’n recorda de cridar-la, el lloc ja no és la skill sinó un hook; ho explico a l’article sobre com organitzar skills, comandes i hooks en un plugin.

I de vegades la resposta no és ni skill ni script. Hem tingut moltes skills que semblaven bona idea al principi i que en realitat només afegien una capa de complexitat a processos de l’empresa que calia procedimentar o automatitzar, no empaquetar per a un agent. Aquest criteri el desenvolupo a quan no crear una skill.

Errors en estructurar una skill

Gairebé tots es dedueixen de com funciona la càrrega.

Duplicar contingut entre el SKILL.md i les references. Si una regla apareix resumida al cos i desenvolupada en un fitxer, les dues versions acabaran dient coses diferents. La skill d’Illuminate ho evita amb la guia de prioritats: quan dues fonts discrepen, està escrit quina guanya.

Deixar fitxers orfes. Una reference que el router no esmenta és invisible: l’agent no recorre la carpeta pel seu compte. Les cinc references d’Illuminate apareixen a «Route the references» i a la guia.

No marcar els límits amb altres skills o eines. Illuminate diu què no fa (connectar-se, executar) i quins esquemes no cobreix. En un plugin amb diverses skills, cadascuna hauria de dir a més què cobreix la del costat, perquè l’agent no intenti resoldre amb una el que està documentat en una altra.

Posar-hi credencials o dades internes. Una skill es carrega al context d’un model i es distribueix amb el plugin; tracta-la com a codi que pot acabar en qualsevol repositori. Si instal·les skills de tercers, el risc va en l’altra direcció, i el tracto a l’article sobre seguretat de skills de tercers.

Escriure per a la persona i no per a l’agent. Una skill no necessita introducció ni context històric; necessita l’ordre dels passos, les regles, els límits i què fer quan alguna cosa no es pot verificar. Quin coneixement mereix ser-hi ho vaig desenvolupar a skills com a documentació viva. D’on va sortir el coneixement d’aquesta skill (un Custom GPT previ) i com es destil·la, a l’article sobre destil·lar el coneixement de l’equip.

Fins on arriba una bona descripció

Tot l’anterior augmenta les probabilitats que la skill s’activi quan toca i que, un cop activa, l’agent llegeixi el que necessita i no s’inventi el que no troba. No ho garanteix. L’activació la decideix el model amb la informació que té a cada conversa, i pot canviar entre versions del model sense que ningú hagi tocat la skill. Fins i tot el preflight d’Illuminate és una instrucció, no una comprovació executada: el model se la pot saltar. L’única manera de saber si una skill l’encerta és provar-la amb peticions que l’haurien d’activar i amb d’altres que no, i comparar-ne les respostes amb ella i sense. Això ja és matèria d’evals de skills: sense elles, qualsevol millora de la descripció és una suposició que ningú no ha comprovat.