Tvrdá pravda o Agent Skills

V prosinci 2025 Anthropic publikoval Agent Skills jako otevřený standard. Přijali jej Microsoft, Cursor a další. Nyní existuje specifikace na agentskills.io, struktura adresářů, požadavky na YAML frontmatter a celý ekosystém.

Ale než se ponoříme do frameworků a specifikací, pojďme pochopit, co skills vlastně jsou.

Co Anthropic říká, že Skills jsou

Z oficiální dokumentace:

Agent Skills jsou modulární schopnosti, které rozšiřují funkčnost Claudu. Každý Skill balí pokyny, metadata a volitelné zdroje (skripty, šablony), které Claude automaticky používá, když je to relevantní.

Klíčová myšlenka z inženýrského blogu Anthropic: skills jsou znovupoužitelné, souborové systém-založené zdroje, které dávají Claudu dovednosti pro konkrétní doménu. Místo vysvětlování toho samého v každé konverzaci to napíšete jednou jako skill.

Problém, který Skills řeší

Bez skills:

• Vysvětlujete procedury znovu v každé relaci
• Kontext se plní opakovanými pokyny
• Žádná konzistence mezi konverzacemi

Se skills:

• Napíšete pokyny jednou
• Zavádějí se pouze když jsou relevantní
• Konzistentní chování mezi relacemi

To je pitch. A dává to smysl.

Oficiální struktura

Specifikace Anthropic vyžaduje specifickou strukturu:

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

Soubor SKILL.md potřebuje 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é odhalování

Anthropic navrhli skills kolem tří úrovní nahrávání:

Myšlenka: zavést pouze to, co potřebuješ, když to potřebuješ. Nesypej vše do každé konverzace.

Toto je skutečně chytré řešení pro správu kontextu.

Teď přichází tvrdá pravda

Tady je to, co specifikace nezdůrazňuje:

Skills jsou jen text.

YAML frontmatter? Parsován do textu pro prompt. Struktura adresářů? Konvence pro organizaci. "Postupné odhalování"? Claude čte soubory z disku.

Pokud si odstraníš framework, skill je:

• Popis (aby Claude věděl, kdy ho použít)
• Pokyny (jak věc dělat)
• Možná skript (aby se spustil)

To je vše.

Co to znamená v praxi

Zvažte tyto dva přístupy:

Přístup A: Formální Skill

.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>"

Přístup B: Jednoduchá příručka

guides/how-to-transcribe-youtube.md

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

Pro Claudea jsou tyto přístupy téměř totožné. Oba jsou textové soubory s pokyny. Oba mohou být nalezeny vyhledáváním. Oba říkají Claudeovi, co dělat.

Rozdíl:

• Přístup A: Frontmatter se předem zavede při spuštění (~100 tokenů)
• Přístup B: Claude hledá informace, když je potřebuje

Stojí si předpřipravit popis za režijní režií struktury? Někdy ano, někdy ne.

Když struktura pomáhá

Struktura Anthropic skutečně pomáhá, když:

Máte mnoho skills a potřebujete zjistitelnost

Pokud máte 50 schopností, předvolbou popisů se Claude dozví o jejich existenci bez čtení všech 50 souborů. Metadata fungují jako index.

Chcete vyvolání slash-command

Skills se stanou příkazy /youtube-transcribe. Uživatelé je mohou vyvolat přímo. To je skutečný přínos UX.

Potřebujete omezení nástrojů

Pole allowed-tools omezuje, co skill může dělat. Bezpečnostní přínos pro citlivé operace.

Distribuujete skills ostatním

Otevřený standard znamená, že skills fungují v Claude Code, Cursor, VS Code. Portabilita na věci záleží.

Když jednoduché příručky vyhrávají

Ale často fungují jednoduché markdown příručky stejně dobře:

Jednorázové procedury

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

Musí to být formální skill? Pravděpodobně ne. Je to příručka. Claude ji najde, když je relevantní.

Vědomí specifické pro projekt

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

To je kontext, ne schopnost. Markdown soubor v docs/ je v pořádku.

Rychlé reference

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

Indexuj informace. Nepotřebuje postupné odhalování.

Spektrum

Skills existují na spektru od triviálních po komplexní:

Jednolinky (možná nepotřebují formální skills)

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

Rychlé reference (na hranici)

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

Příručky krok za krokem (formální skill má smysl)

# 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čitě skill)

Procedury s více kroky se skripty, validací, zpracováním chyb. Skill pro newsfeed, který používáme, má více než 250 řádků s dílčími dokumenty pro specifické úkoly.

Čím složitější schopnost, tím více se formální struktura vyplácí.

Souborový systém je tvůj přítel

Tady je to, na co inženýrský blog Anthropic klade důraz a co se často přehlíží:

Claude má přístup k souborovému systému. Skripty se spouštějí přes bash. Referenční soubory existují na disku. Můžeš efektivně zabalit neomezeným množstvím referenčního materiálu.

Claude může:

• Hledat soubory: grep -r "transcribe" docs/
• Číst to, co najde: Read: docs/how-to-transcribe.md
• Spouštět skripty: bash scripts/transcribe.sh

Postupné objevování nepotřebuje framework skills. Potřebuje dobrou organizaci souborů a AI, která ví, jak hledat.

Framework skills to formalizuje s metadaty. Ale základní mechanismus je jen navigace souborovým systémem.

Kontext je vše

Skutečná myšlenka z designu Anthropic: kontextová okna jsou omezená.

System prompt Claude Code údajně obsahuje 72kb. To je ~18 000 tokenů předtím, než vůbec začneš pracovat. Každý skill popis k tomu přidává.

Designu postupného odhalování se to věnuje:

• Metadata pouze při spuštění (malé)
• Úplné pokyny když se spustí (střední)
• Skripty/reference když jsou potřebné (neomezené, ne v kontextu)

Ale stejný přínos získáš z:

• Minimalního system promptu
• Claude hledá docs když je potřebuje
• Čte pouze co je relevantní

Princip je důležitější než implementace.

Co skutečně záleží

Po vytváření desítek AI workflowů, tady je to, co jsme se naučili:

1. Jasné pokyny vítězí nad chytrou strukturou

# 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 následuje ať už je to formální skill nebo soubor dokumentace.

2. Zjistitelnost je reálná

Pokud Claude nemůže najít tvé pokyny, struktura na věci nezáleží. Ať už skrze skill popisy nebo dobrá jména souborů, dělej věci zjistitelné.

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

3. Skripty řeší složitost

Když se pokyny stanou složitými, napiš skript:

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

Skript zapouzdřuje složitost. Skill jen dokumentuje, jak jej vyvolat.

4. Iteruj na základě selhání

Když Claude dělá něco špatně:

• Nejasný pokyn? → Zlepši text
• Chybí informace? → Přidej ji
• Nemůže ji najít? → Lepší pojmenování nebo přidej do skill indexu

Nepřidávej defenzivní pravidla. Vyřeš skutečný problém.

Závěr

Anthropic vytvořil promyšlený systém pro organizaci AI schopností. Postupné odhalování je chytré. Otevřený standard umožňuje portabilitu. Slash příkazy zlepšují UX.

Ale tady je tvrdá pravda:

Skills jsou jen textové pokyny, které Claude čte ze souborů.

Framework přidává:

• Předpřipravené popisy (index)
• Vyvolání slash-command
• Omezení nástrojů
• Portabilitu na více platforem

Toto jsou skutečné přínosy pro komplexní nastavení s mnoha schopnostmi.

Ale pro každodenní práci:

• Dobře pojmenovaný markdown soubor funguje
• Claude může hledat a nacházet věci
• Jasné pokyny mají větší hodnotu než struktura
• Souborový systém je již systém pro objev

Nepřekomplikuj věci. Začni s jednoduchými příručkami. Přidej formální skill strukturu, když si přínosy ospravedlňují režii.

Piš jasně. Organizuj rozumně. Nech Claudea dělat svou práci.

Na TeamDay používáme oba přístupy. Formální skills pro komplexní pracovní toky jako správa newsfeedu. Jednoduché příručky pro jednorázové procedury. Klíčem je přizpůsobit nástroj úkolu.