Best practices pro psaní znovupoužitelných skillů / prompt modulů / instruction balíčků primárně pro Claude a OpenAI, s konkrétními šablonami, anti-patterny, srovnáním a přehledem populárních veřejných repozitářů.
Dobrý skill není jen prompt. Je to malý operační protokol pro opakovatelný typ práce. Typicky obsahuje:
Praktický princip: skill má být dostatečně konkrétní, aby šel použít bez dovysvětlování, ale ne tak široký, aby přepisoval chování celého agenta.
Primární zdroje: Anthropic prompt engineering docs, system prompts, XML tags, tool use, evals, Claude Code memory. Níže rozlišuji explicitní doporučení od syntézy.
| Pravidlo | Proč | Pro Claude piš takto | Status |
|---|---|---|---|
| Instrukce strukturuj do sekcí | Claude je stabilnější, když je kontext oddělený a dobře označený. | Používej jasné bloky typu Purpose, Use when, Procedure, Output; Anthropic explicitně doporučuje strukturování a XML tagy. |
Oficiální |
| Jasně vymez scope | Příliš široké instrukce zvyšují konflikty a halucinace. | Jedna zodpovědnost na skill: např. „udělej PR review“, ne „spravuj celý repo lifecycle“. | Syntéza z oficiálních zásad |
| Uveď trigger podmínky | Bez triggerů skill přepaluje ostatní instrukce. | Explicitně napiš „Use when…“ a „Do not use when…“. | Syntéza |
| Přidej few-shot příklady | Anthropic doporučuje multishot prompting pro konzistentní pattern chování. | Minimálně 1 happy path, 1 edge case, 1 failure/escalation case. | Oficiální |
| Tool rules piš explicitně | Tool use selhává hlavně kvůli neurčitým podmínkám a schema nejasnostem. | Odděl Required tools, Optional tools, Never use tools for, Ask before destructive action. |
Oficiální + syntéza |
| Popiš chování při nejistotě | Claude má být veden k přiznání nejistoty místo vymýšlení. | „If required info is missing, ask targeted questions / say what is unknown / do not infer facts." | Oficiální |
| Definuj eval kritéria | Anthropic výslovně tlačí evals místo dojmového ladění promptu. | Měj testy: správná aktivace, neaktivace, formát, tool-use, bezpečný fail. | Oficiální |
Primární zdroje: OpenAI Model Spec, Structured Outputs guide, OpenAI Cookbook prompt guide, evaluation flywheel, ukázkové agent prompt soubory. OpenAI má oproti Anthropicu o něco silnější důraz na instruction hierarchy, structured outputs a eval flywheel.
| Pravidlo | Proč | Pro OpenAI piš takto | Status |
|---|---|---|---|
| Respektuj chain of command | OpenAI Model Spec explicitně rozlišuje root/system/developer/user/guideline. | Skill nepiš tak, aby implicitně bojoval se systémovými nebo developer instrukcemi. Raději explicitně deklaruj prioritu a scope. | Oficiální |
| Scope first | Cookbook říká: menší scope = vyšší kontrola a hloubka. | „One prompt / skill = one deliverable.“ Rozděl složité workflow na více promptů nebo agentů. | Oficiální |
| Explicitně definuj output | OpenAI guidance zdůrazňuje audience, tone, format, must-include body, decision criteria. | Používej bloky # Context, # Instructions, # Additional Information, # Output format. |
Oficiální |
| Pro strojové workflow používej Structured Outputs | Spolehlivost stoupá, když formát vynucuje JSON Schema. | Klíče pojmenuj jasně, doplň title/description, nastav strict: true, additionalProperties: false, a evaluj schéma. |
Oficiální |
| Řeš incompatibility vstupu | OpenAI explicitně upozorňuje, že model se může snažit držet schema i u nesmyslného vstupu → halucinace. | Do skillu napiš fallback: vrátit empty fields / refusal / explicitní error state pokud input neodpovídá tasku. | Oficiální |
| Napiš retry politiku pro tools | V agent prompt příkladech Cookbooku jsou retry pravidla explicitně separovaná. | „Retry same tool call up to N times for network/5xx, nerepeatuj invalid-input errors.“ | Oficiální příklad |
| Ladění dělej eval flywheel metodou | OpenAI doporučuje Analyze → Measure → Improve místo „prompt-and-pray“. | Udržuj dataset failů, automatické graders/evals, a ladění prováděj proti baseline. | Oficiální |
| Dimenze | Claude / Anthropic | OpenAI | Praktický dopad na autora skillu |
|---|---|---|---|
| Primární důraz | Struktura instrukcí, jasnost, XML/sekce, tool-use explicitnost | Instruction hierarchy, output contracts, structured outputs, eval loop | Pro Claude piš velmi čistě a čitelně; pro OpenAI navíc přemýšlej „jak to budu validovat strojově“. |
| Scope design | Silně doporučen úzký a přesný skill | Výslovně „scope first“, menší prompt = lepší kontrola | U obou platí: nerozšiřovat skill do mega-workflow. |
| Práce s tools | Explicitně popsat kdy a proč nástroj použít | Explicitně popsat tool policy + retry + error handling | Tool policy vždy oddělit do vlastní sekce. |
| Formát výstupu | Silně pomáhá, ale často textově | Často ideálně JSON schema / structured outputs | Pokud chceš přenositelnost mezi oběma, napiš textový kontrakt + volitelný JSON režim. |
| Evals | Oficiálně doporučené | Silně formalizované přes evaluation flywheel | OpenAI dokumentace je konkrétnější v tom, jak prompt iterovat jako inženýrský proces. |
| Anti-pattern | Co se stane | Lepší varianta |
|---|---|---|
| „Pomáhej uživateli co nejlépe.“ | Příliš obecné. Model neví, co přesně je deliverable ani priorita. | „Když uživatel žádá PR review, vrať: summary, critical issues, nitpicks, merge recommendation.“ |
| Skill bez „do not use when“ | Skill se aktivuje i mimo intended task a přepisuje ostatní chování. | Přidej explicitní kontraindikace. |
| Tool-use skryté v odstavcích | Tool policy se hůř dodržuje a hůř reviewuje. | Samostatná sekce Tool rules. |
| „Vrať JSON“ bez schema | Časté driftování polí a nekonzistentní typy. | JSON Schema / Structured Outputs / minimálně pevný field contract. |
| Chybí failure mode | Model začne doplňovat chybějící fakta. | Předepsat, co dělat při missing input nebo low confidence. |
| Obří univerzální skill | Vysoká kolize instrukcí, horší udržovatelnost. | Sada menších composable skillů. |
# Skill: <name> ## Purpose Jednovětý účel. ## Use when - podmínka 1 - podmínka 2 ## Do not use when - podmínka 1 - podmínka 2 ## Required inputs - vstup A - vstup B ## Procedure 1. Zkontroluj input. 2. Pokud něco chybí, doptat se / explicitně to přiznat. 3. Použij nástroje jen za definovaných podmínek. 4. Vyrob výstup v předepsaném formátu. 5. Přidej caveats jen když jsou relevantní. ## Tool rules - Use <tool> for ... - Never use <tool> for ... - Retry on transient errors up to N times. - Ask before destructive/external side effects. ## Output format - sekce - délka - povinné body - citace / JSON / tabulka / markdown / HTML ## Failure / escalation - Když chybí X, vrať Y. - Když confidence < threshold, explicitně to řekni. - Když je task mimo scope, odmítni nebo přepni na jiný skill. ## Eval cases - happy path - near miss - conflicting instruction - missing input
# Context
Co model potřebuje vědět.
# Instructions
Co přesně má udělat, v jakém pořadí, s jakými pravidly.
# Additional Information / Constraints
Audience, tone, must-include points, forbidden assumptions, failure behavior.
# Output format
Return JSON matching this schema exactly.
{
"type": "object",
"additionalProperties": false,
"required": ["status", "summary", "issues"],
"properties": {
"status": { "type": "string", "enum": ["ok", "needs_info", "out_of_scope"] },
"summary": { "type": "string", "description": "Short final summary." },
"issues": {
"type": "array",
"items": { "type": "string" }
}
}
}
<skill>
<purpose>One clear job.</purpose>
<use_when>
<item>Condition A</item>
<item>Condition B</item>
</use_when>
<do_not_use_when>
<item>Condition C</item>
</do_not_use_when>
<procedure>
<step>Check inputs.</step>
<step>Ask targeted follow-up if required info is missing.</step>
<step>Use tools only under tool_rules.</step>
<step>Return output exactly in output_contract.</step>
</procedure>
<tool_rules>
<rule>Use web retrieval only for current facts.</rule>
<rule>Never perform destructive actions without confirmation.</rule>
</tool_rules>
<output_contract>...
</skill>
Pozn.: GitHub běžně nezveřejňuje „download count“ pro repozitáře. Proto používám hlavně stars jako proxy popularity a přidávám forks + watchers. Stav k 2026-05-17, přes GitHub API.
| Repo | Stars | Forks | Watchers | Co obsahuje | Proč je relevantní | Užitečné přímé odkazy |
|---|---|---|---|---|---|---|
| f/prompts.chat | 162,390 | 21,142 | 1,632 | Obří veřejná sbírka promptů, původně Awesome ChatGPT Prompts. | Nejsilnější community referenční korpus pro patterny formulací, i když ne vše je „production-grade skill“. | repo |
| anthropics/claude-code | 124,228 | 20,460 | 763 | Oficiální Claude Code, včetně pluginů/command balíčků. | Nejrelevantnější oficiální zdroj pro strukturu pluginů, commands a agent workflows okolo Claude. | plugins, code-review, feature-dev |
| dair-ai/Prompt-Engineering-Guide | 74,652 | 8,078 | 739 | Rozsáhlý guide k prompt engineeringu, context engineeringu, agentům a patternům. | Silný referenční rámec a příklady anti-patternů / technik. | repo |
| openai/openai-cookbook | 73,574 | 12,421 | 992 | Oficiální OpenAI návody, notebooky, prompt guides a agent examples. | Nejlepší oficiální OpenAI zdroj konkrétních prompt/skillu patternů. | ChatGPT prompt guide, evaluation flywheel, agent prompts |
| hesreallyhim/awesome-claude-code | 43,984 | 3,769 | 299 | Kurátorovaná kolekce skills, hooks, slash-commands, orchestratorů a pluginů pro Claude Code. | Asi nejbližší veřejný „skills marketplace“ pro Claude ekosystém. | .claude, resource table |
| anthropics/claude-cookbooks | 43,133 | 4,885 | 546 | Oficiální Claude recipes / notebooky / usage patterns. | Nejlepší oficiální doplněk k docům, když chceš vidět praktické patterns a ne jen principy. | repo |
| danielmiessler/Fabric | 41,739 | 4,140 | 393 | Framework založený na modularizovaných AI patterns/promptech pro konkrétní úkoly. | Výborný zdroj „hotových skillů“ ve smyslu task-specific prompt units. | patterns, analyze_paper, analyze_logs |
| SuperClaude-Org/SuperClaude_Framework | 22,817 | 1,926 | 188 | Framework rozšiřující Claude Code o specializované commands, persony a metodiky. | Dobrá ukázka, jak skilly vrstvit do frameworku, ale zároveň varování před přebujelou komplexitou. | .claude, CLAUDE.md, AGENTS.md |
| promptslab/Awesome-Prompt-Engineering | 5,924 | 672 | 92 | Kurátorovaný seznam prompt engineering zdrojů a technik. | Dobré jako discovery vrstva, ne jako finální authoring standard. | repo |
| microsoft/promptbase | 5,749 | 329 | 57 | „All things prompt engineering“ — komunitní zdroj patternů a materiálů. | Užitečné pro inspiraci, méně vhodné jako autoritativní standard. | repo |
| langgptai/awesome-claude-prompts | 5,103 | 552 | 46 | Kurátorované Claude prompty včetně Claude Code sekce. | Menší, ale přímo zacílené na Claude prompt/skilly design. | claudecode |
| Use case | Nejlepší zdroj | Proč |
|---|---|---|
| Oficiální Claude best practice | Anthropic docs + anthropics/claude-code | Nejvyšší autorita, méně šumu než community repa. |
| Oficiální OpenAI best practice | openai/openai-cookbook | Praktické příklady promptů, evalů, structured outputs i agent prompts. |
| Hotové Claude Code skilly / commands | awesome-claude-code | Největší specializovaná sbírka veřejných Claude Code resources. |
| Pattern library pro reálné tasky | Fabric patterns | Prompty jsou organizované jako malé task-specific jednotky. |
| Široká inspirace / brainstorming | prompts.chat | Massive corpus, ale vyžaduje tvrdý filtering kvality. |