Acasă/Metode

AI · Skill-uri pentru agenți

Cum transformăm munca repetată în skill-uri pentru agenți AI

Un skill de agent este un folder cu un fișier SKILL.md care îi spune unui agent AI de programare când și cum să facă o anumită sarcină recurentă, plus scriptul de care are nevoie sarcina. Extindem un skill existent înainte să creăm unul nou, orice scriere rulează implicit în gol, iar regulile care trebuie respectate stau în afara promptului: în hook-uri, în roluri de bază de date doar-citire și într-o bază de cunoștințe comună.

Actualizat 2026-10-11

Ce este un skill de agent

Un skill de agent AI este un folder care conține un fișier SKILL.md: un bloc scurt de frontmatter cu name și description, urmat de instrucțiunile pe care un agent AI de programare, de exemplu Claude Code, le urmează pentru o anumită sarcină recurentă. Dacă sarcina cere o operație deterministă, cum ar fi o interogare de bază de date sau un apel de API, folderul conține și scriptul care o face. Agentul citește descrierea ca să decidă când se aplică skill-ul, deci descrierea face rutarea.

Ținem un catalog comun de skill-uri, așa că ce scrie un om ajunge la toți agenții, pe toate mașinile. Catalogul a crescut la circa 230 de skill-uri, până când o trecere de consolidare l-a adus la circa 216. Cifra nu e o țintă. Un catalog e util în măsura în care agentul găsește sigur skill-ul potrivit, iar fiecare aproape-duplicat îi îngreunează căutarea.

Semnalul pentru un skill nou e repetiția. Un tipar văzut în cel puțin trei cazuri sau o reparație pe care altfel am reface-o de mână mâine devine skill sau regulă în cod. Cazul unic rămâne pe o listă pentru om, împreună cu decizia pe care o are de luat.

Pasul 1: extinde înainte să creezi

Primul pas când faci un skill de agent e să verifici dacă există deja. Comparăm numele și descrierea propuse cu catalogul și ne uităm la cele mai apropiate skill-uri. Când datele și publicul se suprapun, adăugăm un mod sau o subcomandă la skill-ul existent. Patru generatoare de articole, câte unul pe site, au devenit un singur generator cu parametru de site. Mai multe skill-uri de publicitate au devenit o singură suită.

Aceeași regulă ține și în cod. Un audit al catalogului a găsit o mică funcție de curățare a șirului de conexiune copiată în circa 40 de fișiere, fiecare copie putând s-o ia razna separat. Acum skill-urile importă un singur modul comun pentru conexiuni și secrete și citesc tabele precalculate, în loc să refacă agregări grele la fiecare rulare.

Pasul 2: SKILL.md scris pentru router

Frontmatter-ul din SKILL.md cere două câmpuri, name și description, plus un indiciu opțional de argumente. Descrierea spune ce face skill-ul, apoi când se folosește, apoi frazele pe care un om chiar le-ar scrie. Corpul are o formă fixă: când se folosește, pașii exacți și note cu excepții, surse de date și skill-uri înrudite.

Preferăm un skill de cunoaștere, adică doar instrucțiuni, cu excepția cazului în care sarcina trebuie să ruleze cod determinist. Un script e încă un lucru de testat, de instalat și de ținut în pas cu textul.

Contează și unde stă catalogul. La început listam toate skill-urile, cu descriere, în instrucțiunile care se încarcă la fiecare tură. Fișierul ajunsese la 30,8 KB. Rutarea reală se face printr-o căutare semantică peste descrierile complete, păstrate în baza de date, așa că lista încărcată mereu a fost scurtată la descrieri de cel mult 10 cuvinte: 17,4 KB, cu 44% mai puțin, pentru fiecare agent, la fiecare tură.

Pasul 3: scripturi care rulează oriunde și nu scriu nimic implicit

Un script de skill își declară dependențele în fișier, în formatul definit de PEP 723, și se rulează cu uv run. Nu se urcă niciun mediu virtual, deci scriptul merge pe orice mașină care are uv. Secretele se citesc întâi din mediu, apoi dintr-un depozit comun de secrete, și nu se afișează niciodată. Scripturile care scriu în consola Windows forțează ieșirea UTF-8, altfel diacriticele românești le opresc.

Orice scriere rulează implicit în gol. Scriptul afișează ce ar schimba, cu SELECT-ul corespunzător și numărul de rânduri, și nu atinge nimic până nu e chemat din nou cu --apply. Când un skill e expus ca acțiune executabilă, vine în pereche: o acțiune de previzualizare, permisă, și una de aplicare, care cere confirmare. Acțiunile executabile primesc doar parametri dintr-o listă albă, niciodată SQL liber sau o cale de fișier.

Pasul 4: regulile tari stau în afara promptului

O regulă pe care un agent AI nu are voie s-o încalce trebuie pusă într-un mecanism, nu într-o propoziție. Contextul unui agent e promptul lui. Am spus odată unui om că agentul nu va copia material dintr-o bază de date publicată, apoi am scris promptul agentului fără interdicția asta. Agentul a făcut exact acel lucru. O regulă enunțată oriunde altundeva decât în instrucțiunile agentului nu există pentru agent.

Așa că regulile tari stau în trei locuri. Accesul la baze de date trece prin servere MCP (Model Context Protocol, interfața prin care agentul cheamă unelte) care rulează fiecare interogare într-o tranzacție READ ONLY. Un hook PreToolUse, adică un script chemat înaintea fiecărei folosiri de unealtă, blochează direct comenzile catastrofale și cere confirmare pentru SQL distructiv sau git push; echipa poate adăuga tipare noi, valabile pentru toți de la sesiunea următoare. O altă pereche de hook-uri trece folosirea skill-urilor și a bazelor de date în baza de cunoștințe comună după fiecare tură, ca evidența activității să nu depindă de memoria cuiva.

O gardă care se uită la textul comenzii e grosolană. A noastră a refuzat o căutare nevinovată doar pentru că pomenea numele unui utilitar de export al bazei. O tratăm ca pe o alegere deliberată și citim schema din information_schema, în loc să ne certăm cu garda.

Pasul 5: o memorie cu care următorul agent poate judeca

Baza de cunoștințe comună ține ce le trebuie tuturor agenților: secretele, care nu stau nicăieri altundeva, jurnalul de activitate, registrul de fișiere, legăturile de referință și registrul de skill-uri. Memoria personală e un folder cu fișiere Markdown mici, câte un fapt pe fișier, fiecare cu regula, o linie Why: și o linie How to apply:. Linia „de ce” îi permite unui agent de mai târziu să judece un caz-limită, în loc să aplice regula orbește. Indexul are o linie pe notă, fiindcă se citește cu o limită de circa 17 KB.

Lecțiile reutilizabile trec din memoria personală în depozitul echipei, după ce căutăm dacă nu există deja. Un fapt care se schimbă se marchează drept învechit, nu se șterge. Legăturile între note trec printr-o poartă: în testul nostru, legarea doar după similaritatea vectorială a dat un F1 de 24,9%, față de 23,9% pentru legături la întâmplare, și 31,6% cu o poartă care aprobă doar relații specifice.

Auditul de consolidare: întâi contradicțiile

Un audit de consolidare a skill-urilor trimite în paralel agenți doar-citire, câte unul pe un grup de skill-uri, și îi cere fiecăruia suprapunerile și, explicit, contradicțiile. Contradicțiile se repară primele, pentru că produc cifre greșite. Am găsit ROAS-ul de prag definit ca 1 / marjă într-un skill și ca 1 / (marjă × rata de livrare) în altul, pentru magazinele cu plata la livrare, un prag de oboseală a reclamelor de 10% într-un loc și de 20% în altul și patru definiții ale costului mărfii.

Duplicatele pure se șterg după ce trimiterile spre ele sunt redirecționate. Mai multe skill-uri cu scripturi se unesc într-unul singur cu un dispecer subțire, fără rescrierea scripturilor testate, iar fiecare mod se încearcă pe date reale înainte să plece originalele. Un skill cu script unic nu se șterge niciodată. O ștergere trebuie să ajungă în trei locuri: depozitul de cod, baza de date a catalogului și serverul de skill-uri. Serverul n-are operație de ștergere, așa că vechiul nume se republică drept piatră funerară care trimite la înlocuitor.

Unde am greșit

Hook-urile erau oprite. Pe o mașină, o setare dezactiva toate hook-urile, deci nici garda, nici jurnalul pe care instrucțiunile noastre le numeau „garantate” nu rulau. Le-am repornit după ce am verificat garda: un echo nevinovat a trecut, o ștergere recursivă a rădăcinii a fost refuzată. Documentația mai spune că un refuz din PreToolUse e ignorat în modul care ocolește permisiunile. N-am verificat asta noi, așa că pentru agenții nesupravegheați apărarea stă la nivelul sistemului de operare.

Erorile nu erau skill-uri stricate. Din 182 de erori de skill înregistrate, 91 veneau dintr-o singură căutare care raporta un 404 drept eșec, când „nu există” era chiar răspunsul. Cea mai des întâlnită cauză a unei aparente căderi era un secret opțional declarat ca obligatoriu: 57 de cazuri în 32 de skill-uri, iar 31 au fost scoase din 15 manifeste. Serverul mai întorcea un 500 gol la greșeli de apelare; acum întoarce 400, 403 sau 503 cu motivul, verificat pe 5 căi. Un audit static al manifestelor a găsit 104 nepotriviri în 37 de skill-uri, o parte fals-pozitive, fiindcă auditul nu înțelege subcomenzile.

Reparații care n-au rulat niciodată. Codul care nu se execută arată identic cu codul care rulează și nu găsește nimic. Înainte să schimbăm o regulă cerem acum două numere: de câte ori a rulat și pe câte cazuri a produs un rezultat. O regulă de adresă rezolva 0 din 2.258 de comenzi respinse înainte de o corectură de un caracter și 47 după.

Limite și listă de verificare

Nimic din toate astea nu face un agent corect. Skill-urile fac repetabilă practica bună, dar fac repetabile și greșelile. O rulare în gol arată ce s-ar schimba, nu și dacă ar trebui. Hook-urile protejează doar mașinile pe care rulează și doar în modurile care le respectă.

Lista. Caută în catalog și extinde unde se poate. Scrie o descriere cu fraze reale de declanșare. Declară dependențele în fișier și rulează cu uv. Rulare în gol implicit, aplicare la cerere. Acces doar-citire la baze. Regulile tari în hook-uri, nu în text. O linie „de ce” la fiecare notă de memorie. După publicare, compară scripturile pomenite în SKILL.md cu fișierele chiar urcate. Caută contradicțiile înaintea duplicatelor.

Întrebări și răspunsuri

Ce este un fișier SKILL.md în Claude Code?

Fișierul SKILL.md este miezul unui skill de agent. Începe cu un frontmatter care conține un nume și o descriere, urmat de instrucțiunile pentru o sarcină recurentă. Agentul citește descrierea ca să decidă când se aplică skill-ul, deci descrierea trebuie să spună ce face skill-ul, când se folosește și frazele pe care un om chiar le-ar scrie. Scripturile necesare stau în același folder.

Când creez un skill nou pentru agent și când extind unul existent?

Un skill nou se justifică doar când niciun skill existent nu acoperă aceleași date și același public. Caută întâi în catalog după nume și descriere. Dacă există unul apropiat, adaugă-i un mod sau o subcomandă. Noi scriem un skill când un tipar se repetă în cel puțin trei cazuri; cazul unic rămâne pe o listă pentru om.

Cum împiedic un agent AI să ruleze comenzi distructive?

Pune regula într-un mecanism, nu în prompt. Un hook PreToolUse poate bloca direct comenzile catastrofale și poate cere confirmare pentru SQL distructiv sau git push. Uneltele de bază de date pot rula fiecare interogare într-o tranzacție doar-citire. Verifică dacă hook-urile chiar sunt pornite pe fiecare mașină și nu te baza pe ele pentru agenți nesupravegheați în modul care ocolește permisiunile.

Cum își gestionează dependențele scripturile unui skill?

Dependențele se declară în fișier, în formatul PEP 723, iar scriptul se rulează cu uv run. Așa nu trebuie urcat niciun mediu virtual și scriptul merge pe orice mașină cu uv. Secretele se citesc din mediu și nu se afișează niciodată, iar dacă scriptul poate rula într-o consolă Windows, ieșirea se forțează pe UTF-8.

Ce este un audit de consolidare a skill-urilor?

Un audit de consolidare verifică un catalog de skill-uri pentru suprapuneri și contradicții, de obicei cu câte un agent doar-citire pe fiecare grup de skill-uri. Contradicțiile se repară primele, fiindcă două skill-uri care definesc diferit aceeași metrică produc cifre greșite. Apoi se șterg duplicatele pure și se unesc skill-urile înrudite în spatele unui dispecer subțire, cu fiecare mod testat pe date reale.

Toate metodele