Hermes Skills House Style

Doporučený interní standard pro psaní Hermes skillů: konzistentní struktura, naming, scope, tool policy, evals a maintenance pravidla.

Cíl: aby šly skilly snadno psát, reviewovat, ladit, patchovat a dlouhodobě udržovat.

1. Jeden skill = jedna schopnost
Ne workflow všeho, ale úzký opakovatelný úkol.

2. Trigger podmínky jsou povinné
Každý skill musí mít When to Use a Do not use for.

3. Output contract je povinný
Model musí vědět, jak přesně vypadá výstup.

4. Tool policy musí být oddělená
Retry, potvrzení, side-effects, fallback.

5. Missing context nesmí vést k halucinaci
Skill musí říct, co dělat při chybějícím inputu.

6. Každý skill se dá evalovat
Bez test cases je skill jen hezký text.

1) Povinná struktura

Sekce	Povinnost	Co v ní musí být
`Overview`	Ano	Co skill dělá a proč existuje.
`When to Use`	Ano	Spouštěcí podmínky, typické triggery, kontra-příklady.
`Required Inputs`	Doporučeno	Jaké informace musí být dostupné.
`Procedure`	Ano	Konkrétní workflow krok po kroku.
`Tool Rules`	Pokud skill používá nástroje	Kdy nástroj použít, kdy ne, co retry, co potvrdit.
`Output Format`	Ano	Sekce, schema, délka, citace, tabulky, JSON, HTML…
`Common Pitfalls`	Ano	Nejčastější chyby a jak se jim vyhnout.
`Verification Checklist`	Ano	Jak ověřit, že skill fungoval správně.

2) Naming a scope pravidla

Název skillu: lowercase, hyphens, krátký, věcný. Např. requesting-code-review, ne best-skill-ever.
Description: začínej stylem Use when ....
Jedna zodpovědnost: pokud má skill víc než ~1 hlavní deliverable, rozděl ho.
Nesoutěž s vyššími instrukcemi: skill nemá přepisovat globální politiku agenta, pokud to není jeho explicitní účel.
Nepiš generické slogany: místo „be helpful“ napiš konkrétní provozní pravidla.

3) House style pro text sekcí

Špatně	Lépe	Proč
"Pomoz uživateli co nejlépe."	"When reviewing code, return: summary, critical issues, nitpicks, merge recommendation."	Konkrétní output contract.
"Použij nástroje podle potřeby."	"Use terminal for builds/tests. Use read_file for file inspection. Ask before destructive commands."	Menší prostor pro chybnou interpretaci.
"Když si nejsi jistý, tak se zeptej."	"If required inputs are missing, ask targeted questions. If retrieval is possible, retrieve before asking."	Lepší provozní přesnost.

4) Tool policy standard

Každý skill používající nástroje by měl mít vlastní mini-protokol:

## Tool Rules
- Use <tool> for ...
- Never use <tool> for ...
- Retry transient failures up to N times.
- Do not retry invalid-input failures unchanged.
- Ask for confirmation before destructive or external side effects.
- If retrieval is possible via tools, retrieve before asking the user.
- If verification is possible, verify before claiming success.

5) Output contract standard

Každý skill má explicitně definovat alespoň:

typ výstupu: text / markdown / HTML / JSON / patch / issue comment / PR review
požadované sekce nebo pole
maximální délku, pokud je důležitá
jestli jsou povinné citace / zdroje / URL / checklist
co vrátit při needs_info nebo out_of_scope

6) Missing context a failure behavior

Situace	Doporučené chování
Chybí potřebný input a jde ho dohledat	Nejdřív použij nástroj a dohledání proveď.
Chybí potřebný input a nejde ho dohledat	Polož cílenou otázku nebo vrať `needs_info`.
Výsledek nejde ověřit	Označ nejistotu, netvrď úspěch jako hotovou věc.
Skill je mimo scope	Explicitně to řekni a ideálně doporuč vhodnější skill / postup.

7) Evals: minimální sada

Happy path: normální případ, kde skill má uspět.
Near miss: podobný task, kde se skill nemá aktivovat.
Missing info: chybí povinný input.
Conflict: skill dostane kolidující instrukce nebo tool failure.

## Verification Checklist
- [ ] Skill activated only for intended trigger
- [ ] Output format matches contract
- [ ] Tool use followed policy
- [ ] Missing inputs handled without hallucination
- [ ] Final claim was verified where possible

8) Maintenance pravidla

Situace	Akce
Skill byl použit a chyběla v něm důležitá past	Okamžitě patchnout skill.
Skill přerostl přes rozumný scope	Rozdělit na menší skilly + cross-reference.
Skill má dlouhé reference	Vyvést do `references/` místo nafukování SKILL.md.
Skill duplikuje jiný skill	Sloučit nebo zúžit scope.

9) Doporučený authoring standard pro Hermes

---
name: example-skill
description: Use when the user asks for a repeatable, scoped workflow.
version: 1.0.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [skills, authoring, example]
    related_skills: [writing-plans, requesting-code-review]
---

# Example Skill

## Overview
One paragraph: what this skill does and why it exists.

## When to Use
- Trigger A
- Trigger B
- Don't use for: C, D

## Required Inputs
- Input A
- Input B

## Procedure
1. Inspect inputs.
2. Retrieve missing info if possible.
3. Execute the task in the preferred order.
4. Verify the result.

## Tool Rules
- Use X for ...
- Never use Y for ...
- Retry transient failures up to 2 times.
- Ask before destructive side effects.

## Output Format
- Section 1
- Section 2
- Final recommendation

## Common Pitfalls
1. Pitfall A
2. Pitfall B

## Verification Checklist
- [ ] Output matches requested format
- [ ] Claims are verified where possible
- [ ] Scope boundaries respected

10) TL;DR standard

Piš úzké skilly.
Vždy dej When to Use / Do not use for.
Odděl Tool Rules od prose.
Definuj Output Format.
Definuj failure behavior.
Udržuj Verification Checklist.
Patchuj skill hned, jak se ukáže reálný problém.