Tvrdá pravda o Agentných Skills

V decembri 2025 Anthropic zverejnila Agent Skills ako otvorený štandard. Microsoft, Cursor a ďalší ho prijali. Existuje teraz špecifikácia na agentskills.io, štruktúra adresárov, požiadavky na YAML frontmatter a celý ekosystém.

Ale než sa ponoríme do rámcov a špecifikácií, pochopme, čo sú skills vlastne.

Čo Anthropic hovorí, že sú Skills

Z oficiálnej dokumentácie:

Agent Skills sú modulárne možnosti, ktoré rozširujú funkčnosť Claude. Každá Skills zapúšťa pokyny, metadáta a voliteľné zdroje (skripty, šablóny), ktoré Claude automaticky používa, keď sú relevantné.

Kľúčová poznamieka z inžinierskeho blogu Anthropic: skills sú opakovane použiteľné, zdrojové prostriedky na základe súborového systému, ktoré dávajú Claude doménu špecifickú odbornosť. Namiesto vysvetľovania toho istého v každej konverzácii to napíšete raz ako skill.

Problém, ktorý Skills riešia

Bez skills:

• Opakovane vysvetľujete postupy v každej relácii
• Kontext sa plní opakovanými pokynmi
• Žiadna konzistencia medzi konverzáciami

So skills:

• Napíšete pokyny raz
• Zavisia sa len keď sú relevantné
• Konzistentné správanie v rámci relácií

To je návrh. A má to zmysel.

Oficiálna štruktúra

Špecifikácia Anthropic vyžaduje špecifickú štruktúru:

.claude/skills/youtube-transcribe/
├── SKILL.md              # Povinné
├── scripts/
│   └── transcript.sh     # Voliteľné
└── references/
    └── api-docs.md       # Voliteľné

Súbor SKILL.md potrebuje YAML frontmatter:

---
name: youtube-transcribe
description: Transcribe YouTube videos to text. Use when user wants to extract transcript from a YouTube URL.
---

# YouTube Transcription

To transcribe a video:
1. Run: `scripts/transcript.sh "<youtube-url>"`
2. Output saves to: `transcripts/<video-id>.txt`

Postupné odhaľovanie

Anthropic navrhol skills okolo troch úrovní zavítania:

Myšlienka: zavítajte len to, čo potrebujete, kedy to potrebujete. Neupokriadajte všetko do každej konverzácie.

Toto je skutočne chytrá architektúra na správu kontextu.

Teraz, Tvrdá Pravda

Tu je to, čo špecifikácia nezdôrazňuje:

Skills sú len text.

YAML frontmatter? Analyzuje sa do textu pre prompt. Štruktúra adresárov? Konvencia pre organizáciu. "Postupné odhaľovanie"? Claude čítajúci súbory z disku.

Stiahajte rámec a skill je:

• Popis (aby Claude vedel, kedy ho použiť)
• Pokyny (ako to urobiť)
• Možno skript (na spustenie)

To je všetko.

Čo to znamená v praxi

Zvážte tieto dva prístupy:

Prístup A: Formálna Skills

.claude/skills/youtube-transcribe/SKILL.md

---
name: youtube-transcribe
description: Transcribe YouTube videos to text files
---

# YouTube Transcription
Run: bun scripts/youtube-transcript.sh "<url>"

Prístup B: Jednoduchý Sprievodca

guides/how-to-transcribe-youtube.md

# How to Transcribe YouTube Videos
Run: bun scripts/youtube-transcript.sh "<url>"

Pre Claude sú tieto skoro totožné. Obaja sú textové súbory s pokynmi. Obaja sa dajú nájsť vyhľadávaním. Obaja hovoria Claude, čo urobiť.

Rozdiel:

• Prístup A: Frontmatter sa zavítajú pri spustení (~100 tokenov)
• Prístup B: Claude vyhľadáva, keď potrebuje informáciu

Je zavítanie popisu vhodné na režijnú zložitosť? Niekedy áno, niekedy nie.

Keď Štruktúra Pomáha

Štruktúra Anthropic naozaj pomáha, keď:

Máte veľa skills a potrebujete objavovateľnosť

Ak máte 50 možností, zavítanie popisov umožňuje Claude vedieť, že existujú bez čítania všetkých 50 súborov. Metadáta fungujú ako index.

Chcete vyvolanie príkazu slash

Skills sa stanú príkazmi /youtube-transcribe. Používatelia ich môžu vyvolať priamo. To je reálna výhoda UX.

Potrebujete obmedzenia nástrojov

Pole allowed-tools obmedzuje, čo môže skill urobiť. Bezpečnostná výhoda pre citlivé operácie.

Distribuujete skills ostatným

Otvorený štandard znamená, že skills fungujú na Claude Code, Cursor, VS Code. Prenositeľnosť je dôležitá.

Keď Jednoduché Sprievodcovia Vyhrávajú

Ale často jednoduché sprievodcovia markdown fungujú rovnako dobre:

Jednorázové postupy

# Deploy to Production
1. Run tests: `bun test`
2. Build: `bun run build`
3. Deploy: `./deploy.sh production`

Potrebuje to byť formálny skill? Pravdepodobne nie. Je to sprievodca. Claude ho nájde, keď je relevantný.

Špecifické vedomosti projektu

# Our Brand Voice
- Professional but approachable
- No jargon unless explained
- Examples over abstractions

Toto je kontext, nie schopnosť. Textový súbor markdown v docs/ je v poriadku.

Rýchle referencie

# API Credentials
- Google Analytics: Property 478766521
- Mailgun: Check .env for MAILGUN_API_KEY
- Sentry: Project teamday-cc

Indexové informácie. Nepotrebuje postupné odhaľovanie.

Spektrum

Skills existujú v spektre od triviálnych po komplexné:

Jednoriadkové (možno nepotrebujú formálne skills)

Email notifications: bun scripts/mailgun.send.js --to="x" --subject="y"

Rýchle Reference (hraničné)

# Google Analytics
Use the mcp__google-analytics tools.
Property ID: 478766521
Common queries: pageviews, sessions, top pages

Sprievodcovia Krok za Krokom (formálny skill má zmysel)

# Add YouTube Video to Newsfeed

1. Fetch transcript
2. Extract metadata with curl (not WebFetch!)
3. Create feed post
4. Update embeddings
5. Extract entities
6. Trigger translations

Komplexné Pracovné Toky (určite skill)

Viacstupňové postupy so skriptami, validáciou, spracovaním chýb. Newsfeed skill, ktorý používame, je 250+ riadkov s podokumentmi pre špecifické úlohy.

Čím komplexnejšia je schopnosť, tým viac sa formálna štruktúra oplatí.

Súborový Systém Je Váš Priateľ

Tu je to, čo inžiniersky blog Anthropic zdôrazňuje a často sa prehliadá:

Claude má prístup k súborovému systému. Skripty sa vykonávajú prostredníctvom bash. Referenčné súbory existujú na disku. Môžete efektívne zväzovať neobmedzené referenčné materiály.

Claude môže:

• Vyhľadávať súbory: grep -r "transcribe" docs/
• Čítať to, čo nájde: Read: docs/how-to-transcribe.md
• Vykonávať skripty: bash scripts/transcribe.sh

Postupné objavovanie nepotrebuje rámec skill. Potrebuje dobru organizáciu súborov a AI, ktorá vie vyhľadávať.

Rámec skill to formalizuje s metadátami. Ale základný mechanizmus je len navigácia súborového systému.

Kontext Je Všetko

Skutočný vhľad z dizajnu Anthropic: kontextové okná sú limitovaná.

Systémový prompt Claude Code je údajne 72kb. To je ~18 000 tokenov skôr, ako začnete pracovať. Každý popis skill do toho pridáva.

Dizajn postupného odhaľovania to rieši:

• Metadáta len pri spustení (malé)
• Úplné pokyny keď je spustené (stredné)
• Skripty/referencie keď sú potrebné (neobmedzené, nie v kontexte)

Ale rovnakú výhodu dostanete z:

• Minimálny systémový prompt
• Claude vyhľadáva dokumenty keď sú potrebné
• Čítajte len to, čo je relevantné

Princíp je dôležitejší ako implementácia.

Čo Naozaj Záleží

Po vytvorení desiatok AI pracovných tokov, tu je to, čo sme sa naučili:

1. Jasné Pokyny Porazilia Chytré Štruktúry

# Generate Blog Cover

We use FAL AI. Images save to public/images/.

Run:
bun scripts/generate-image.ts "prompt" name.webp

Good prompts:
- Include style ("minimalist illustration")
- Include subject ("AI agents collaborating")
- Include mood ("professional, tech-forward")

Claude to dodržiava či je to formálny skill alebo súbor dokumentácie.

2. Objavovateľnosť Je Reálna

Ak Claude nemôže nájsť vaše pokyny, štruktúra nezáleží. Či už prostredníctvom popisov skill alebo dobrých názvov súborov, urobte veci zistiteľnými.

• ✅ guides/how-to-transcribe-youtube.md
• ✅ Skill s jasným popisom
• ❌ notes/misc/stuff-v2-final.md

3. Skripty Riešia Zložitosť

Keď sa pokyny stanú zložitými, napíšte skript:

# Instead of 20 lines of instructions:
bun scripts/add-video-to-newsfeed.ts "<youtube-url>"

Skript zapúšťa zložitosť. Skill len dokumentuje, ako ho vyvolať.

4. Iterujte Na Základe Zlyhania

Keď Claude urobí niečo zle:

• Nejasný pokyn? → Zdokonaliť text
• Chýbajúce informácie? → Pridať to
• Nemôžu to nájsť? → Lepší pomenovanie alebo pridať do indexu skill

Nepridávajte defenzívne pravidlá. Opravte skutočný problém.

Záver

Anthropic vytvoril premyslený systém na organizáciu AI schopností. Postupné odhaľovanie je chytré. Otvorený štandard umožňuje prenositeľnosť. Príkazy slash vylepšujú UX.

Ale tu je tvrdá pravda:

Skills sú len textové pokyny, ktoré Claude číta zo súborov.

Rámec pridáva:

• Vopred zavítané popisy (index)
• Vyvolanie príkazu slash
• Obmedzenia nástrojov
• Prenositeľnosť medzi platformami

Toto sú reálne výhody pre komplexné inštalácie s mnohými schopnosťami.

Ale na každodennej práci:

• Dobre pomenovaný súbor markdown funguje
• Claude može vyhľadávať a nachádzať veci
• Jasné pokyny sú dôležitejšie ako štruktúra
• Súborový systém je už systém objavovania

Nenadmerávajte inžinierstvo. Začnite s jednoduchými sprievodcami. Pridajte formálnu štruktúru skill, keď sú výhody opodstatnené.

Napíšte jasne. Organizujte zmysluplne. Nechajte Claude, aby robil svoju prácu.

V TeamDay používame oba prístupy. Formálne skills pre komplexné pracovné toky ako správa newsfeedu. Jednoduché sprievodcovia pre jednorázové postupy. Kľúč je prispôsobiť nástroj úlohe.