Modul 5 – Skills (SKILL.md) för återanvändbara arbetsflöden

OpenCode-utbildningen på AIWiki.se ← Tillbaka till översikten

En skill är ett återanvändbart kompetenspaket för en AI-agent. Det är en Markdown-fil (SKILL.md) som beskriver:

Vad agenten ska kunna göra inom ett visst område
Vilka regler och konventioner som gäller
Eventuell domänspecifik kunskap agenten behöver

Skills är inte AGENTS.md. De är kompletterande:

AGENTS.md	SKILL.md
Styr agentens beteende och behörigheter	Tillför domänkunskap och arbetsflöden
En per katalog/nivå	Många per projekt/team
Alltid laddad i kontexten	Lazy-laddad vid behov
”Vad får agenten göra?”	”Hur ska agenten göra det?”

OpenCode söker efter SKILL.md-filer automatiskt i:

  ~/.opencode/skills/           ← Globala skills (gäller alla projekt)
  ~/projekt/.skills/            ← Projektspecifika skills
  ~/projekt/src/.skills/        ← Komponentspecifika skills

Lazy loading innebär att skills inte laddas in i context window förrän de är relevanta. Agenten läser skill-beskrivningarna (metadata) och bestämmer vilka som behövs baserat på uppgiften.

Det är viktigt ur ett arkitekturperspektiv: context window är en begränsad resurs. Lazy loading innebär att du kan ha ett stort skill-bibliotek utan att varje skill tar upp utrymme i varje session.

---
name: openapi-dokumentation
description: Genererar OpenAPI 3.1-specifikationer från TypeScript-kod. Triggas när
             användaren ber om API-dokumentation, swagger-spec eller endpoint-dokumentation.
version: 1.0.0
author: plattformsteamet
tags: [dokumentation, api, openapi, typescript]
---
 
# Skill: OpenAPI-dokumentation
 
## Syfte
Analysera TypeScript REST API-kod och generera välstrukturerade OpenAPI 3.1-specifikationer.
 
## Regler
 
- Använd OpenAPI 3.1.0 (inte Swagger 2.0).
- Alla endpoints ska ha `summary` och `description`.
- Felresponser dokumenteras med RFC 7807 Problem Details-format.
- Autentisering dokumenteras via `securitySchemes`.
 
## Arbetsflöde
 
1. Identifiera alla route-handlers i kodbasen.
2. Extrahera request/response-typer från TypeScript-typdefinitioner.
3. Generera YAML-specifikation i `docs/api/openapi.yaml`.
4. Validera mot OpenAPI 3.1-schema.
 
## Exempel
 
Input: `src/api/users.ts` med TypeScript-typer
Output: `docs/api/openapi.yaml` med komplett specifikation

Fält	Obligatoriskt	Beskrivning
``name``	Ja	Unikt namn för skillet
``description``	Ja	Kritiskt – agenten använder detta för att avgöra om skillet är relevant
``version``	Nej	Versionshantering av skillet
``author``	Nej	Vem som äger skillet
``tags``	Nej	Kategorisering för sökning och filtrering

Viktig detalj: ``description``-fältet är det agenten läser när den avgör om en skill ska laddas. Skriv den som en trigger-beskrivning – vad ska användaren säga för att den här skillet ska aktiveras? Det är mer ett trigger-mönster än en teknisk specifikation.

---
name: typescript-konventioner
description: Tillämpas när TypeScript-kod skrivs eller granskas. Innehåller teamets
             kodstandarder, namnkonventioner och arkitekturmönster.
tags: [typescript, kodkvalitet, standards]
---
 
# TypeScript-konventioner
 
## Namngivning
- Interfaces: PascalCase med I-prefix (`IUserService`)
- Types: PascalCase utan prefix (`UserResponse`)
- Konstanter: SCREAMING_SNAKE_CASE
- Privata metoder: camelCase med underscore-prefix (`_validateUser`)
 
## Strukturregler
- Max 200 rader per fil
- En export per fil (default export)
- Dependency injection via konstruktor, inte global state
 
## Förbjudet
- `any` utan explicit kommentar om varför
- `// @ts-ignore` utan JIRA-ticket i kommentaren
- Direkt DOM-manipulation i service-klasser

---
name: datamodell-v2
description: Används vid arbete med databasmodeller, migrationer eller ORM-kod.
             Innehåller den aktuella datamodellen och relationer för v2 av produkten.
tags: [databas, orm, datamodell, migration]
---
 
# Datamodell v2
 
## Entiteter och relationer
 
User 1─── N Order
Order 1─── N OrderItem
OrderItem N─── 1 Product
 
## Namnkonventioner i databasen
- Tabeller: snake_case plural (`order_items`)
- Primärnycklar: `id` (UUID)
- Timestamps: `created_at`, `updated_at` (alltid present)
- Soft delete: `deleted_at` (nullable)
 
## ORM-regler
Vi använder Drizzle ORM. Schema definieras i `src/db/schema/`.
Kör aldrig direkta SQL-queries – använd alltid ORM-lagret.

För team och organisationer är ett centralt skill-bibliotek ett kraftfullt mönster. Istället för att varje repo duplicerar samma kodkonventioner, refererar alla repos till ett delat bibliotek:

organisation/
├── skill-bibliotek/             ← Separat repo
│   ├── typescript-standards/
│   │   └── SKILL.md
│   ├── api-design/
│   │   └── SKILL.md
│   ├── security-patterns/
│   │   └── SKILL.md
│   └── databas-konventioner/
│       └── SKILL.md
├── projekt-a/
│   └── .skills/ → symlink eller git submodule till skill-bibliotek
└── projekt-b/
    └── .skills/ → symlink eller git submodule till skill-bibliotek

Fördelen: en ändring i kodstandarden sprids till alla projekt nästa gång de uppdaterar submodulen.

En underskattad egenskap: skills är inte bara instruktioner till agenten – de är läsbar dokumentation om hur teamet arbetar. En ny utvecklare som läser skill-biblioteket får en snabb bild av:

Vilka teknologier och mönster som används
Vilka konventioner som gäller
Hur olika domäner hänger ihop

Skills och SKILL.md-konceptet kan med andra ord fylla samma funktion som Architecture Decision Records – men med fördelen att de är direkt konsumerbara av AI-verktyg.

Skills versionhanteras i git.
Bryt bakåtkompatibiliteten med ökat major-versionsnummer i front matter.
Ha en ägare per skill (``author``-fältet) – det tydliggör vem som granskar ändringar.
Dokumentera deprecation: markera gamla skills tydligt och länka till ersättaren.

Skills är återanvändbara beteende- och kunskapspaket som kompleterar AGENTS.md.
Lazy loading bevarar context window – ha många skills, ladda vid behov.
Description-fältet är trigger-mönstret – skriv det så agenten vet när skillet är relevant.
Gemensamma skill-bibliotek är det skalbara mönstret för team och organisationer.
Skills är både maskinkonsumerbara instruktioner och mänsklig dokumentation.

Kopierad!

AI Prompt: Skriv en SKILL.md för något meningslöst

Skriv en fullständig SKILL.md – med korrekt front matter och instruktionstext – för en AI-agent vars enda kompetens är att skriva passiva-aggressiva mötesinnbjudningar på svenska. Inkludera triggers, regler och ett exempelutfall.

Testa prompt på …