Anthropic Agent Skills – Skill Authoring Best Practices

Executive Summary

Komplexní best practices pro psaní Skill souborů (SKILL.md) pro Claude agenty. Hlavní teze: kontext window je sdílený zdroj – buď stručný, testuj s reálnými případy a iteruj za pomoci samotného Claudea.

Core Knowledge

Základní principy

Stručnost je klíčová

Při startu se načte jen metadata (name + description) ze všech Skills.
SKILL.md se načte až když je Skill relevantní; ostatní soubory jen když jsou potřeba.
Každý token v SKILL.md soutěží s historií konverzace → buď co nejkratší.
Pravidlo: přidávej jen kontext, který Claude nemá ve svém tréninku.

Míra svobody (degrees of freedom)

Svoboda	Kdy použít	Příklad
Vysoká (text)	Více platných přístupů, závisí na kontextu	Code review guidelines
Střední (pseudokód/parametry)	Preferovaný vzor, variace přijatelná	Report generator s parametry
Nízká (přesný skript)	Fragile operace, nutná konzistence	Database migration

Analogie: Claude na úzkém mostě (přesné instrukce) vs. v otevřeném poli (volný směr).

Testuj s každým modelem, který plánuješ používat

Haiku: potřebuje více guidance?
Sonnet: je instrukce jasná a efektivní?
Opus: nepřesvětluješ zbytečně?

Struktura Skill

YAML frontmatter – povinná pole:

name: max 64 znaků, lowercase + číslice + pomlčky, bez XML tagů, bez "anthropic"/"claude"
description: max 1024 znaků, neprázdný, bez XML tagů; popisuje co Skill dělá a kdy ho použít

Konvence pojmenování:

Preferovaný tvar: gerundium → processing-pdfs, analyzing-spreadsheets
Přijatelné: pdf-processing, process-pdfs
Vyhýbej se: helper, utils, tools, documents

Psaní efektivních popisů:

Vždy třetí osoba: "Processes Excel files…" ✓ / "I can help you…" ✗
Uveď klíčová slova i trigger kontexty: "Use when working with PDF files or when the user mentions PDFs"

Progressive Disclosure

SKILL.md jako obsah knihy – body vedou Clauda k detailním souborům jen když je potřeba.

Pravidla:

SKILL.md body < 500 řádků
Reference maximálně 1 úroveň hluboko od SKILL.md (žádné zanořené reference)
Pro reference soubory > 100 řádků: přidej table of contents na začátek

Vzory organizace:

Pattern 1 – High-level guide s referencemi:

pdf/
├── SKILL.md        # rychlý start + ukazatele
├── FORMS.md        # detail pro formuláře
├── REFERENCE.md    # API reference
└── EXAMPLES.md     # příklady

Pattern 2 – Domain-specific organizace:

bigquery-skill/
├── SKILL.md
└── reference/
    ├── finance.md
    ├── sales.md
    ├── product.md
    └── marketing.md

→ Claude načte jen relevantní doménový soubor, ostatní zůstanou na disku.

Pattern 3 – Conditional details: Základní obsah v SKILL.md, pokročilé funkce v odkazovaných souborech.

Workflows & Feedback Loops

Checklist pattern pro komplexní úkoly: Dej Claudovi kopírovatelný checklist – sleduje progres a zabrání přeskočení kroků.

Task Progress:
- [ ] Step 1: Analyze the form (run analyze_form.py)
- [ ] Step 2: Create field mapping (edit fields.json)
- [ ] Step 3: Validate mapping (run validate_fields.py)
- [ ] Step 4: Fill the form (run fill_form.py)
- [ ] Step 5: Verify output (run verify_output.py)

Feedback loop pattern: Run validator → Fix errors → Repeat – výrazně zlepšuje kvalitu výstupu.

Obsah – Content Guidelines

Bez time-sensitive informací – nepiš "před srpnem 2025 použij starý API". Starý obsah dej do <details> sekce "Old patterns".
Konzistentní terminologie – vždy jeden termín pro jednu věc (ne mix "endpoint / URL / route / path").

Časté vzory (Common Patterns)

Template pattern – poskytni šablonu výstupu; přizpůsob přísnost (ALWAYS vs. "sensible default").

Examples pattern – input/output páry ukáží Claudovi žádaný styl lépe než popis.

Conditional workflow pattern – rozhodovací strom: "Vytváříš? → follow Creation workflow. Upravuješ? → follow Editing workflow."

Evaluace a iterace

Evaluation-driven development:

Spusť Clauda na reálné úkoly bez Skill → zdokumentuj konkrétní selhání
Vytvoř 3+ evaluační scénáře
Napiš minimální instrukce, které pokrývají mezery
Opakuj: spusť → porovnej → uprav

Evaluační formát:

{
  "skills": ["pdf-processing"],
  "query": "Extract all text from this PDF…",
  "files": ["test-files/document.pdf"],
  "expected_behavior": ["…"]
}

Iterativní vývoj s Claudem A/B:

Claude A = expert který navrhuje a ladí Skill
Claude B = agent který Skill reálně používá
Cyklus: Claude B selže → přines pozorování Claudovi A → uprav → testuj znovu
Claude modely rozumí formátu Skill nativně – nepotřebuješ speciální system prompt pro tvorbu Skills.

Sleduj chování:

Nečekané cesty čtení → intuitivnost struktury
Přehlédnuté reference → explicitnějš propojení
Ignorované soubory → nepotřebný obsah nebo špatný signál

Anti-patterns

❌ Vyhýbej se	✓ Správně
Windows cesty `scripts\helper.py`	Unix cesty `scripts/helper.py`
"Můžeš použít pypdf, nebo pdfplumber, nebo PyMuPDF…"	Jeden doporučený nástroj + escape hatch pro edge case

Skills s executable kódem (pokročilé)

Solve, don't defer – ošetři chyby přímo ve scriptu, nespoléhej že je Claude vyřeší.

Utility scripts:

Spolehlivější než generovaný kód, šetří tokeny, zajišťují konzistenci
Jasně rozliš: "Run script" (execute) vs. "See script" (read as reference)

Verifiable intermediate outputs – "plan-validate-execute" pattern pro batch/destruktivní operace: analyze → create plan file → validate plan → execute → verify

Package dependencies:

claude.ai: může instalovat z npm/PyPI/GitHub
Claude API: žádný síťový přístup, žádná runtime instalace → vypiš závislosti předem a ověř dostupnost

Runtime prostředí:

Metadata (name + description) pre-loaded do system promptu
Soubory čteny on-demand přes bash
Skripty spouštěny bez načtení do kontextu (jen output spotřebuje tokeny)

MCP nástroje – vždy používej fully qualified název: ServerName:tool_name (např. BigQuery:bigquery_schema)

Decision Rules

Přidej info do SKILL.md jen pokud Claude to nemá → default: nevysvětluj základy
Čím fragilnější operace, tím nižší svoboda → přesné instrukce nebo konkrétní script
Reference max 1 úroveň hluboko → jinak Claude může číst soubory neúplně
Testuj s nejslabším modelem, který plánuješ použít → Haiku jako dolní laťka
Evaluace PŘED psaním dokumentace → piš jen to co reálně chybí
Evaluaci veď Claudem A, testuj Claudem B → odděluj roli tvůrce a uživatele

Quality Criteria

Edge Cases

Zanořené reference – Claude může přečíst soubor neúplně pomocí head -100, pokud je odkazován z jiného odkazovaného souboru. Řešení: všechny reference přímo z SKILL.md.
Velké reference soubory (>100 řádků) – přidej table of contents na začátek; Claude pak ví co je v souboru i při částečném čtení.
MCP nástroje bez prefixu – Claude nemusí nástroj najít při více dostupných MCP serverech. Vždy Server:tool.
claude.ai vs. API – balíčky dostupné na claude.ai nemusí být dostupné v API (žádný síťový přístup). Vždy ověř prostředí.
Model-specific chování – instrukce funkční pro Opus mohou být pro Haiku nedostatečné. Kalibruj na nejslabší plánovaný model.

Executive Summary

Core Knowledge

Základní principy

Stručnost je klíčová

Při startu se načte jen metadata (name + description) ze všech Skills.
SKILL.md se načte až když je Skill relevantní; ostatní soubory jen když jsou potřeba.
Každý token v SKILL.md soutěží s historií konverzace → buď co nejkratší.
Pravidlo: přidávej jen kontext, který Claude nemá ve svém tréninku.

Míra svobody (degrees of freedom)

Svoboda	Kdy použít	Příklad
Vysoká (text)	Více platných přístupů, závisí na kontextu	Code review guidelines
Střední (pseudokód/parametry)	Preferovaný vzor, variace přijatelná	Report generator s parametry
Nízká (přesný skript)	Fragile operace, nutná konzistence	Database migration

Analogie: Claude na úzkém mostě (přesné instrukce) vs. v otevřeném poli (volný směr).

Testuj s každým modelem, který plánuješ používat

Haiku: potřebuje více guidance?
Sonnet: je instrukce jasná a efektivní?
Opus: nepřesvětluješ zbytečně?

Struktura Skill

YAML frontmatter – povinná pole:

name: max 64 znaků, lowercase + číslice + pomlčky, bez XML tagů, bez "anthropic"/"claude"
description: max 1024 znaků, neprázdný, bez XML tagů; popisuje co Skill dělá a kdy ho použít

Konvence pojmenování:

Preferovaný tvar: gerundium → processing-pdfs, analyzing-spreadsheets
Přijatelné: pdf-processing, process-pdfs
Vyhýbej se: helper, utils, tools, documents

Psaní efektivních popisů:

Vždy třetí osoba: "Processes Excel files…" ✓ / "I can help you…" ✗
Uveď klíčová slova i trigger kontexty: "Use when working with PDF files or when the user mentions PDFs"

Progressive Disclosure

SKILL.md jako obsah knihy – body vedou Clauda k detailním souborům jen když je potřeba.

Pravidla:

SKILL.md body < 500 řádků
Reference maximálně 1 úroveň hluboko od SKILL.md (žádné zanořené reference)
Pro reference soubory > 100 řádků: přidej table of contents na začátek

Vzory organizace:

Pattern 1 – High-level guide s referencemi:

pdf/
├── SKILL.md        # rychlý start + ukazatele
├── FORMS.md        # detail pro formuláře
├── REFERENCE.md    # API reference
└── EXAMPLES.md     # příklady

Pattern 2 – Domain-specific organizace:

bigquery-skill/
├── SKILL.md
└── reference/
    ├── finance.md
    ├── sales.md
    ├── product.md
    └── marketing.md

→ Claude načte jen relevantní doménový soubor, ostatní zůstanou na disku.

Pattern 3 – Conditional details: Základní obsah v SKILL.md, pokročilé funkce v odkazovaných souborech.

Workflows & Feedback Loops

Checklist pattern pro komplexní úkoly: Dej Claudovi kopírovatelný checklist – sleduje progres a zabrání přeskočení kroků.

Task Progress:
- [ ] Step 1: Analyze the form (run analyze_form.py)
- [ ] Step 2: Create field mapping (edit fields.json)
- [ ] Step 3: Validate mapping (run validate_fields.py)
- [ ] Step 4: Fill the form (run fill_form.py)
- [ ] Step 5: Verify output (run verify_output.py)

Feedback loop pattern: Run validator → Fix errors → Repeat – výrazně zlepšuje kvalitu výstupu.

Obsah – Content Guidelines

Bez time-sensitive informací – nepiš "před srpnem 2025 použij starý API". Starý obsah dej do <details> sekce "Old patterns".
Konzistentní terminologie – vždy jeden termín pro jednu věc (ne mix "endpoint / URL / route / path").

Časté vzory (Common Patterns)

Template pattern – poskytni šablonu výstupu; přizpůsob přísnost (ALWAYS vs. "sensible default").

Examples pattern – input/output páry ukáží Claudovi žádaný styl lépe než popis.

Conditional workflow pattern – rozhodovací strom: "Vytváříš? → follow Creation workflow. Upravuješ? → follow Editing workflow."

Evaluace a iterace

Evaluation-driven development:

Spusť Clauda na reálné úkoly bez Skill → zdokumentuj konkrétní selhání
Vytvoř 3+ evaluační scénáře
Napiš minimální instrukce, které pokrývají mezery
Opakuj: spusť → porovnej → uprav

Evaluační formát:

{
  "skills": ["pdf-processing"],
  "query": "Extract all text from this PDF…",
  "files": ["test-files/document.pdf"],
  "expected_behavior": ["…"]
}

Iterativní vývoj s Claudem A/B:

Claude A = expert který navrhuje a ladí Skill
Claude B = agent který Skill reálně používá
Cyklus: Claude B selže → přines pozorování Claudovi A → uprav → testuj znovu
Claude modely rozumí formátu Skill nativně – nepotřebuješ speciální system prompt pro tvorbu Skills.

Sleduj chování:

Nečekané cesty čtení → intuitivnost struktury
Přehlédnuté reference → explicitnějš propojení
Ignorované soubory → nepotřebný obsah nebo špatný signál

Anti-patterns

❌ Vyhýbej se	✓ Správně
Windows cesty `scripts\helper.py`	Unix cesty `scripts/helper.py`
"Můžeš použít pypdf, nebo pdfplumber, nebo PyMuPDF…"	Jeden doporučený nástroj + escape hatch pro edge case

Skills s executable kódem (pokročilé)

Solve, don't defer – ošetři chyby přímo ve scriptu, nespoléhej že je Claude vyřeší.

Utility scripts:

Spolehlivější než generovaný kód, šetří tokeny, zajišťují konzistenci
Jasně rozliš: "Run script" (execute) vs. "See script" (read as reference)

Verifiable intermediate outputs – "plan-validate-execute" pattern pro batch/destruktivní operace: analyze → create plan file → validate plan → execute → verify

Package dependencies:

claude.ai: může instalovat z npm/PyPI/GitHub
Claude API: žádný síťový přístup, žádná runtime instalace → vypiš závislosti předem a ověř dostupnost

Runtime prostředí:

Metadata (name + description) pre-loaded do system promptu
Soubory čteny on-demand přes bash
Skripty spouštěny bez načtení do kontextu (jen output spotřebuje tokeny)

MCP nástroje – vždy používej fully qualified název: ServerName:tool_name (např. BigQuery:bigquery_schema)

Decision Rules

Přidej info do SKILL.md jen pokud Claude to nemá → default: nevysvětluj základy
Čím fragilnější operace, tím nižší svoboda → přesné instrukce nebo konkrétní script
Reference max 1 úroveň hluboko → jinak Claude může číst soubory neúplně
Testuj s nejslabším modelem, který plánuješ použít → Haiku jako dolní laťka
Evaluace PŘED psaním dokumentace → piš jen to co reálně chybí
Evaluaci veď Claudem A, testuj Claudem B → odděluj roli tvůrce a uživatele

Quality Criteria

Edge Cases

Zanořené reference – Claude může přečíst soubor neúplně pomocí head -100, pokud je odkazován z jiného odkazovaného souboru. Řešení: všechny reference přímo z SKILL.md.
Velké reference soubory (>100 řádků) – přidej table of contents na začátek; Claude pak ví co je v souboru i při částečném čtení.
MCP nástroje bez prefixu – Claude nemusí nástroj najít při více dostupných MCP serverech. Vždy Server:tool.
claude.ai vs. API – balíčky dostupné na claude.ai nemusí být dostupné v API (žádný síťový přístup). Vždy ověř prostředí.
Model-specific chování – instrukce funkční pro Opus mohou být pro Haiku nedostatečné. Kalibruj na nejslabší plánovaný model.