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

Skilleillä on standardoitu muoto: kansio, jossa on SKILL.md. Anthropic julkaisi Agent Skills -määrittelyn avoimena standardina joulukuussa 2025, ja kesään 2026 mennessä sitä lukee noin neljäkymmentä työkalua — GitHub Copilot, VS Code, Cursor, Codex, Gemini CLI, OpenCode ja muut. Samalla muodolla kirjoitettu skill toimii siis kaikissa niistä.

Pakollisia kenttiä on kaksi: name ja description. Loppu on Markdownia.

---
name: component-generator
description: Luo uusi React-komponentti projektin konventioilla — tyypitetty props-rajapinta, testitiedosto ja barrel-export. Käytä kun pyydetään uutta komponenttia.
---

# Component Generator

## Milloin tätä käytetään
Kun käyttäjä pyytää uutta React-komponenttia.

## Tarvittava konteksti
- Komponentin nimi
- Props-rajapinta
- Mihin tiedosto sijoitetaan

## Vaiheet
1. Luo komponenttitiedosto oikeaan hakemistoon
2. Lisää TypeScript-props-rajapinta
3. Toteuta komponentti projektin konventioilla
4. Luo vastaava testitiedosto
5. Vie se index.ts:stä

## Lopputulos
- Komponenttitiedosto (.tsx)
- Testitiedosto (.test.tsx)
- Päivitetty barrel-export

Miksi description on tärkein rivi koko tiedostossa

Skillit ladataan asteittain (progressive disclosure), kolmessa vaiheessa:

Tästä seuraa yksi käytännön sääntö: agentti valitsee skillin pelkän kuvauksen perusteella, koska muuta se ei ole siinä vaiheessa lukenut. Kuvaus, joka kertoo vain mitä skill tekee (“luo komponentin”), häviää kuvaukselle, joka kertoo myös milloin sitä käytetään (“…käytä kun pyydetään uutta komponenttia”). Sisällöltään loistava skill, jolla on laiska kuvaus, ei aktivoidu koskaan.

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ää.

.claude/skills/                 # tai skills/ — työkalu määrää polun
├── create-component/
│   ├── SKILL.md                 # nimi + kuvaus + ohjeet
│   └── templates/               # valinnaiset liitteet, ladataan vasta tarvittaessa
│       └── component.tsx.hbs
├── create-api-endpoint/
│   └── SKILL.md
├── write-unit-tests/
│   └── SKILL.md
├── code-review/
│   ├── SKILL.md
│   └── checklist.md
└── security-audit/
  └── SKILL.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