El teu equip té llicències de Claude Code, Cursor o Copilot. Cada developer ha trobat els seus propis trucs: prompts que funcionen, instruccions que donen bons resultats, formes de demanar code reviews que produeixen feedback útil. El problema és que aquest coneixement viu al cap de cada persona. Quan algú se'n va, s'emporta els seus prompts. Quan algú nou entra, comença de zero.
Els Skills resolen exactament això. Són el mecanisme estàndard per empaquetar instruccions, scripts i coneixement en unitats reutilitzables que qualsevol agent d'IA pot descobrir i executar. No és un concepte teòric: l'equip de Claude Code a Anthropic té centenars de Skills en ús actiu, i els descriu com el punt d'extensió més utilitzat de l'eina.
Però la seva flexibilitat és també el seu risc. Un Skill mal escrit consumeix tokens sense aportar valor, confon l'agent o, pitjor, produeix resultats inconsistents que el developer accepta sense revisar. Aquesta guia condensa les lliçons publicades per Anthropic, els patrons que funcionen en equips reals i els errors que hem vist en 12 transformacions.
Què és un Skill i per què importa
Un Skill és un fitxer SKILL.md amb instruccions que un agent d'IA carrega quan són rellevants. La idea és simple: en lloc de repetir la mateixa instrucció cada vegada que necessites alguna cosa, l'escrius una vegada, l'empaquetes i deixes que l'agent la descobreixi automàticament o la invoqui sota demanda amb /nom-del-skill.
Però un Skill és més que un fitxer de text. És un directori que pot contenir:
- SKILL.md (obligatori): les instruccions principals amb metadades YAML.
- Fitxers de referència: documentació detallada que l'agent carrega només quan la necessita.
- Scripts executables: codi que l'agent executa directament, sense haver-lo de generar.
- Templates: plantilles que l'agent omple segons el context.
- Exemples: parells entrada/sortida que mostren el format esperat.
L'estructura típica d'un Skill amb complexitat mitjana:
el-meu-skill/
├── SKILL.md # Instruccions principals (obligatori)
├── reference.md # Documentacio detallada (carrega sota demanda)
├── examples.md # Exemples d'us
├── templates/
│ └── template.md # Plantilla per omplir
└── scripts/
└── validate.sh # Script que l'agent executaAnatomia d'un SKILL.md efectiu
Tot SKILL.md té dues parts: un frontmatter YAML amb metadades i un cos markdown amb instruccions.
El frontmatter: metadades que guien l'agent
El frontmatter defineix quan i com es fa servir el Skill. Els camps clau:
| Camp | Funció | Clau |
|---|---|---|
| name | Nom del Skill. Es converteix en /nom. | Només minúscules, números i guions. |
| description | Què fa i quan fer-lo servir. L'agent ho fa servir per decidir si activar-lo. | Sempre en tercera persona. Específic. |
| disable-model-invocation | Si és true, només l'usuari pot invocar-lo. | Fer servir per a deploy, enviaments, accions destructives. |
| allowed-tools | Eines que l'agent pot fer servir sense demanar permís. | Controla l'abast del Skill. |
| context | Si és fork, el Skill s'executa en un subagent aïllat. | Ideal per a tasques que no han de contaminar el context principal. |
El cos: dos tipus de contingut
Segons Anthropic, pensar en quin tipus de contingut conté el teu Skill ajuda a decidir com estructurar-lo:
Contingut de referència
Afegeix coneixement que l'agent aplica al teu treball actual: convencions, patrons, guies d'estil, coneixement de domini.
S'executa: inline, juntament amb la teva conversa.
Exemple: convencions d'API, regles de nomenclatura, patrons del projecte.
Contingut de tasca
Instruccions pas a pas per a una acció concreta: deploys, commits, generació de codi, migracions.
S'executa: normalment invocat amb /nom.
Exemple: skill de deploy, skill de migració de base de dades.
Lliçons de l'equip de Claude Code
Thariq Shihipar, de l'equip d'Anthropic, va publicar una sèrie d'articles sobre les lliçons apreses construint Claude Code. A "How We Use Skills", comparteix el que han descobert gestionant centenars de Skills internament. Aquestes són les lliçons que més impacte tenen:
1. La secció de "Gotchas" és el contingut de més valor
Els millors Skills van començar com unes poques línies i un avís sobre alguna cosa que podia fallar. Aquest avís — el gotcha — és el que marca la diferència. És informació que l'agent no pot deduir del codi: un edge case subtil, un comportament inesperat d'una API, una convenció no documentada.
A la pràctica: Cada vegada que un agent comet un error fent servir el teu Skill, afegeix un gotcha. Els Skills més útils d'Anthropic han acumulat gotchas durant mesos. No van néixer perfectes. Van evolucionar amb l'ús.
2. No repeteixis el que l'agent ja sap
Claude (i altres models avançats) sap molt sobre programació, frameworks i patrons comuns. Explicar què és un PDF o com funciona una llibreria popular és gastar tokens sense aportar valor.
La regla d'Anthropic: si estàs publicant un Skill que és principalment coneixement, centra't en informació que empenyi l'agent fora de la seva forma habitual de pensar. Les excepcions, els edge cases, les decisions del teu equip que són diferents del patró per defecte.
3. Dona informació, no restriccions excessives
L'agent intentarà seguir les teves instruccions al peu de la lletra. Si ets massa específic, perds la capacitat de l'agent d'adaptar-se al context real. Si ets massa vague, no aportes valor.
L'equilibri depèn del risc:
Migracions de BD, deploys, accions destructives. Script exacte, sense variacions.
Generació de codi, configuració. Pseudocodi o template amb paràmetres.
Code reviews, anàlisi, recerca. Guia general, confia en el criteri de l'agent.
4. El sistema de fitxers és progressive disclosure
No tota la informació s'ha de carregar sempre. Els Skills d'Anthropic fan servir el sistema de fitxers com a mecanisme de progressive disclosure: el SKILL.md conté l'essencial i apunta a fitxers de referència que l'agent carrega només quan els necessita.
Això no és una optimització menor. La finestra de context és un recurs compartit. El teu Skill competeix amb l'historial de conversa, altres Skills, el system prompt i la sol·licitud actual de l'usuari. Cada token compta.
5. Desenvolupa Skills de manera iterativa amb el mateix agent
El procés més efectiu que fa servir Anthropic internament segueix un patró amb dues instàncies:
- Claude A (l'expert): t'ajuda a crear i refinar el Skill.
- Claude B (l'usuari): fa servir el Skill en tasques reals i revela els buits.
El cicle: completa una tasca sense Skill → identifica quin context vas haver de donar manualment → demana a Claude A que ho empaqueti com a Skill → prova amb Claude B → observa on falla → torna a Claude A per refinar.
Aquest cicle és exactament el que en la nostra metodologia Spec-Driven Development anomenem iteració sobre especificacions: el coneixement es codifica, es testeja i es millora contínuament.
5 patrons que funcionen
Aquests patrons apareixen recurrentment en els Skills més efectius, tant interns d'Anthropic com en equips que hem transformat:
1. Patró Template
Proporciones una plantilla que l'agent omple. Útil quan necessites un format de sortida consistent: commit messages, reports, documentació tècnica. El grau de rigidesa depèn del cas: estricte per a formats d'API, flexible per a anàlisi.
2. Patró Examples (entrada/sortida)
Parells d'exemple que mostren el format esperat. Més efectiu que descriure el format amb paraules. L'agent entén l'estil i el nivell de detall que esperes veient exemples concrets, no llegint regles abstractes.
3. Patró Workflow amb checklist
Per a operacions complexes de múltiples passos, proporciona un checklist que l'agent copia i marca a mesura que avança. Això evita que se salti passos crítics, especialment en processos de validació.
## Workflow de deploy
Copia aquest checklist i marca el progres:
- [ ] Pas 1: Executar suite de tests
- [ ] Pas 2: Build de l'aplicacio
- [ ] Pas 3: Push al target de deploy
- [ ] Pas 4: Verificar que el deploy va ser exitos
- [ ] Pas 5: Smoke test en produccio4. Patró Config
Emmagatzemes configuració en un config.json dins del directori del Skill. Si no existeix, l'agent demana les dades a l'usuari. Això permet que el mateix Skill funcioni en diferents entorns sense modificar les instruccions.
5. Patró d'injecció dinàmica
Skills que executen comandes shell abans d'enviar el contingut a l'agent. La sintaxi !`comanda` executa la comanda i reemplaça el placeholder amb el resultat. L'agent rep dades reals, no la comanda.
Exemple pràctic: un Skill de code review que executa !`git diff` per injectar els canvis reals al prompt abans que l'agent els analitzi.
Anti-patrons que destrueixen Skills
Aquests errors són tan comuns com perjudicials. Els hem vist repetidament:
Skill massa verbós
Explicar què és un PDF, com funcionen els decoradors de Python o què fa git commit. L'agent ho sap. Cada paràgraf innecessari és context que desplaça informació útil. La regla: si pots assumir que l'agent ho sap, no ho incloguis.
Massa opcions
"Pots fer servir pypdf, pdfplumber, PyMuPDF o pdf2image..." Això no ajuda, paralitza. Proporciona un default clar i una alternativa per al cas excepcional. Res més.
Referències niuades
SKILL.md apunta a advanced.md, que apunta a details.md, que conté la informació real. L'agent pot llegir parcialment fitxers referenciats des d'altres fitxers referenciats. Mantén les referències a un sol nivell de profunditat.
Informació que caduca
"Si estàs fent això abans d'agost de 2025, fes servir l'API v1." Això es converteix en desinformació tan bon punt passa la data. Fes servir seccions de "patró legacy" amb detalls col·lapsables si necessites context històric.
Terminologia inconsistent
Barrejar "API endpoint", "URL", "ruta" i "path" per referir-se al mateix. L'agent no sap que són sinònims al teu context. Tria un terme, fes-lo servir sempre.
El cost real: Un Skill mal escrit no és innocu. Consumeix tokens de la finestra de context, redueix la qualitat de resposta de l'agent en altres tasques i, si produeix resultats subtilment incorrectes, genera deute tècnic que passa desapercebut fins que és tard.
Skills en equip: de l'individual a l'organitzacional
La potència real dels Skills apareix quan deixen de ser eines individuals i es converteixen en coneixement compartit de l'equip. Hi ha quatre nivells de distribució:
A ~/.claude/skills/. Disponible en tots els teus projectes. Les teves pròpies convencions i workflows.
A .claude/skills/ del repositori. Es commiteja amb el codi. Tot l'equip del projecte l'hereta automàticament.
Desplegat organitzacionalment a través de managed settings. Tots els usuaris de l'empresa el tenen disponible.
L'equip d'Anthropic descriu com han creat un marketplace intern de plugins on els Skills que guanyen tracció orgànicament són promoguts al marketplace oficial via PR. No hi ha un equip centralitzat decidint quins Skills fer servir: l'adopció és bottom-up.
Aquest model reflecteix el que veiem als equips més efectius: el coneixement no s'imposa top-down. Es descobreix, es valida i s'escala.
Skills i Spec-Driven Development: dues cares de la mateixa moneda
Si has llegit els nostres insights sobre context engineering i Spec-Driven Development, veuràs que els Skills són la implementació pràctica d'ambdós conceptes:
- Context engineering defineix la disciplina de dissenyar i gestionar el context d'IA. Els Skills són el seu mecanisme d'empaquetat i distribució.
- SDD estableix que el treball amb IA ha de partir d'especificacions estructurades. Un Skill és una especificació: defineix què ha de fer l'agent, amb quines eines, seguint quin patró, i quins errors evitar.
En la nostra metodologia, els Skills formen part de la Constitució del projecte: el conjunt de regles i coneixement que la IA ha de respectar. Juntament amb els templates d'especificació, els playbooks de prompts i els checklists de code review, els Skills completen el sistema que fa que la IA produeixi resultats consistents i alineats amb els estàndards de l'equip.
Com començar: checklist per al teu primer Skill
No necessites crear un sistema complet des del primer dia. Comença amb un Skill, mesura l'impacte i escala. Aquest és el camí:
- Identifica una tasca repetitiva. Alguna cosa que el teu equip explica a la IA més de tres vegades per setmana. Commit messages, code reviews, migracions de components, configuració de tests.
- Completa la tasca amb l'agent sense Skill. Observa quin context has de proporcionar manualment. Apunta les correccions que fas.
- Crea el Skill mínim. Només el SKILL.md amb frontmatter bàsic i les instruccions essencials. Sense fitxers extra. Sense scripts.
- Testeja amb un cas real. No amb un exemple inventat. Observa on l'agent falla o encerta.
- Afegeix gotchas. Cada error de l'agent és un gotcha potencial. Afegeix-lo al Skill.
- Commiteja al repositori. Posa'l a
.claude/skills/perquè tot l'equip l'hereti. - Itera. El Skill millorarà amb cada ús real. No intentis que sigui perfecte al principi.
---
name: code-review
description: Revisa codi seguint les convencions del
projecte. Fes servir quan l'usuari demana una review o abans
de commitejar canvis.
---
En revisar codi, segueix aquests passos:
1. Verifica que compleix les convencions a CONVENTIONS.md
2. Busca possibles bugs o edge cases no coberts
3. Suggereix millores de llegibilitat nomes si son significatives
4. Marca com a "gotcha" qualsevol patro que pugui ser confus
## Gotchas d'aquest projecte
- Els hooks de React han de seguir el patro useXxxQuery
(no useGetXxx)
- Mai fer servir any en tipus de resposta d'API
- Els tests d'integracio requereixen el flag --run-dbEl futur: Skills com a avantatge competitiu
Estem en un moment d'inflexió. La IA generativa ja no es diferencia pel model: tots els equips tenen accés als mateixos LLM. La diferenciació està en com configures i dirigeixes aquesta IA.
Els equips que tractin els Skills com un actiu d'enginyeria — versionat, testejat, distribuït, millorat contínuament — tindran un avantatge compost. Cada Skill que funciona redueix fricció per a tot l'equip. Cada gotcha afegit evita un error que hauria costat hores de debug. Cada patró compartit elimina variabilitat en la qualitat de l'output.
La pregunta no és si el teu equip necessita Skills. És quant temps et pots permetre continuar sense ells.
Lectura complementària: Context Engineering: la disciplina que satisfà equips amb IA | Instruccions compartides i curades per a equips | Spec-Driven Development
Metodologia: A onext implementem Skills, context engineering i SDD com a part dels nostres Centres d'Excel·lència d'IA. 12 equips transformats, 0 sprints perduts.
Preguntes freqüents
Què és un Skill per a un agent d'IA?
Un Skill és un directori amb un fitxer SKILL.md que conté instruccions que l'agent carrega quan són rellevants. A més del fitxer principal pot incloure documentació de referència, scripts executables, plantilles i exemples d'entrada/sortida. Segueix l'estàndard obert Agent Skills.
En què es diferencia un Skill d'un prompt desat?
Un prompt es repeteix cada vegada que el necessites; un Skill s'escriu una vegada, s'empaqueta i l'agent el descobreix automàticament o s'invoca sota demanda. A diferència d'un prompt, pot portar scripts, plantilles i documentació que l'agent carrega només quan li calen.
Què ha d'incloure un SKILL.md?
Metadades YAML al frontmatter, que indiquen a l'agent quan carregar-lo, i un cos amb les instruccions. La part de més valor sol ser la secció de gotchas: allò que surt malament i no és evident per a qui no hi ha passat.
Per què fallen els Skills?
Per quatre antipatrons habituals: ser massa verbós —explicar el que l'agent ja sap desplaça context útil—, oferir massa opcions en comptes d'un default clar, encadenar referències niades a més d'un nivell de profunditat, i incloure informació que caduca.
Com comença un equip a crear els seus Skills?
De manera iterativa i amb el mateix agent: s'escriu una versió mínima, es prova en tasques reals i es corregeix amb el que falla. L'objectiu és treure el coneixement del cap de cada persona i deixar-lo on tot l'equip el pugui fer servir.
Jordi García és Tech Lead a onext. Treballa a portar la IA a producció governada en equips de desenvolupament i de producte —amb Spec-Driven Development, enginyeria de context i verificació humana a cada pas— i signa els insights tècnics d'onext sobre mètode, qualitat i cost de la IA aplicada.
LinkedIn →