Technická analýza frontmatteru SKILL.md

Toto je technická reference pro blok frontmatteru v souboru Claude SKILL.md. Jejím účelem je vysvětlit každé pole a jeho vliv na chování skillu, konkrétně jak se spouští. Zde uvedené informace nejsou teoretické; vycházejí z našich přímých zkušeností s parsováním, instalací a testováním 743 unikátních skillů odeslaných do SkillProof. Naše metodologie zahrnuje spouštění každého skillu proti standardizované sadě reálných programovacích úloh a významnou součástí tohoto procesu je nejprve pochopení záměru autora, jak je deklarován v SKILL.md.

Zjistili jsme, že tento malý blok YAML je nejkritičtější a často nepochopenou součástí definice skillu. Špatně nakonfigurovaný frontmatter může tiše deaktivovat skill, což vede autora k ladění jeho skriptu, zatímco problém je v metadatech. Tato příručka dokumentuje, co každé pole dělá, jak spolu interagují a jakým konfiguracím se vyhnout.

Blok frontmatteru SKILL.md

Každý soubor SKILL.md začíná blokem frontmatteru YAML, ohraničeným ---. Jedná se o standardní konvenci v mnoha generátorech statických stránek a dokumentačních nástrojích, ale v kontextu Claude skillu to není jen pro lidskou spotřebu. Model parsuje tento blok, aby pochopil identitu, schopnosti a omezení skillu.

Tato sekce YAML pro Claude skill je ovládacím panelem pro váš skill. Základní model používá tato data k rozhodnutí, zda, kdy a jak spustit nástroje, které jste poskytli. Považovat to jen za informační komentáře je první chyba.

Minimální blok frontmatteru vypadá takto:

---
name: example-skill
description: A brief but precise explanation of what this skill does.
allowed-tools: [python]
---

Prozkoumáme každé z těchto polí, plus kritické příznaky řízení vyvolání, na základě vzorců pozorovaných ve více než 700 souborech, které jsme analyzovali.

Základní identita: name a description

Tato dvě pole definují, čím skill je pro uživatele i pro model. Mají však velmi odlišné role v tom, jak je skill spouštěn.

name

Pole name je unikátní řetězec, který identifikuje skill. Používá se pro explicitní vyvolání, když uživatel zadá @ následované názvem skillu. Například @example-skill. Název musí být jeden, bez mezer. Konvenčně je psán malými písmeny a používá kebab-case.

Ačkoli je důležité pro identifikaci a přímé uživatelské volání, name má malý nebo žádný vliv na autonomní rozhodnutí modelu použít skill. Model neodvozuje schopnosti z názvu git-history-analyzer. Spoléhá se na description.

description

Toto je nejdůležitější pole v celém frontmatteru SKILL.md. description není komentář. Je to primární sada instrukcí, která modelu říká, kdy je váš skill vhodným nástrojem pro daný úkol. Je to API dokumentace pro samotný model.

V našem testování je kvalita description proměnnou s nejvyšší korelací s úspěšností skillu. Neurčité popisy vedou k nekonzistentnímu spouštění, nesprávnému použití nástroje nebo k úplnému ignorování skillu. To je častá příčina, když se Claude skill nespouští podle očekávání.

Špatný description: "Analyzes code."

To je k ničemu. Neposkytuje žádné informace o tom, jaký druh analýzy, jaké vstupy očekává nebo jaké výstupy produkuje. Model nemá důvod zvolit tento skill před svými vlastními interními schopnostmi.

Funkční description: "Accepts a file path as input. Reads the specified file and uses the py-complexity tool to calculate the cyclomatic complexity of each function. Returns a list of functions and their complexity scores."

To je efektivní, protože je to přesné a orientované na akci:

1. Vstupy: Jasně uvádí, že přijímá cestu k souboru.
2. Akce: Specifikuje, co dělá (čte soubor, počítá cyklomatickou složitost).
3. Nástroje: Dokonce naznačuje nástroj, který použije (py-complexity).
4. Výstupy: Definuje očekávaný formát návratu (seznam funkcí a jejich skóre složitosti).

Když je modelu předložena úloha jako "Can you check the complexity of the functions in main.py?", může tuto žádost přímo přiřadit k schopnostem popsaným ve druhém description. První description by byl ignorován.

Když píšete svůj vlastní Claude skill, věnujte většinu času zdokonalování description. Napište to, jako byste dokumentovali funkci pro jiného inženýra, protože přesně to děláte.

Oprávnění nástrojů: allowed-tools

Pole allowed-tools je seznam spustitelných souborů, které skill smí vyvolat. To funguje jako bezpečnostní sandbox. Model za žádných okolností nemůže volat nástroj, který není explicitně uveden v tomto poli.

allowed-tools: [python, bash, jq]

Jedná se o kritickou bezpečnostní a spolehlivostní funkci. Zabraňuje skillu v provádění libovolného kódu a jasně definuje jeho operační rozsah. Během našeho testování ověřujeme, že uvedené nástroje jsou vhodné pro deklarovaný účel skillu. Skill, který tvrdí, že je jednoduchý formátovač JSON, ale uvádí bash v allowed-tools, je varovným signálem. I když by mohl používat bash k předání dat do jq, také uděluje skillu schopnost spouštět jakýkoli shell příkaz, což je zbytečné rozšíření oprávnění.

Viděli jsme, jak skilly selhaly, protože se pokusily volat nástroj, který není uveden. Naopak jsme označili skilly, které požadovaly příliš široká oprávnění, jež nebyla odůvodněna jejich description nebo implementací. Platí princip nejmenších oprávnění: povolte pouze přesné nástroje nezbytné pro fungování skillu.

Kontrola vyvolání: user-invocable a disable-model-invocation

Tyto dva booleovské příznaky jsou méně běžné, ale mají hluboký dopad na chování skillu. Kontrolují zdroj vyvolání: může uživatel explicitně volat skill a může se model rozhodnout jej použít sám? Výchozí hodnota pro oba je false, pokud jsou vynechány, ale efektivní výchozí chování standardního skillu předpokládá user-invocable: true a disable-model-invocation: false.

Jejich interakce může být matoucí, takže zde je souhrnná tabulka:

user-invocable	disable-model-invocation	Chování	Verdikt SkillProof
true (nebo vynecháno)	false (nebo vynecháno)	Standardní: Uživatel může @ zmínit; model může vyvolat autonomně.	Očekávaná konfigurace pro většinu skillů.
false	false (nebo vynecháno)	Pouze autonomní: Uživatel nemůže @ zmínit; model může vyvolat.	Pro úkoly na pozadí nebo pomocné funkce.
true	true	Pouze explicitní: Uživatel musí @ zmínit; model nemůže vyvolat.	Pro nástroje s vedlejšími účinky nebo vysokými náklady.
false	true	Deaktivováno: Ani uživatel, ani model nemůže vyvolat.	Chybná konfigurace. Tyto označujeme.

user-invocable

Tento příznak určuje, zda uživatel může přímo spustit skill pomocí @ zmínky. Výchozí hodnota, true, je chování, které většina uživatelů očekává. A user-invocable claude skill je ten, který můžete volat na vyžádání.

Nastavení user-invocable: false znamená, že skill může být spuštěn pouze autonomním rozhodovacím procesem modelu. Uživatel jej nemůže donutit spustit. To je platná volba pro skilly, které fungují jako pomocníci na pozadí nebo součást většího řetězce nástrojů, ale může to být velký zdroj zmatku. Testovali jsme několik skillů, kde byl tento příznak nastaven na false bez jakéhokoli upozornění v dokumentaci. Uživatelé, kteří se pokoušeli @ zmínit skill, by neviděli žádnou odpověď a předpokládali by, že je rozbitý. Pokud toto nastavíte na false, musíte to jasně zdokumentovat.

disable-model-invocation

Tento příznak je opakem user-invocable. Určuje, zda model smí proaktivně zvolit skill sám.

Výchozí hodnota, false, umožňuje modelu použít skill, kdykoli jeho description odpovídá požadavku uživatele.

Nastavení disable-model-invocation: true zakazuje modelu používat skill autonomně. Skill může být spuštěn pouze v případě, že user-invocable je také true a uživatel jej explicitně @ zmíní. To je užitečné pro nástroje, které jsou drahé, mají významné vedlejší účinky (jako je provádění síťového požadavku nebo úprava souborů) nebo vyžadují velmi specifický vstup, který model nemusí být schopen správně odvodit sám.

Kombinace tichého selhání

Nejproblematičtější konfigurace, kterou jsme objevili v našem testování, je kombinace user-invocable: false a disable-model-invocation: true. Jak ukazuje tabulka, skill nakonfigurovaný tímto způsobem nelze spustit žádným způsobem. Uživatel je zablokován v jeho volání a modelu je zakázáno jej zvolit.

V naší revizi více než 700 souborů SKILL.md jsme našli skilly s touto přesnou konfigurací. Z pohledu uživatele je skill nainstalován, ale zcela nefunkční. Je to efektivně mrtvý kód. V každém případě tyto skilly zařazujeme do fronty na manuální kontrolu. Někdy je to chyba autora. Jindy se zdá, že jde o způsob, jak dočasně deaktivovat skill v repozitáři bez jeho smazání. Bez ohledu na důvod je dodání skillu s touto konfigurací chybou.

Praktické důsledky z 743 testů skillů

Pochopení frontmatteru Claude skillu není akademické cvičení. Je to klíč k vytváření spolehlivých a efektivních skillů. Naše testování 743 skillů potvrdilo několik klíčových pravd:

1. description je spouštěč. Čas strávený jeho zdokonalováním není nikdy ztracený.
2. Výchozí nastavení jsou obvykle správná. Většina skillů by měla být uživatelsky vyvolatelná a modelem vyvolatelná.
3. Odchylky musí být záměrné a zdokumentované. Pokud uděláte skill pouze autonomní nebo pouze explicitní, vaši uživatelé musí vědět proč.

Proto existuje SkillProof. Z 743 skillů, které jsme zpracovali, 31 ve skutečnosti fungovalo hůře než použití čistého Claude. Mnoho z těchto selhání nebylo způsobeno špatným kódem, ale špatně konstruovaným frontmatterem SKILL.md, který způsobil, že se skill spustil v nesprávnou dobu, nebo vůbec. Dalších 204 skillů prošlo našimi testy, ale vyžadovalo ne zcela zřejmé nastavení, často související s pochopením, jak byly nastaveny příznaky vyvolání. Tyto poznatky – úspěchy i selhání – zveřejňujeme, protože skutečná hodnota skillu je určena jeho výkonem v reálném světě, nikoli pouze jeho kódem.

Nalezení skillů, které to dělají správně, je účelem našeho adresáře. Dobře nakonfigurovaný skill, jako je Codebase Summarizer, bude mít přesný popis a rozumná nastavení vyvolání, což mu umožní fungovat jako spolehlivé rozšíření modelu.

V našem katalogu si můžete prohlédnout všech 508 skillů, které prošly našimi testy. Každý záznam obsahuje přesný frontmatter SKILL.md a náš verdikt o jeho účinnosti. Podívejte se sami, jak vypadá dobře nakonfigurovaný, v praxi ověřený skill.