# Antigravity IDE – Kompletní specifikace .agent složky

**Datum**: 2026-04-04 (aktualizováno)
**Dotazy**: "Antigravity IDE agent rules YAML frontmatter description", "rules activation mode always on model decision", "agent skills workflows specification 2026"

## Shrnutí

Google Antigravity je agent-first IDE od Google DeepMind, kde AI agenti autonomně orchestrují úkoly přes editor, terminál a prohlížeč. Konfigurace agentů probíhá přes `.agent/` (nebo `.agents/`) složku s třemi pilíři: **Rules** (pravidla s YAML frontmatter), **Skills** (on-demand dovednosti) a **Workflows** (uživatelsky spouštěné sekvence). Systém využívá **progressive disclosure** – agent načítá jen to, co právě potřebuje.

## Detailní zjištění

### 1. Struktura .agent složky

```
<workspace-root>/
├── .agent/                          # Workspace-level konfigurace (legacy)
├── .agents/                         # Workspace-level konfigurace (nový standard)
│   ├── rules/                       # Pravidla chování agenta
│   │   └── *.md                     # Markdown s YAML frontmatter
│   ├── skills/                      # On-demand dovednosti
│   │   └── <skill-name>/            # Každý skill = vlastní složka
│   │       ├── SKILL.md             # POVINNÝ soubor
│   │       ├── scripts/             # Volitelné – spustitelné skripty
│   │       ├── examples/            # Volitelné – ukázkový kód
│   │       └── resources/           # Volitelné – dokumentace, šablony
│   └── workflows/                   # Uživatelsky spouštěné sekvence
│       └── *.md                     # Markdown s YAML frontmatter
```

**Globální scope**: `~/.gemini/antigravity/skills/` – pro dovednosti sdílené napříč projekty.

> **Poznámka**: Antigravity postupně přechází na `.agents/` (množné číslo), ale `.agent/` je stále plně podporováno.

### 2. Rules (Pravidla)

**Účel**: Pravidla chování vkládaná do systémového kontextu agenta. Fungují jako „guardrails".

**Formát**: Markdown soubory v `.agent/rules/` **s YAML frontmatter**.

**YAML frontmatter pro rules**:

```markdown
---
description: Stručný popis kdy a proč se toto pravidlo aplikuje
---

# Název pravidla

Obsah pravidla – instrukce v přirozeném jazyce...
```

**Povinné pole frontmatter**:
- `description` – stručný popis pravidla, klíčový pro Model Decision aktivaci

**Volitelné pole frontmatter**:
- `name` – lidsky čitelný název pravidla
- `activation` – režim aktivace (výchozí: závisí na nastavení v IDE)
- `priority` – priorita pravidla (např. "high")

**Aktivační režimy** (nastavitelné v Customizations panelu IDE nebo přes frontmatter):
- **Always On** – platí pro všechny úkoly, vždy automaticky aktivní
- **Model Decision** – agent sám rozhodne na základě `description` zda je pravidlo relevantní
- **Manual** – aktivace přes `@mention` v chatu
- **Glob** – aktivace dle souborového vzoru (např. `**/*.py`)

**Příklady názvů**: `coding-standards.md`, `security.md`, `architecture.md`

**Best practices**:
- Max 200–300 řádků na soubor, aby nedošlo k "context rot"
- Zaměřit se na to, co LLM neví – specifika projektu, ne obecné "piš čistý kód"
- Jedna oblast = jeden soubor
- Specifikovat CO dělat i CO NEDĚLAT
- Verzovat v Gitu jako kód
- `description` psát jasně – agent ho používá pro rozhodování (Model Decision)
- Pro Always On pravidla je `description` důležitý pro kontext

### 3. Skills (Dovednosti)

**Účel**: Modulární balíčky znalostí, které agent načítá on-demand.

**Princip Progressive Disclosure** (3 vrstvy):
1. **Discovery** – agent vidí jen `name` a `description` z frontmatter
2. **Activation** – agent načte celý `SKILL.md` když rozpozná relevantní úkol
3. **Reference** – agent načte soubory ze `scripts/`, `examples/`, `resources/` jen když potřebuje

**SKILL.md formát**:

```markdown
---
name: nazev-skillu          # POVINNÉ – lowercase, čísla, pomlčky; odpovídá názvu složky
description: Stručný popis CO dělá a KDY se má aktivovat.  # POVINNÉ – klíčová pro matching
---

# Název

## Kdy použít
- Triggery a scénáře

## Instrukce
Detailní pokyny...
```

**Volitelné položky frontmatter**: `license`, `metadata.author`, `metadata.version`

**Pravidla pro `description`**:
- Psát ve třetí osobě
- Zahrnout klíčová slova pro matching (agent indexuje toto pole)
- Být specifický ohledně triggerů

**Scope**:
- Workspace: `.agent/skills/<nazev>/`
- Globální: `~/.gemini/antigravity/skills/<nazev>/`

### 4. Workflows (Pracovní postupy)

**Účel**: Strukturované sekvence kroků, spouštěné uživatelem přes `/příkaz`.

**Formát**: Markdown v `.agent/workflows/` s povinným YAML frontmatter.

```markdown
---
description: Stručný popis co workflow dělá
---

# /nazev – Popis

## Kroky

1. **Krok 1**
   - Instrukce...

2. **Krok 2**
   // turbo
   - Příkaz k auto-spuštění
```

**Spouštění**: Napsat `/nazev-souboru` v Agent chatu (bez `.md`).

**Turbo anotace**:
- `// turbo` nad konkrétním krokem → auto-run jen tohoto `run_command` kroku
- `// turbo-all` kdekoliv v souboru → auto-run VŠECH `run_command` kroků

**⚠️ Bezpečnost**: Turbo obchází schvalovací proces – používat opatrně, ne na produkci.

**Pokročilé**: Workflows mohou volat jiné workflows (chaining/nesting).

### 5. GEMINI.md a AGENTS.md

| Soubor | Účel | Priorita |
|--------|------|----------|
| `GEMINI.md` | Google-specifické globální pravidlo | Vyšší (v Google nástrojích) |
| `AGENTS.md` | Cross-tool standard (Cursor, Claude, atd.) | Nižší |

- Umisťují se do `~/.gemini/` (globální) nebo kořene projektu
- Tip: `ln -s AGENTS.md GEMINI.md` pro single source of truth
- Max 12 000 znaků na soubor

### 6. Best Practices (2025–2026)

1. **Modularizuj** – místo obřího systémového promptu používej malé specializované skills
2. **Progressive disclosure** – těžké dokumentace ukládej do `resources/`, ne do SKILL.md
3. **Artifacts** – nech agenta generovat `implementation_plan.md`, `task.md` pro review
4. **State management** – pro komplexní multi-agent flows používej "Blackboard" pattern (centrální `state.md`)
5. **Verzuj** – `.agent/` verzuj v Gitu, treat as code
6. **Nepiš samozřejmosti** – nepopisuj, co LLM už ví (PEP8, clean code...)
7. **Testuj** – workflows otestuj zavoláním `/nazev` po vytvoření
8. **Description je klíčový** – u rules i skills popisuj jasně kdy a proč se mají aktivovat

### 7. Customizations panel

Přístup: V Agent chat panelu → `...` menu vpravo nahoře → Customizations

Umožňuje:
- Spravovat Rules (přidávat, editovat, nastavovat aktivaci)
- Spravovat Workflows
- Nastavovat aktivační režimy (Always On, Manual, Glob, Model Decision)

## Srovnání formátů – co má YAML frontmatter

| Typ | YAML Frontmatter | Povinné pole |
|-----|-------------------|-------------|
| **Rules** | ✅ ANO | `description` |
| **Skills** | ✅ ANO | `name`, `description` |
| **Workflows** | ✅ ANO | `description` |
| **GEMINI.md** | ❌ NE | – |
| **AGENTS.md** | ❌ NE | – |

## Zdroje

- [antigravity.google/docs/customizations](https://antigravity.google/docs/customizations) – Oficiální dokumentace customizací
- [antigravity.google/docs/skills](https://antigravity.google/docs/skills) – Oficiální dokumentace skills
- [atamel.dev](https://atamel.dev) – Blog s praktickými příklady Antigravity workflows
- [Medium – Antigravity Skills Deep Dive](https://medium.com) – Detailní analýza skill systému a progressive disclosure
- [Reddit r/AntigravityIDE](https://reddit.com) – Komunitní diskuze a best practices
- [augmentcode.com – AGENTS.md specification](https://augmentcode.com) – Cross-tool standard pro AI agent konfigurace

## Závěr a doporučení

Naše `.agent/` struktura potřebovala opravu v sekci Rules:
1. ✅ Struktura `rules/`, `skills/`, `workflows/` – správně
2. ✅ SKILL.md s YAML frontmatter (`name`, `description`) – správně
3. ⚠️ **OPRAVENO**: Rules **MAJÍ mít** YAML frontmatter s `description` – dříve chybně uvedeno jako „bez frontmatter"
4. ✅ Workflows s YAML `description` – správně
5. 💡 Zvážit přidání `GEMINI.md` do kořene projektu pro globální pravidla
6. 💡 Zvážit složky `scripts/`, `examples/` u komplexnějších skills
7. 💡 Pravidelně auditovat – odstraňovat duplikace a nepoužívané soubory
