Skills: cum echipați agentul cu o abilitate gata făcută

Există o cerere pe care o tot repetați: uită-te la modificări, verifică fișierele astea, formatează așa, iar aici nu te băga. De fiecare dată explicați procedura din nou și puțin altfel.

Rezultatul variază odată cu formularea. Azi a ieșit excelent, mâine ați uitat jumătate din condiții, iar agentul a făcut cinstit exact ce a auzit.

Soluția nu e memoria agentului, ci un folder cu instrucțiuni. Un skill este o procedură scrisă o singură dată, pe care Claude Code o poate conecta singur sau la comanda dumneavoastră. Vedem unde se află acest folder, cum vă asigurați că skill-ul a fost preluat și ce trebuie verificat înainte de prima rulare.

Ce este un skill

Înainte să trecem la fișiere și câmpuri, să prindem intuiția.

Imaginați-vă un tâmplar. Și-a notat o dată ordinea obișnuită de lucru, a pregătit fișe, șabloane și un program pentru mașină. Acum îi ajunge o frază scurtă: "strânge tot, ascute burghiul, apoi scaunul pentru pisică - pornește șablonul CNC". A pornit - și treaba merge.

Procedura scrisă ține toată lucrarea laolaltă:

• Face ordine după regulile dumneavoastră. Strânge bancul de lucru, pune sculele la locul lor - de fiecare dată la fel, exact cum v-ați obișnuit.
• Respectă limitele scrise. Fierăstrăul încă se învârte - nu se apropie. Partea sigură a lucrului o face imediat, fără întrebări în plus.
• Se uită în fișe când e nevoie. Trebuie ascuțit burghiul - deschide regula de ascuțire. Nu o ține în minte dinainte, o scoate la momentul potrivit.
• Păstrează șabloane pentru lucrări diferite. S-a trecut de la mese la scaune - ia schema de pregătire gata făcută.
• Pornește ceva complicat cu o singură comandă. Programul pentru tăieturile repetate stă deja alături. E de ajuns să spuneți: "găsește șablonul Scaun pentru pisică și pornește-l pe CNC" - mașina respectă toleranțele și ordinea operațiilor.

Un skill funcționează la fel. Nu e încă o unealtă în mâinile agentului, ci o procedură împachetată. Instrucțiunea principală păstrează ordinea și limitele, materialele de referință dau detalii la momentul potrivit, șabloanele țin semifabricatele, iar scripturile rulează partea mecanică repetabilă. Descrisă o dată - apoi doar o apelați.

Formatul skill în sine nu izolează nimic. Instrucțiunea poate limita lucrul la aspectul vizual, dar între CSS și logică nu există niciun zid tehnic. Un skill bun numește explicit zona de lucru; după rulare vă uitați la fișierele modificate și verificați comportamentul paginii. "Funcționează" și "arată bine" sunt straturi diferite, iar garanția o dă verificarea, nu formatul.

Unde trăiește skill-ul

Nicio magie în cloud aici. Un skill este un folder pe disc, chiar în proiectul dumneavoastră:

.claude/skills/web-design/SKILL.md

Calea se citește pe segmente: folderul de serviciu .claude, în el skills, apoi folderul skill-ului propriu-zis (numele îl alegeți dumneavoastră), iar în acesta fișierul SKILL.md. Un fișier text obișnuit, se deschide cu orice editor.

Pentru skill-urile din proiect și din folderul personal, numele folderului devine numele comenzii cu slash, dacă fișierul însuși nu stabilește alt nume (despre asta mai jos). Așa că alegeți-l de la început gândindu-vă cum va arăta în chat.

Acum o corectură la cea mai răspândită imagine mentală: un skill nu este un fișier, ci un folder. Lângă SKILL.md poate sta orice.

.claude/
└── skills/
    └── web-design/
        ├── SKILL.md      # fișierul principal: descriere și instrucțiune
        ├── palettes.md   # material de referință, agentul îl deschide la nevoie
        └── scripts/
            └── check.py  # script care poate fi rulat

Pentru alegerea automată, agentul are la dispoziție numele și descrierea scurtă a skill-ului, nu tot corpul. SKILL.md se încarcă la rulare, fișierele de referință de alături - doar la nevoie. De aceea o fișă lungă nu umple contextul dinainte.

Pentru lucrul local obișnuit contează trei surse de skills:

Semnul ~ înseamnă folderul personal al utilizatorului. În comenzi îl lăsați așa cum e; dacă deschideți folderul manual, mergeți în directorul dumneavoastră personal.

Diferența dintre primele două locuri e simplă și merită lămurită de la început.

Ați pus folderul în proiect - skill-ul funcționează doar în acest proiect. Deschideți proiectul vecin, și acolo nu există.

Un skill din folderul personal e disponibil în toate proiectele. E comod pentru o procedură comună, dar se poate activa și acolo unde nu vă așteptați. Ce e universal se pune acasă, ce ține de proiect rămâne în proiect.

Dacă Claude Code rulează cu un profil de curs separat, ~/.claude-codegym/, skill-urile personale stau în folderul lui skills/. Calea din proiect, .claude/skills/, nu se schimbă din cauza profilului.

Description decide când funcționează skill-ul

O situație tipică: ați pus folderul, fișierul e la locul lui, iar agentul se poartă exact ca înainte. Nimic nu e stricat - pur și simplu nu și-a dat seama că skill-ul se potrivește aici.

Uitați-vă ce are agentul la îndemână în momentul alegerii. Corpul skill-ului nu l-a citit încă: e încărcată doar lista de nume și descrieri. Așadar decizia se ia după descriere și după nimic altceva.

Să construim de la cap la coadă un skill minimal pentru proiect. Numele lui este web-design - așa se numește folderul, și tot de aici vine comanda /web-design. Aici nu mai scriem numele separat în fișier, folderul l-a stabilit deja:

.claude/skills/web-design/SKILL.md

Iar înăuntru e doar atât, nu mai trebuie nimic:

---
description: Pune în ordine interfața web - CSS modern, tranziții fluide,
  paletă coerentă. Se aplică atunci când se cere ceva frumos sau stilat.
---

# Web design

Folosește umbre discrete, tranziții fluide și o tipografie bine gândită.
Păstrează paleta coerentă, iar animațiile - la hover și la apariția elementelor.

Sus, între liniile cu trei cratime, e blocul de serviciu, dedesubt - textul obișnuit al instrucțiunii. Câmpuri obligatorii nu există, dar description merită scris întotdeauna: fără el agentul ghicește rostul skill-ului după primul paragraf din corp, și asta e o loterie.

O descriere bună răspunde la două întrebări: ce face skill-ul și când trebuie folosit. Și asta chiar cu cuvintele cu care vă scrieți de fapt cererile.

# tace: nu e clar când se aplică
description: Ajută la aspectul vizual

# se activează: spune și ce face, și când
description: Pune în ordine interfața - CSS, tipografie, paletă.
  Se aplică atunci când se cere ceva frumos, stilat sau o corectură de layout.

Descrierea hotărăște când skill-ul pornește de la sine. Dar nu e singura intrare: skill-ul are un nume, și după el îl puteți apela manual. Ați tastat /web-design - și descrierea nu mai contează deloc, fișierul se citește și se execută.

În skill-urile gata făcute apare des câmpul name. La skill-urile din proiect și din folderul personal, el stabilește comanda pe care o arată meniul deschis cu /: folderul deploy-staging cu name: deploy se apelează ca /deploy. Numele folderului continuă și el să funcționeze. Într-un plugin, name poate stabili ultima parte a comenzii, cea de după numele plugin-ului.

Căi de pornire sunt, așadar, două, iar tot ce urmează după ele e la fel.

Ramura stângă e automată: cererea s-a potrivit cu descrierea, agentul a luat skill-ul. Cea dreaptă e manuală: ați tastat /web-design, și skill-ul a pornit indiferent de descriere.

Skill-urile ajung în același meniu deschis cu / ca și comenzile integrate. Fișierul .claude/commands/deploy.md și skill-ul .claude/skills/deploy/SKILL.md creează aceeași comandă /deploy; dacă există amândouă, câștigă skill-ul.

Instalare și verificare

Ați pus folderul. Cum vă dați seama că agentul l-a văzut, și nu doar că fișierul stă pe disc?

/skills

Comanda deschide lista de skills și arată sursa fiecăruia. Tastați câteva litere - lista se filtrează. Ați găsit numele folderului și starea on - Claude Code vede skill-ul și îi permite rularea.

Numele, sursa și starea on confirmă că skill-ul este disponibil

De obicei Claude Code preia din mers un SKILL.md nou sau modificat. Dacă numele nu apare în listă, verificați pe rând:

Skill-ul e în listă, dar nu pornește singur? Reîncărcarea nu are nicio legătură. Verificați description și câmpul disable-model-invocation: true - acesta lasă doar pornirea manuală. Reformulați cererea sau apelați skill-ul după nume. Dacă apelul manual funcționează, instalarea e în regulă.

Ce verificați înainte să aveți încredere

Aici entuziasmul trebuie temperat puțin. Un skill nu e o temă vizuală și nici o imagine care se pune și se scoate după chef. Sunt instrucțiuni pe care agentul dumneavoastră le va executa în proiectul dumneavoastră.

Verificați nu doar fișierul principal, ci tot folderul. Începeți cu patru lucruri:

• descrierea - se potrivește cu ce așteptați de la skill și nu se activează prea larg;
• corpul și trimiterile din el - ce îi cere skill-ul agentului să facă și ce fișiere de alături îi cere să deschidă;
• folderul scripts/, dacă există - ce comenzi se rulează acolo, ce fișiere și ce adrese de rețea ating;
• câmpul allowed-tools - ce instrumente permite skill-ul dinainte, fără o întrebare separată.

---
name: pre-commit-style
description: Aduce proiectul la stilul comun înainte de commit
allowed-tools: Read, Write, Edit, Glob
---

Aici allowed-tools nu descrie planul de lucru și nu limitează setul complet de capabilități ale agentului. Câmpul doar pre-aprobă instrumentele enumerate pentru tura în care e invocat skill-ul. Numele se descifrează simplu:

• Read - citește fișiere;
• Write - creează fișiere noi și le rescrie integral pe cele existente;
• Edit - face modificări în interiorul unui fișier existent;
• Glob - caută fișiere după mască, adică se plimbă prin proiect și vede ce există în el.

Primul și ultimul doar se uită. Write și Edit pot modifica fișiere: dacă instrucțiunea duce la o astfel de acțiune, în tura respectivă s-ar putea să nu existe o întrebare separată. Dar faptul că permisiunea există nu înseamnă că agentul o va folosi neapărat. Regulile generale de acces ale proiectului rămân în vigoare.

Câmpul în sine nu e ceva rău: elimină confirmările inutile acolo unde exact asta vreți. Dar setul l-a ales autorul skill-ului, deci merită să-l verificați înainte de prima rulare.

Și ultimul lucru, mai puțin înfricoșător, dar mult mai frecvent. Skill-ul îl îndrumă pe agent, nu garantează rezultatul. După rulare, uitați-vă la fișierele modificate și verificați rezultatul: un skill de aspect vizual poate face pagina mai frumoasă, dar nimeni nu va confirma în locul lui că butonul funcționează.

De unde luați skills gata făcute

Ca să încercați, nu e deloc obligatoriu să scrieți SKILL.md de la zero. Cel mai des, skill-urile gata făcute se găsesc în repository-uri publice sau vin împreună cu plugin-uri.

Cea mai scurtă cale e să-i cereți agentului să găsească o variantă potrivită, dar fără să o instaleze orbește. Formularea poate fi așa:

Găsește un skill pentru aspectul vizual al interfețelor. Arată-mi sursa, SKILL.md și scripturile,
explică ce fișiere și instrumente folosește. Până nu confirm eu,
nu instala nimic.

După ce ați văzut sursa și conținutul, cereți să fie pus folderul în .claude/skills/ din proiect și verificați rezultatul cu /skills.

Pentru o căutare pe cont propriu merge interogarea Claude skills marketplace. Catalogul ajută să găsiți variante, dar nu e o garanție de siguranță: conținutul se citește oricum înainte de instalare.

SKILL.md urmează standardul deschis Agent Skills, deci structura de bază se poate muta între agenți diferiți. Dar Claude Code adaugă câmpuri și moduri de pornire proprii. Ați mutat skill-ul în alt instrument - verificați ce capabilități suportă acolo cu adevărat.

Propriul skill îl puteți construi împreună cu agentul

Momentul în care e timpul pentru un skill propriu se recunoaște fără nicio teorie: explicați aceeași procedură a treia oară. Nu sarcina, ci chiar ordinea pașilor - uită-te la asta, verifică aia, formatează așa, aici nu te băga. Se repetă - înseamnă că s-a copt.

Și aici vine vestea bună. Nu e obligatoriu să scrieți SKILL.md pe o foaie albă. Agentul poate construi o ciornă, iar de la dumneavoastră se cere doar să explicați ce procedură e și ce așteptați de la ea. Arată ca o conversație obișnuită:

Fă un skill pentru pregătirea unui commit. Să se uite ce s-a schimbat,
să verifice dacă n-au intrat fișiere în plus în commit și să scrie mesajul
după șablonul nostru. Îl pornesc manual, când vreau eu.
Dacă cerințele nu sunt suficiente, pune-mi mai întâi întrebări.

Observați: n-ați numit niciun câmp și nu v-ați apucat de structura fișierului. Cerințele sunt spuse în cuvinte, iar transformarea lor în câmpuri e treaba agentului.

Dacă îi lipsesc date, agentul va pune întrebări. Fără o astfel de cerere ar putea face presupuneri pe loc, de aceea rândul necesar e deja în exemplu. Când primiți ciorna, verificați fișierele, găsiți skill-ul în /skills și faceți o rulare de probă.

Dacă procedura poate fi parcursă manual, parcurgeți-o împreună cu agentul înainte de a o împacheta. Un commit făcut pas cu pas arată unde a trebuit corectat agentul și ce a lipsit din explicație. Un skill construit pe o rulare reală iese mai precis decât unul din amintiri.

Când SKILL.md se umflă

Primul skill propriu iese aproape întotdeauna dintr-un singur fișier, și e normal. Strâmt devine mai târziu: procedura capătă detalii, în ea se mută un tabel de corespondențe, o listă de reguli, trei exemple lungi, și într-o zi deschideți un fișier de patru ecrane.

Nu e nevoie să îngrămădiți totul într-un singur loc, iar motivul a fost deja spus mai sus: corpul se încarcă integral de îndată ce skill-ul intră în lucru. Cele patru ecrane de referință ajung în context și atunci când din ele trebuie un singur rând.

De aceea detaliile se mută în fișiere alăturate, iar în SKILL.md rămâne o trimitere: dacă apare situația cutare - deschide fișierul cutare. Folderul cu palettes.md și scripts/ l-ați văzut deja, iată cum arată pe dinăuntru:

## Materiale de referință

- Palete și combinații de culori - în [palettes.md](palettes.md)
- Exemple gata făcute de markup - în [examples.md](examples.md)
- Verificarea contrastului: rulează scripts/check.py

Materialul de referință agentul îl deschide la nevoie. Scriptul poate fi rulat fără ca tot codul lui sursă să fie încărcat automat în conversație, așa că dimensiunea fișierului aproape că nu consumă context. Dar un script străin se citește oricum înainte de prima rulare: e cod executabil, iar output-ul lui ajunge în lucrul agentului.

E comod să împărțiți fișierele după rol:

• SKILL.md - procedura propriu-zisă: ce se face, în ce ordine, ce nu se face. Înainte de apel agentul vede descrierea ei, iar corpul îl încarcă la rulare;
• materialele de referință - tabele, reguli, exemple lungi, tot ce nu e necesar la fiecare rulare;
• scripts/ - ce e mai simplu de executat decât de descris în cuvinte. Într-un skill străin aceste fișiere se verifică înainte de rulare;
• șabloanele - fișiere pe care skill-ul le ia ca bază și le adaptează la sarcină.

De aici și concluzia inversă, de data asta despre skill-urile altora. Un SKILL.md scurt nu înseamnă "skill simplu". Uitați-vă ce mai stă în folder lângă el.

Ce schimbă asta în lucru

Dacă strângem totul în câteva rânduri:

• o cerere repetată devine un folder. Ați descris o dată ordinea de lucru - de acum se reproduce la fel, în orice sesiune și în orice zi;
• skill-ul propriu nu trebuie scris pe o foaie albă. Explicați procedura în cuvinte, cereți să fie clarificat ce lipsește și verificați ciorna construită;
• la pornirea automată skill-ul e ales după description, la cea manuală - după numele cu slash. Dacă tace, aflați mai întâi dacă apare în listă și dacă pornirea automată e permisă;
• /skills răspunde la întrebarea "l-a preluat, până la urmă?". Jumătate de minut de verificare economisește o jumătate de oră de ghicit;
• un skill străin se citește înainte de instalare și de rulare, împreună cu fișierele și scripturile asociate;
• skill-ul schimbă felul în care agentul face treaba, dar nu izolează zona de modificări și nu înlocuiește verificarea rezultatului.