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

**Datum**: 2026-04-03
**Dotazy**: "Antigravity IDE agent folder structure rules skills workflows", "SKILL.md frontmatter format", "progressive disclosure GEMINI.md AGENTS.md best practices", "turbo annotation specification"

## 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** (pasivní pravidla), **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, čímž šetří context window.

## Detailní zjištění

### 1. Struktura .agent složky

```
<workspace-root>/
├── .agent/                          # Workspace-level konfigurace
│   ├── rules/                       # Pasivní pravidla (vždy aktivní)
│   │   └── *.md                     # Prosté markdown soubory
│   ├── 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**: Pasivní omezení vkládaná do systémového kontextu agenta. Fungují jako „guardrails".

**Formát**: Prosté `.md` soubory v `.agent/rules/` – **žádný YAML frontmatter**.

**Obsah**: Instrukce v přirozeném jazyce, typicky jako odrážky.

**Aktivační režimy** (nastavitelné v Customizations panelu IDE):
- **Always On** – platí pro všechny úkoly
- **Manual** – aktivace přes `@mention` v chatu
- **Model Decision** – agent sám rozhodne na základě popisu
- **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

**Hierarchie globálních pravidel**: `GEMINI.md` má přednost před `AGENTS.md`. Globální rules v `~/.gemini/GEMINI.md`.

### 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í

### 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)

## 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 je v souladu se specifikací. Doporučení:
1. ✅ Struktura `rules/`, `skills/`, `workflows/` – správně
2. ✅ SKILL.md s YAML frontmatter – správně
3. ✅ Rules jako prosté .md bez frontmatter – správně
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
