# Antigravity IDE – Skills specifikace

**Datum**: 2026-04-12
**Zdroje**: agentskills.io (oficiální specifikace), antigravity.google, community best practices

## Co jsou Skills

Modulární balíčky znalostí načítané on-demand. Každý skill = složka v `.agent/skills/<name>/` s povinným `SKILL.md`.

## Složková struktura

```
skill-name/
├── SKILL.md        # POVINNÝ – metadata + instrukce
├── scripts/        # Volitelný – executable kód pro deterministické úkoly
├── references/     # Volitelný – detailní docs načítané jen na vyžádání
└── assets/         # Volitelný – šablony, schémata, datové soubory
```

Umístění:
- Workspace: `.agent/skills/<name>/`
- Globální: `~/.gemini/antigravity/skills/<name>/`

## YAML Frontmatter

### name (POVINNÉ)
- 1-64 znaků
- Pouze lowercase alfanumerické znaky (a-z) a pomlčky (-)
- Nesmí začínat ani končit pomlčkou
- Nesmí obsahovat po sobě jdoucí pomlčky (--)
- MUSÍ odpovídat názvu rodičovské složky
- Příklady OK: `pdf-processing`, `kodi-management`, `code-review`
- Příklady ŠPATNĚ: `PDF-Processing` (uppercase), `-pdf` (začíná pomlčkou), `pdf--processing` (dvojitá pomlčka)

### description (POVINNÉ)
- 1-1024 znaků
- Toto je LLM search index pro progressive disclosure – NE lidská dokumentace
- Imperativní fráze: "Use when..." ne "This skill does..."
- Popisuj user intent, ne interní mechaniku
- Zahrnuj specifická klíčová slova pro matching
- Zahrnuj kontexty kde skill platí, i non-obvious
- Zahrnuj negativní triggery (kdy NEPOUŽÍT)
- ŠPATNĚ: `Helps with PDFs.`
- SPRÁVNĚ: `Analyze CSV and tabular data files — compute summary statistics, add derived columns, generate charts. Use when the user has a CSV, TSV, or Excel file and wants to explore, transform, or visualize the data, even if they don't explicitly mention "CSV" or "analysis."`

### Volitelná pole
- `license` – licence skillu
- `compatibility` – max 500 znaků, požadavky na prostředí (např. "Requires Python 3.14+")
- `metadata` – map string→string (author, version, tags...)
- `allowed-tools` – space-separated string, experimentální

## Progressive disclosure (3 vrstvy)

1. **Metadata (~100 tokenů)**: `name` + `description` se načtou při startu pro VŠECHNY skills
2. **Instructions (< 5000 tokenů doporučeno)**: Celý SKILL.md body se načte až když skill aktivován
3. **Resources (dle potřeby)**: Soubory ze scripts/, references/, assets/ se načtou jen když instrukce vyžádají

## SKILL.md body – best practices

### Psát
- Anglicky pro lepší LLM comprehension
- Instrukce (JAK), ne encyklopedie (CO)
- Přidej co agent NEZNÁ, vynech co zná
- Provide defaults, not menus ("use X; if that fails, use Y")
- Reusable procedures > one-off declarations
- Match specificity to fragility – křehké operace = přesné kroky; flexibilní úkoly = principy
- Gotchas sections pro project-specific pitfally
- Validation loops: "udělej → ověř → oprav → ověř znova"

### Nepsát
- Encyklopedický obsah
- Věci které LLM zná (co je PDF, jak funguje Python...)
- Duplicitní obsah z rules

## File references

Odkaz na soubory v podsložkách – agent je načte jen když na ně narazí:
```
See [reference guide](references/REFERENCE.md) for details.
Run: scripts/extract.py
```

## Podsložky

**scripts/**: Self-contained executable kód. Jasné chybové hlášky. Pro deterministické, opakované úkoly.
**references/**: Detailní technická reference. Agent čte JEN když SKILL.md instrukce říkají.
**assets/**: Šablony, obrázky, datové soubory, lookup tables.

## Anti-patterns

- Kopírovat obsah skills do rules = dvojitý context cost
- Encyklopedický obsah místo instrukcí
- Vágní description = špatný matching
- Obří SKILL.md body (>> 5000 tokenů) bez využití references/
