Lekce 05.4: Napsání vlastní dovednosti (Write A Skill)

⏱️ 2 min čtení • Lekce 05.4

🧠 Mentální model & teoretický rozbor

Napsání špičkové dovednosti vyžaduje aplikaci inženýrských principů specifikace. Dovednost nesmí být pouhým popisem toho, co se má stát, ale přesným algoritmem kroků s ošetřením chyb:

ANATOMIE PRODUKČNÍ DOVEDNOSTI:
1. YAML Frontmatter (Metadata pro automatický objev harnessu)
2. Cíl a vstupní parametry
3. Předpoklady (Které soubory musí existovat)
4. Sekvence kroků (Step-by-Step Playbook)
5. Verifikační podmínka (Jak agent pozná, že je hotovo)

---

🏢 Realistický scénář z praxe

V týmu dochází k častým chybám při vytváření tRPC procedur – vývojáři zapomínají na kontrolu uživatelských rolí v middleware. Seniorní inženýr napíše dovednost add-trpc-procedure, která agentovi striktně nařizuje použít chráněnou proceduru protectedProcedure a vygenerovat test pro neautentizovaného uživatele. Od té chvíle je každá nová procedura stoprocentně zabezpečená.

---

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

Kompletní produkční SKILL.md pro novou tRPC proceduru:

---
name: add-trpc-procedure
description: Bezpečné přidání nové procedury do tRPC routeru s testem oprávnění
---

# Postup přidání tRPC procedury

Při přidávání procedury dodržuj tento postup:
1. **Analýza vstupu**: Vytvoř Zod validační schéma v `src/server/schemas/`.
2. **Volba procedury**:
   - Veřejná data: použij `publicProcedure`.
   - Uživatelská data: použij `protectedProcedure` (vyžaduje přihlášenou session).
   - Správa: použij `adminProcedure` (ověřuje `role === 'ADMIN'`).
3. **Implementace**:
   Zapiš logiku do příslušného routeru v `src/server/routers/`.
4. **Test**:
   Vytvoř test v `src/server/routers/__tests__/`, který ověří:
   - Úspěšné volání s platnými daty.
   - Odmítnutí s chybou `UNAUTHORIZED`, pokud chybí session.
5. **Verifikace**:
   Spusť: `pnpm test -- <nazev_routeru>.test.ts`.

---

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

Chyba: Chybějící verifikační krok v dovednosti

Pokud dovednost končí slovy „Implementuj kód,“ agent provede editaci a skončí. Pokud kód nefunguje, dozvíte se to až vy.

• Pravidlo: Posledním krokem každé dovednosti musí být spuštění testu nebo kompilátoru!

---

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

1. Sepište kroky, které sami děláte při tvorbě dané entity.
2. Zabalte je do markdown souboru SKILL.md ve složce .agents/skills/<nazev>/ (pro Antigravity) nebo .claude/skills/<nazev>/ (pro Claude Code).
3. Otestujte dovednost na reálném úkolu v agy nebo claude.
4. Odlaďte případná nejasná místa a commitněte do repozitáře v Gitu.

---

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

Úkol:

Napište dovednost pro tvorbu nové React/Next.js komponenty podle vašich standardů (Tailwind CSS, TypeScript interface pro Props, Vitest test komponenty). Vyzkoušejte její spuštění v agy i claude.

---