Skills — AI:n kyvykkyyksien dokumentointi

Edellisessä oppitunnissa loimme AGENTS.md:n, joka kertoo agentille miten toimia. Nyt opimme luomaan Skills-dokumentaation, joka kertoo agentille mitä se osaa tehdä ja tekee nämä kyvykkyydet löydettäviksi.

Miksi Skills-dokumentaatio?

AI-agentit ovat tehokkaimmillaan kun niiden kyvykkyydet ovat:

• Löydettäviä — agentti tietää mitä se osaa
• Toistettavia — sama skill tuottaa johdonmukaisen tuloksen
• Dokumentoituja — kehittäjä tietää mitä pyytää

Skills-järjestelmän perusteet

Skillin anatomia

Jokainen skill koostuu neljästä osasta:

# Skill: Component Generator

## Trigger
User asks to create a new React component

## Context Needed
- Component name
- Props interface
- Where to place the file

## Steps
1. Create component file in correct directory
2. Add TypeScript props interface
3. Implement component with project patterns
4. Create corresponding test file
5. Export from index.ts

## Output
- New component file (.tsx)
- Test file (.test.tsx)
- Updated barrel export

Slash-komennot ja Skillit

Moderni AI-työkalut tukevat slash-komentoja (/command), jotka ovat käyttäjän näkökulmasta suorin tapa käynnistää skill:

Skillin luominen käytännössä

Vaihe 1: Tunnista toistuva tehtävä

Hyvä skill-kandidaatti on tehtävä, joka:

• Toistuu usein (viikoittain tai useammin)
• Noudattaa selkeää kaavaa
• Tuottaa ennustettavan tuloksen
• Vaatii useamman vaiheen

Vaihe 2: Dokumentoi vaiheet

# Skill: Create API Endpoint

## Trigger
/api <resource-name> <method>

## Context
- Resource name (e.g., "users", "products")
- HTTP method (GET, POST, PUT, DELETE)
- Request/response schema if complex

## Steps
1. Create route file: app/api/<resource>/route.ts
2. Add Zod validation schema for request body
3. Implement handler with error handling
4. Add RLS policy if needed
5. Create integration test
6. Update API documentation

## Patterns to Follow
- Use Next.js App Router convention
- Validate with Zod, not manual checks
- Return consistent error format: { error: string, code: number }
- Log all mutations

## Example
/api products POST creates:
- app/api/products/route.ts (POST handler)
- lib/validations/product.ts (Zod schema)
- __tests__/api/products.test.ts

Vaihe 3: Testaa ja iteroi

Jokainen skill paranee käytössä. Ensimmäinen versio on harvoin täydellinen — testaa skill 3–5 kertaa ja päivitä dokumentaatiota havaintojen perusteella.

Skills-kirjasto

Hyvin organisoitu projekti ylläpitää skills-kirjastoa — kokoelmaa dokumentoituja kyvykkyyksiä, jotka kaikki tiimin jäsenet voivat hyödyntää.

skills/
├── development/
│   ├── create-component.md
│   ├── create-api-endpoint.md
│   └── create-migration.md
├── testing/
│   ├── write-unit-tests.md
│   ├── write-e2e-tests.md
│   └── generate-test-data.md
├── documentation/
│   ├── document-api.md
│   └── update-changelog.md
└── review/
  ├── code-review.md
  └── security-audit.md

Skillien löydettävyys

AI löytää skillit parhaiten kun ne ovat:

1. Nimetty selkeästi — Kuvaava nimi, ei lyhenteitä
2. Oikeassa paikassa — Vakiokansio (skills/ tai docs/skills/)
3. Indeksoitu — Skills-hakemisto tai manifesti
4. Kontekstissa — AGENTS.md viittaa skills-kansioon

Yhteenveto

• Skills ovat AI:n dokumentoituja, toistettavia kyvykkyyksiä
• Jokainen skill sisältää triggerin, kontekstin, vaiheet ja odotetun tuloksen
• Slash-komennot ovat käyttäjäystävällisin tapa käynnistää skillejä
• Skills-kirjasto kasvaa orgaanisesti projektin edetessä
• Seuraavaksi opimme tehokkaan promptauksen ja mallien valinnan periaatteet