Skills pentru agenți de cod: când le folosești și ce pui în ele

Fișierul de instrucțiuni al proiectului a ajuns la 400 de linii. Conține convențiile echipei, dar și procedura de lansare în șapte pași, formatul raportului de incident și lista întrebărilor pentru revizuirea unei migrări. Toate sunt utile. Niciuna nu e utilă în fiecare sesiune — și totuși toate consumă context la fiecare pornire. Exact aici intervin skills: instrucțiuni care stau pe disc și se încarcă doar când sunt chemate.

Articolul e despre skills în contextul lucrului pe cod: ce sunt, unde stau, cum decide agentul să le folosească și — partea care contează cel mai mult în practică — ce pui într-un skill și ce rămâne în fișierul de instrucțiuni. Pentru partea de spațiu de lucru din interfața web, cu proiecte și memorie, există un ghid separat despre Claude Projects, memorie și Skills; aici discutăm strict depozitul de cod.

Ce este, de fapt, un skill

Documentația Claude Code îl descrie direct: skills extind ce poate face agentul, prin pachete de instrucțiuni, material de referință și unelte, grupate ca unități reutilizabile. „Creezi un fișier SKILL.md cu instrucțiuni, iar Claude îl adaugă în setul lui de unelte. Claude folosește skills când sunt relevante, sau îl invoci direct cu /nume-skill."

Structura e un director cu un singur fișier obligatoriu:

.claude/skills/nume-skill/
├── SKILL.md          (obligatoriu)
├── reference.md      (opțional)
└── scripts/
    └── helper.py

SKILL.md are două părți: un bloc de configurare în format YAML, între linii de ---, și conținutul propriu-zis în Markdown — instrucțiunile pe care agentul le urmează când skill-ul rulează.

Diferența esențială față de fișierul de instrucțiuni al proiectului e formulată explicit în documentație: spre deosebire de conținutul din CLAUDE.md, corpul unui skill se încarcă doar atunci când e folosit, așa că materialul de referință lung „nu costă aproape nimic până când ai nevoie de el".

Disciplina din spatele acestei decizii — ce ține în context permanent, ce încarci la cerere, cum eviți instrucțiunile contradictorii — e subiectul cursului Context Engineering și memorie pentru agenți AI.

Unde stau și cine le vede

Locul fișierului decide domeniul de aplicare:

Pentru monorepo, comportamentul e cel așteptat: se încarcă skills din directorul în care pornești sesiunea și din fiecare director părinte până la rădăcina depozitului, deci pornind în packages/frontend/ primești și skills-urile din rădăcină.

Un detaliu care produce confuzie la prima utilizare: comanda vine din numele directorului, nu din câmpul name din configurare. Directorul deploy produce comanda /deploy, indiferent ce scrie în frontmatter.

Cum decide agentul să folosească un skill

Trei semnale, în ordinea importanței:

Descrierea. Câmpul description e principalul mecanism prin care agentul decide dacă un skill e relevant. Documentația notează că textul combinat al descrierii și al câmpului opțional when_to_use e trunchiat la 1.536 de caractere — deci descrierea trebuie să fie precisă, nu poetică. Exemplul din documentație spune totul despre stil: „Rezumă modificările necomise și semnalează riscurile. Se folosește când întrebi ce s-a schimbat, când vrei un mesaj de commit sau când revizuiești o modificare."

Tiparele de fișiere. Câmpul paths restrânge încărcarea automată la anumite fișiere, de exemplu paths: "*.js,*.ts,*.vue". Skill-ul intră în context când agentul citește sau modifică fișiere care se potrivesc.

Invocarea explicită. Tastezi /nume-skill.

Poți controla cine are dreptul să invoce:

• disable-model-invocation: true — doar tu îl poți porni; agentul nu.
• user-invocable: false — doar agentul îl folosește; nu apare în meniul de comenzi.

Prima variantă e cea potrivită pentru proceduri cu efecte: o livrare, o migrare, o comandă care atinge un sistem extern. Nu vrei ca agentul să decidă singur că e momentul unei lansări.

Ce pui într-un skill și ce rămâne în instrucțiuni

Regula pe care o dă chiar documentația: creează un skill „când tot lipești aceleași instrucțiuni, o listă de verificare sau o procedură în mai mulți pași în conversație, sau când o secțiune din CLAUDE.md a devenit o procedură, nu un fapt".

Împărțirea care funcționează în practică:

În fișierul de instrucțiuni rămân faptele valabile în fiecare sesiune: comenzile de build și test, convențiile care diferă de implicit, structura proiectului, regulile permanente. Formatul și limitele acestui fișier sunt detaliate în ghidul despre AGENTS.md.

În skills intră procedurile și materialul de referință: cum se face o lansare, cum se scrie un raport de incident, lista de verificare pentru o migrare, ghidul de stil al API-ului public, întrebările dintr-o revizuire de securitate, formatul unui mesaj de commit pentru un tip anume de modificare.

În hooks și în verificările automate intră ce trebuie garantat: instrucțiunile rămân context, nu configurație impusă. Un skill care spune „rulează testele înainte de commit" e un ghidaj; o verificare care respinge livrarea fără teste e o regulă.

Recomandarea de dimensiune din documentație: SKILL.md sub 500 de linii, cu materialul detaliat mutat în fișiere separate, la care skill-ul face trimitere.

Încă un comportament util de știut: odată invocat, conținutul skill-ului rămâne în context în turele următoare, iar fișierul nu se recitește. Deci scrii instrucțiuni permanente, nu pași de unică folosință.

Cinci skills care se amortizează imediat

Pe proiecte reale, acestea sunt primele care merită scrise:

1. Pregătirea unei lansări. Pașii exacți, în ordine, cu verificările între ei. Marcat disable-model-invocation: true, ca să nu pornească singur.
2. Lista de verificare pentru migrări. Ce blocaje sunt acceptabile, ce se declară explicit, ce nu intră în aceeași livrare — subiectul e detaliat în ghidul despre migrări de schemă cu agenți.
3. Raportul de incident. Structura, întrebările la care trebuie să răspundă, tonul. Ai nevoie de el exact când ești obosit și grăbit.
4. Revizuirea de securitate a unei modificări. Ce se verifică pe zonele sensibile: autentificare, plăți, date personale.
5. Onboarding în proiect. Întrebările și ordinea explorării, utile la fiecare coleg nou — tiparul complet e în articolul despre onboarding într-un codebase necunoscut.

Pentru fiecare, testul de utilitate e același: dacă procedura se repetă de cel puțin trei ori pe trimestru și cineva a scris-o deja într-un mesaj, merită un skill.

Un skill complet, comentat

Exemplul de mai jos e o procedură reală de echipă — verificarea unei modificări care atinge zone sensibile — scrisă în forma minimă care funcționează:

---
name: revizuire-securitate
description: Verifică o modificare care atinge autentificare, plăți sau date
  personale. Se folosește înainte de aprobarea unui pull request pe aceste zone
  sau când cineva întreabă dacă o schimbare e sigură.
paths: "src/auth/**,src/billing/**,src/users/**"
---

# Revizuire de securitate

Parcurge, în ordine, și raportează doar ce ai găsit efectiv, cu fișier și linie.

1. Intrări externe: sunt validate și tipizate înainte de folosire?
2. Interogări: sunt parametrizate? Există concatenare de șiruri?
3. Autorizare: se verifică dreptul utilizatorului pe resursa atinsă?
4. Jurnalizare: ajung în jurnal date personale sau secrete?
5. Dependențe noi: au fost adăugate? Dacă da, semnalează separat.
6. Migrări: modifică structura? Vezi lista din skill-ul `migrari`.

Nu propune refactorizări. Nu modifica fișiere. Rezultatul e o listă
de observații, fiecare cu severitate: blocant, important, observație.

Trei lucruri fac exemplul util: descrierea spune când se aplică, nu ce face; paths îl aduce automat în context când agentul atinge zonele sensibile; iar instrucțiunile limitează explicit rezultatul — o listă, nu modificări. Fără ultima parte, majoritatea agenților vor începe să „repare" ce găsesc.

Skills, subagenți, hooks: cine ce face

Ecosistemul are patru mecanisme care se confundă frecvent. Distincția practică:

• Fișierul de instrucțiuni — fapte permanente, prezente în fiecare sesiune.
• Skills — proceduri și referințe, încărcate la cerere; rămân în context după prima folosire.
• Subagenți — execuție izolată, cu context propriu, pentru explorări lungi care altfel ar umple contextul principal. Un skill poate cere rularea într-un context izolat, prin context: fork.
• Hooks — comenzi care rulează la momente fixe din ciclul de viață, indiferent ce decide modelul. Singurul mecanism din listă care garantează ceva.

Testul de alegere, în trei întrebări: e valabil mereu? → instrucțiuni. E o procedură pe care o repet? → skill. Trebuie să se întâmple obligatoriu? → hook sau verificare în pipeline.

Greșelile care le fac inutile

Descriere vagă. „Ajută la testare" nu spune agentului când să o folosească, deci nu va fi invocată niciodată automat. Descrierea trebuie să conțină situațiile concrete.

Skill prea lung. Peste câteva sute de linii, devine o carte pe care agentul o parcurge superficial. Materialul de referință se mută în fișiere separate.

Procedură cu un singur pas. Dacă instrucțiunea încape într-o propoziție, locul ei e în fișierul de instrucțiuni, nu într-un skill separat.

Skills care se contrazic cu fișierul de instrucțiuni. Când două surse spun lucruri diferite despre același comportament, rezultatul e arbitrar. O curățare trimestrială rezolvă problema mai bine decât orice regulă suplimentară.

Uitarea părții de securitate. Skills pot include execuție de comenzi, iar conținutul lor ajunge în context. Într-un depozit partajat, un skill e cod: trece prin revizuire, ca orice altceva. Există și o setare de politică, disableSkillShellExecution, prin care organizațiile opresc complet execuția de comenzi din skills. Contextul mai larg — ce poate atinge un agent și cum îl izolezi — e în ghidul despre izolarea agenților de programare.

Cum le administrezi într-o echipă

Trei reguli simple:

Versionate în depozit. Skills de proiect stau în .claude/skills/, sunt comise și trec prin pull request. Un skill scris de cineva pe laptopul propriu ajută o persoană; unul comis ajută echipa și se corectează în timp.

Cu proprietar. Fiecare skill are un responsabil care îl actualizează când procedura se schimbă. Un skill învechit e mai periculos decât lipsa lui, pentru că agentul îl va urma cu încredere.

Revizuite ca documentația. O dată pe trimestru: ce nu s-a folosit deloc, ce s-a schimbat în proces, ce s-a dublat între două skills.

Lucrul efectiv cu agentul pe depozit — permisiuni, hooks, integrare în fluxul de versionare — e tratat pe larg în cursul Claude Code Mastery.

Cum îl testezi înainte să-l dai echipei

Un skill nu e cod, dar se comportă ca atare: are intrări imprevizibile și produce efecte. Trei verificări rapide, înainte de a-l comite:

Se invocă singur când trebuie? Pornește o sesiune curată, formulează cererea așa cum ar face un coleg — „poți să verifici modificarea asta?" — și vezi dacă agentul îl alege. Dacă nu, problema e aproape întotdeauna descrierea, nu conținutul.

Nu se invocă atunci când nu trebuie? Testul invers e la fel de important. Un skill cu descriere prea largă intră în context la cereri care n-au legătură cu el și consumă din bugetul de atenție al agentului.

Produce ce ai cerut? Rulează-l pe trei cazuri reale din proiect și compară rezultatul cu ce ai fi scris tu. Aici se vede dacă instrucțiunile sunt suficient de specifice: „verifică securitatea" produce generalități, „parcurge lista în ordine și raportează cu fișier și linie" produce ceva utilizabil.

După ce trece cele trei verificări, îl comiți, îl anunți în canalul echipei și îl treci în revizuirea trimestrială.

Întrebări frecvente

Î: Care e diferența dintre un skill și fișierul de instrucțiuni al proiectului? R: Momentul încărcării și tipul conținutului. Fișierul de instrucțiuni se încarcă la fiecare pornire de sesiune și conține fapte permanente: comenzi, convenții, structură. Un skill se încarcă doar când e invocat — de tine sau de agent — și conține proceduri sau material de referință. Documentația recomandă explicit mutarea într-un skill atunci când o secțiune din fișierul de instrucțiuni „a devenit o procedură, nu un fapt".

Î: Cum îl face agentul să aleagă singur skill-ul potrivit? R: Din câmpul description, completat opțional de when_to_use și restrâns de paths. Textul combinat al descrierii și al lui when_to_use e trunchiat la 1.536 de caractere, deci contează precizia: enumeră situațiile concrete în care skill-ul se aplică, nu beneficiile lui.

Î: Pot împiedica agentul să pornească singur o procedură periculoasă? R: Da, cu disable-model-invocation: true în configurarea skill-ului: rămâne invocabil doar de tine. E setarea potrivită pentru lansări, migrări și orice atinge sisteme externe. Invers, user-invocable: false face skill-ul disponibil doar agentului și îl ascunde din meniul de comenzi.

Î: Ce lungime ar trebui să aibă un skill? R: Documentația recomandă sub 500 de linii pentru SKILL.md, cu materialul detaliat mutat în fișiere separate la care se face trimitere. Dacă ai nevoie de mai mult, aproape sigur ai două skills amestecate într-unul.

Î: Skills înlocuiesc verificările automate din pipeline? R: Nu. Un skill e context, la fel ca instrucțiunile de proiect: influențează comportamentul, dar nu îl garantează. Ce trebuie garantat — teste care trec, absența secretelor, migrări conforme — rămâne în verificări automate care blochează livrarea, nu în text pe care agentul îl citește.

Concluzie

Skills rezolvă o problemă concretă și măsurabilă: procedurile lungi nu mai ocupă context în fiecare sesiune, dar rămân la un / distanță când ai nevoie de ele. Restul valorii vine din disciplina obișnuită de echipă — versionare, proprietar, revizuire periodică.

Împărțirea care merită ținută minte: faptele în fișierul de instrucțiuni, procedurile în skills, garanțiile în verificări automate. Trei locuri, trei roluri diferite; confuzia dintre ele e motivul pentru care multe echipe au fișiere de instrucțiuni de patru sute de linii pe care agentul le respectă doar pe jumătate.

Surse: Claude Code — Skills · Claude Code — memoria proiectului și CLAUDE.md · agents.md — formatul de instrucțiuni pentru agenți

Articol informativ, publicat la 19 septembrie 2026. Numele câmpurilor de configurare și comportamentul uneltelor se modifică între versiuni — verifică documentația oficială la data implementării.