Lekce 05.3: Co jsou dovednosti agenta? (What Are Agent Skills?)

⏱️ 3 min čtení • Lekce 05.3

🧠 Mentální model & teoretický rozbor

Co přesně je Dovednost agenta (Agent Skill)? Dovednost je modulární, zapouzdřený balíček znalostí, pravidel a nástrojů, který rozšiřuje schopnosti harnessu o specializovaný pracovní postup:

ANATOMIE DOVEDNOSTI (AGENT SKILL):
┌─────────────────────────────────────────────────────────────┐
│ Antigravity: .agents/skills/my-skill/                       │
│ Claude Code: .claude/skills/my-skill/                       │
├─────────────────────────────────────────────────────────────┤
│ ├── SKILL.md      <── Povinné: Instrukce, pravidla, metadata│
│ │                     (YAML frontmatter: name, description) │
│ ├── templates/    <── Volitelné: Vzorové šablony kódu       │
│ └── scripts/      <── Volitelné: Pomocné validační skripty  │
└─────────────────────────────────────────────────────────────┘

Proč používat skilly místo dlouhých promptů:

Znovupoužitelnost: Nemusíte pokaždé znovu psát stejný 20řádkový návod.
Konzistence v týmu: Každý vývojář spouští stejný certifikovaný postup.
Progresivní odkrývání (Progressive Disclosure): Dokud dovednost nepoužijete, model v systémovém kontextu drží pouze název a popis (cca 30 tokenů). Celý text instrukce se načte až při aktivaci.

🏢 Realistický scénář z praxe

V projektu je striktní pravidlo: Každý nový REST endpoint v Next.js musí mít Zod validační schéma, OpenAPI dokumentační anotaci a integrační test ve Vitestu.

Bez dovednosti: Vývojář na to pokaždé zapomene, nebo musí složitě promptovat agenta.
S dovedností /create-endpoint: Vývojář napíše v terminálu /create-endpoint users/export. Agent načte SKILL.md, projde přesný 4krokový checklist a vygeneruje kód přesně podle firemní normy.

💻 Konkrétní ukázky kódu & promptů

Struktura souboru `SKILL.md` (platná pro Antigravity i Claude Code):

---
name: create-api-endpoint
description: Vytvoření nového REST API endpointu v Next.js podle firemních standardů
---

# Tvorba API Endpointu

Při vytváření nového endpointu VŽDY postupuj podle těchto kroků:
1. Vytvoř Zod validační schéma pro request body v `src/schemas/`.
2. Napiš selhávající integrační test v `src/app/api/.../__tests__/route.test.ts`.
3. Implementuj samotný handler v `src/app/api/.../route.ts`.
4. Spusť validaci: `pnpm vitest run route.test.ts`.

⚠️ Analýza selhání & Anti-patterns

Chyba: Příliš obecná dovednost („do-everything skill“)

Vytvořit dovednost s názvem code-helper, která obsahuje 50 nesouvisejících tipů pro CSS, SQL, Docker i testy.

Dovednost ztrácí zaměření a plýtvá kontextem.
Pravidlo: Jedna dovednost = jeden konkrétní, úzce vymezený inženýrský úkol.

🛠️ Inženýrský postup krok za krokem (Playbook)

Identifikujte činnost, kterou v projektu opakujete každý týden (např. přidání DB migrace, vytvoření nové komponenty, příprava release PR).
Vytvořte složku .agents/skills/[nazev]/ (pro Antigravity) nebo .claude/skills/[nazev]/ (pro Claude Code).
Zapište pravidla a kroky do SKILL.md s YAML hlavičkou obsahující name a description.

🧪 Praktické cvičení (Hands-on Lab)

Úkol:

Vytvořte svou první dovednost v repozitáři.

Kroky:

Vytvořte .agents/skills/add-test/SKILL.md (případně .claude/skills/add-test/SKILL.md).
Zadejte do něj instrukci pro tvorbu unit testu ve vašem testovacím frameworku (Vitest / Jest).
Spusťte agy (nebo claude) a vyvolejte dovednost: /add-test src/utils/slugify.ts. Sledujte výsledek!