Agent skillovi
Korigovanje načina kako agenti pišu
Mihailo SibonjicSoftware Architect, ažurirano
Kada od agenta tražite da napravi README, status ili poruku za commit, dobijete AI slop isprepletan rečenicama koje zvuče duboko i bitno, a u suštini ništa ne kažu. Ovdje želimo pokazati jedan od načina kako da promijenimo to ponašanje i dobijemo tekst koji više liči na nešto inženjerski pisano. Jedan od načina jeste korištenje Google developer vodiča kao skilla.
Zašto AI tekst zvuči kao AI?
Četiri navike obilježavaju mašinski pisanu tehničku prozu.
| Navika | Primjer | Lijek |
|---|---|---|
| Aforizam | "Tests are the specification" | Recite tvrdnju koju je zamijenio, na primjer "the test names describe the intended behavior" |
| Riječi-punjenje | leverage, robust, seamless, just, simply | Lista riječi i jedno pravilo, a to je da ništa nikada ne zovete jednostavnim ili lakim |
| Prešućena rupa | Nabraja šta je uspjelo, šuti o onome što je preskočeno | Popravite redoslijed, prvo šta je sada tačno, zatim šta se promijenilo, pa šta je neurađeno i zašto |
| Preambula | "Great question." "You're absolutely right." | Zabranite pohvalu kao uvod |
Ako se čitalac s rečenicom mora složiti, ta rečenica ne nosi informaciju, a sažetak sagrađen od takvih rečenica ne govori vam skoro ništa relevantno.
Zašto Googleov vodič
Možete pisati vlastita pravila i održavati ih i dobiti registar koji vam tačno odgovara. Druga opcija je vodič koji održava neko drugi. Google developer vodič je javan i svako pravilo u njemu ima URL. Kada se vi i agent ne slažete oko rečenice, presuđujete citatom umjesto ukusom.
| Previše neformalno | Kako treba | Previše formalno |
|---|---|---|
| Dude! This API is totally awesome! | This API lets you collect data about what your users like. | The API documented by this page may enable the acquisition of information pertaining to user preferences. |
| Nailed it, tests are green | All 34 tests pass. Two were already failing on main, so I left them. |
Test execution completed with satisfactory results. |
Drugi red je slučaj koji sam vodič ne pokriva, agent koji izvještava o upravo završenom poslu, a pokriva ga proširenje u sekciji "Izvještavanje o vlastitom radu" (Reporting your own work).
Kako skill radi i šta košta
Skill je direktorij, a ne fajl. Ime direktorija je ime skilla, kebab-case, i sadrži SKILL.md plus folder references/:
plain-prose/
├── SKILL.md # required, and the only file that loads on trigger
└── references/ # optional, each file read only when its topic comes up
├── grammar.md
├── mechanics.md
├── ...
└── word-list.mdSKILL.md nosi ime i opis. Opis je okidač, pa mora imenovati situacije, a ne temu, i tek kada se opis poklopi, tijelo fajla ulazi u kontekst. Možete ga pokrenuti i sami, imenujući skill i dajući mu posao.
Iza referentnih fajlova ne stoji nikakav mehanizam. SKILL.md nosi tabelu tema i relativnih putanja, sa jednim ciljem, a to je da se pročitaju samo oni fajlovi koji su potrebni i tiču se teme.
Ništa ne osigurava postojanje references/, tako da eventualno nepostojanje putanje ne rezultuje greškom.
Cijena koju plaćamo inicijalno jeste opis, pošto na osnovu njega agent odlučuje da li je skill relevantan, dok u slučaju da jeste, cijelo tijelo skilla bit će učitano u kontekst, a to i jeste cijena aktivacije. Referentni fajlovi se učitavaju po potrebi, vezano za temu. Ovo je primjer skilla sa osam referentnih fajlova od ukupno nekih 1.658 redova. Ono što vrijedi za svaku rečenicu možemo držati unutar skilla, a ostalo vezano za specifične teme razdvojiti po zasebnim fajlovima.
Povratna petlja
Pravilo koje agent ne može provjeriti je pravilo koje agent neće slijediti. U praksi najkraća sekcija najviše mijenja izlaz. To je kontrolna lista koja se izvršava nad nacrtom koji već postoji:
- Da li je rečenica napisana tako da se čitalac s njom mora složiti? Prepišite je u tvrdnju koju bi mogao osporiti.
- Ishod u prvoj rečenici?
- Svaki naslov običan natpis, u sentence caseu?
- Da li sadrži slop riječi sa liste, poput just, simply, leverage, robust, seamless?
- Pasiv tamo gdje je bitan akter?
- Da li sadrži superlative ili garancije koje ne možete podržati?
- Da li sadrži neprovjerene tvrdnje?
- Da li ima preskočenih stvari koje nisu pomenute?
Svaka linija je da-ili-ne pitanje o tekstu koji je već pred njim.
Skill fajl
Gdje sačuvati direktorij zavisi od alata koji koristite i, naravno, da li želite globalnu konfiguraciju ili spram projekta/foldera:
| Alat | Za vas | U repozitoriju |
|---|---|---|
| Claude Code | ~/.claude/skills/ | .claude/skills/ |
| GitHub Copilot | ~/.copilot/skills/ | .github/skills/ |
| Kiro | ~/.kiro/skills/ | .kiro/skills/ |
| Codex, Gemini CLI, Goose | ~/.agents/skills/ | .agents/skills/ |
.agents/skills/ je zajednički korijen koji čitaju svi alati iz posljednjeg reda, a Copilot i Goose čitaju i .claude/skills/, pa je repozitorij već postavljen za Claude Code djelimično prenosiv bez ikakvog premještanja.
Preuzmite skill i referentne fajlove i smjestite ih na odgovarajuće mjesto, zavisno od agenta koji koristite.
Uvijek pročitajte skill prije nego što ga instalirate i koristite.
- name
- plain-prose
- description
- Applies the Google developer documentation style guide to prose: plain, checkable technical English with no aphorisms, buzzwords, or filler. Use when asked for Google style or "the style guide", and when writing or reworking technical prose: a summary or status report, a findings list, a README, design doc, spec, or runbook, a commit body, a code comment, release notes, PR or issue text, or a draft written for the user. Also use when asked to tighten, proofread, or de-slop existing prose, or when asked why a sentence reads as AI-written. Not a global default: for informal or non-technical writing, follow the user's own register instead.
Prose conventions
Source: the Google developer documentation style guide. Each file under references/ names the guide pages it extracts, so a disputed rule is settled there, by citation. Rules marked "extension" are house additions, not the guide's. Guide content © Google, used under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/).
Register
The guide asks for "conversational, friendly, and respectful", like "a knowledgeable friend". Extension: aim instead at a senior engineer writing to a competent colleague, specific and unhurried, nothing staged for effect.
| Too informal | Right | Too formal |
|---|---|---|
| Dude! This API is totally awesome! | This API lets you collect data about what your users like. | The API documented by this page may enable the acquisition of information pertaining to user preferences. |
| Nailed it, tests are green | All 34 tests pass. Two were already failing on main, so I left them. | Test execution completed with satisfactory results. |
Avoid buzzwords, figurative language, pop-culture references, internet slang, and exclamation marks. Never call anything simple or easy. Extensions in the same spirit: no emoji, and no praise as preamble ("Great question", "You're absolutely right").
Don't compress a finding into an aphorism (extension)
A technical summary needs statements the reader can test against the code.
| Aphorism | Claim |
|---|---|
| Data flows in one direction | Reducers are the only place state changes |
| Tests are the specification | The test names describe the intended behavior |
| Errors are values, not events | Failures are returned, not thrown |
| Boundaries carry the contract | The boundary validates input; nothing below it does |
If a reader can't disagree with the sentence, it carries no information. This covers headings, bullet summaries, closing lines, and titles. A heading labels the section it opens.
Reporting your own work (extension)
First person for what you did, past tense; present tense for the behavior that resulted: "I changed both call sites. The retry count is read once." Lead with what is true now, then what changed, then what you left undone and why. If you don't name a gap, the reader assumes there isn't one.
Sentences
- Active voice, and name who acts.
- Present tense. Reserve
willfor something that genuinely happens later. - No em dashes (extension). Use a comma, a colon, parentheses, or two sentences.
- Conditions before instructions: "To delete the document, click Delete."
- Second person. Address the reader as "you", not "the user".
- Under 26 words. Cut
in order tototo,make use oftouse,a number oftosome. - No anthropomorphism. Software doesn't want, think, know, or try.
- Put
onlynext to what it limits: "Request only one token." - Keep
then,that,of. Two characters, and they save a re-read. - No ambiguous pronouns: "the text doesn't change", not "it doesn't change".
- No directional references. "The preceding section" survives a re-layout, "above" doesn't.
- Two nouns of modifier stacking, maximum, unless three is the established name of the thing (payment retry queue).
Paragraphs and order
Most important information first, in the paragraph and in the reply. One idea per paragraph. Past five or six sentences, look for the second idea. A one-sentence paragraph is fine.
References
Read the file for the topic at hand, not all eight.
| Topic | File |
|---|---|
| Voice, tense, person, pronouns, agreement | references/grammar.md |
| Capitalization, punctuation, numbers, dates, units | references/mechanics.md |
| Words to avoid, jargon, inclusive language, the slop list | references/word-list.md |
| Headings, lists, procedures, notices, tables, links | references/documents.md |
| Code font, code samples, command syntax, placeholders | references/code.md |
| Claims, must/should/can, superlatives, verified versus assumed | references/claims.md |
| Product names, trademarks, filenames | references/names.md |
| Markdown versus HTML, semantic tagging | references/markup.md |
Before you send
- Any sentence a reader couldn't disagree with? Rewrite it as the claim it replaced.
- Outcome in the first sentence?
- Every heading a plain label, in sentence case?
- Any word from the slop list, any
just,simply,leverage,robust,seamless? - Passive voice where the actor matters?
- Any superlative or guarantee you can't support?
- Anything asserted that you didn't actually check?
- Anything you skipped that you haven't admitted?
Osam referentnih fajlova
Jedan fajl pokriva svaku rečenicu. Osam referentnih fajlova postoji zato što je većina stilskih pravila vezana za jednu vrstu pisanja.
| Fajl | Pokriva |
|---|---|
grammar.md | Glas, vrijeme, lice, zamjenice, slaganje, množine, kontrakcije, članovi |
mechanics.md | Velika slova, interpunkcija, brojevi, datumi, jedinice, skraćenice |
word-list.md | Riječi koje treba izbjegavati, žargon, inkluzivan jezik, slop lista |
documents.md | Naslovi, liste, procedure, napomene, tabele, linkovi, slike |
code.md | Code font, primjeri koda, sintaksa komandi, placeholderi, komentari API referenci |
claims.md | must/should/can, superlativi, prednajave, provjereno naspram pretpostavljenog |
names.md | Imena proizvoda, zaštitni znakovi, imena i tipovi fajlova |
markup.md | Markdown naspram HTML-a, semantičko označavanje |
Svih osam izdvojeno je 1. augusta 2026 i svaka sekcija imenuje stranicu vodiča koju izdvaja.
Vodič se stalno revidira i on je mjerodavan tekst, pa otvorite citiranu stranicu kada pravilo nosi stvarnu težinu.
Neka ostane konverzacijski
Konvencije imenovanja klasa, metoda i varijabli za određeni stack, razlike između paketa i modula ili neka specifikacija generalno jesu korisni, ali mogu biti definisani mimo konverzacijskog skilla. Svaka konvencija definisana za neki programski jezik mijenja se u svom ritmu i po potrebi, tako da ih je bolje držati odvojeno jer ih je tako lakše održavati.
Pokušavamo imati strukturu koja se lako održava, a skillove dijelimo po vrsti materijala koji pokrivamo, a ne po projektu.