Design di una custom skill in Copilot Cowork

Dallo use case al file SKILL.md: come insegnare un nuovo mestiere al tuo collega digitale

📋 Scheda Tecnica

Campo Valore
Ultimo aggiornamento 04/07/2026
Testato su Copilot Cowork – Frontier preview (aggiornato 30/03/2026)
Prerequisiti Licenza M365 Copilot + iscrizione Frontier + OneDrive attivo
Livello Intermedio — richiede familiarità con Markdown e YAML
Tempo stimato 20 minuti di lettura + 30 minuti di setup
Limiti noti Funzionalità Frontier in preview: soggetta a modifiche. Custom skills non validate da Microsoft — verifica sempre l’output
Sezione KB KB Cowork

Campo	Valore
Ultimo aggiornamento	04/07/2026
Testato su	Copilot Cowork – Frontier preview (aggiornato 30/03/2026)
Prerequisiti	Licenza M365 Copilot + iscrizione Frontier + OneDrive attivo
Livello	Intermedio — richiede familiarità con Markdown e YAML
Tempo stimato	20 minuti di lettura + 30 minuti di setup
Limiti noti	Funzionalità Frontier in preview: soggetta a modifiche. Custom skills non validate da Microsoft — verifica sempre l’output
Sezione KB	KB Cowork

Ricerca aggiornata eseguita il 04/07/2026 — fonti: Microsoft Learn Copilot Cowork FAQ (30/03/2026), GitHub Copilot SDK documentation – Custom Skills (2026).

Copilot Cowork ha 13 skill built-in — Word, Excel, PowerPoint, PDF, Email, Scheduling, Calendar Management, Meetings, Daily Briefing, Enterprise Search, Communications, Deep Research e Adaptive Cards — ma il vero salto di produttività arriva quando gli insegni qualcosa che nessuno ha ancora documentato: il tuo flusso di lavoro specifico. Le custom skill sono file Markdown che Cowork legge all’avvio di ogni conversazione, trasformando istruzioni testuali in comportamenti replicabili e delegabili. Questo articolo percorre l’intero processo: dall’identificazione del use case giusto, alla struttura del file SKILL.md, fino al prompt operativo che lo attiva in modo affidabile. [learn.microsoft.com]

1. Introduzione — Quando ho capito che le skill built-in non bastavano

L’altro giorno stavo preparando il solito report settimanale per un cliente: raccogliere le attività dalla settimana, sintetizzarle per categoria, allegare i KPI da un foglio Excel, formattare il tutto secondo un template aziendale e inviarlo via email ogni venerdì alle 17. Un’operazione che facevo ogni settimana, sempre uguale, sempre manuale.

La prima volta che ho usato Cowork per delegarla, ci ho messo più tempo a spiegargliela che a farla io stesso. La seconda settimana, stesso problema. Alla terza ho pensato: perché non scrivergli un manuale una volta sola?

Puoi creare fino a 20 custom skill posizionando file SKILL.md nella cartella OneDrive /Documents/Cowork/Skills/. Ogni file contiene un blocco YAML frontmatter con nome e descrizione, seguito dalle istruzioni della skill. Copilot Cowork scopre automaticamente le custom skill all’avvio di ogni conversazione. [learn.microsoft.com]

Questo è il principio. La pratica è un po’ più articolata — e vale la pena capirla bene.

2. Background — Come funziona il meccanismo delle custom skill

Risposta diretta: Una custom skill è un file Markdown che Cowork legge all’avvio di ogni sessione. Le istruzioni contenute nel file diventano parte del contesto attivo di Cowork per tutta la conversazione.

Il modello mentale giusto

Una custom skill non è una macro, non è un plugin e non è un agente separato. È più simile a una scheda di lavoro: un documento che spiega a Cowork come affrontare un tipo specifico di compito, con quali regole, quale output atteso e quali passi seguire.

Una skill è una directory con un nome che contiene un file SKILL.md — un documento Markdown che fornisce istruzioni. Quando caricata, il contenuto della skill viene iniettato nel contesto della sessione. Le skill permettono di: pacchettizzare l’expertise di dominio in moduli riutilizzabili; condividere comportamenti specializzati tra progetti; organizzare configurazioni di agente complesse; abilitare/disabilitare capacità per sessione. [github.com]

Dove vivono le skill: la struttura su OneDrive

			
OneDrive/
└── Documents/
    └── Cowork/
        └── Skills/
            ├── weekly-report/
            │   └── SKILL.md
            ├── meeting-summary/
            │   └── SKILL.md
            └── incident-report/
                └── SKILL.md

		

Ogni skill è una sottocartella con il suo SKILL.md dentro. Il nome della cartella è il nome tecnico della skill — sceglilo descrittivo e senza spazi.

3. Analisi — Anatomia di un file SKILL.md

3.1 La struttura di base

Un file SKILL.md è un documento Markdown con YAML frontmatter opzionale. I campi del frontmatter sono: name — l’identificatore della skill; description — una breve descrizione di cosa fa la skill. Il corpo Markdown contiene le istruzioni che vengono iniettate nel contesto della sessione quando la skill è caricata. [github.com]

—

name: weekly-report

description: Genera il report settimanale per i clienti

—

# Weekly Report

## Obiettivo

Produce un report settimanale strutturato partendo dalle attività della settimana.

## Passi

1. Chiedi all’utente il periodo di riferimento (default: settimana corrente)

2. Cerca nelle email e in Teams le attività per categoria: Sviluppo, Riunioni, Deliverable

3. Recupera i KPI dal file Excel allegato o da SharePoint (chiedi il percorso)

4. Formatta il report secondo il template: sezione Sommario, sezione Attività, sezione KPI

5. Prima di inviare, mostra un’anteprima all’utente e attendi approvazione

## Regole

– Tono: professionale, terza persona

– Lunghezza: massimo 1 pagina A4

– NON inviare senza approvazione esplicita dell’utente

– Se mancano dati, chiedi — non inventare

Questo è già un SKILL.md funzionante. Ma un buon design richiede qualche ragionamento in più.

3.2 Le cinque componenti di una skill ben disegnata

Nella mia esperienza, le custom skill che funzionano davvero hanno sempre cinque elementi:

1. Obiettivo chiaro (1-2 frasi)

Dice a Cowork cosa deve fare questa skill e quando usarla. Evita ambiguità.

## Obiettivo

Questa skill si attiva quando l’utente chiede di preparare o inviare

il report settimanale al cliente. Non usarla per altri tipi di report.

2. Input attesi (cosa raccogliere prima di iniziare)

Cowork è bravo a fare domande — aiutalo a sapere cosa chiedere.

## Input necessari

– Periodo di riferimento (default: lunedì-venerdì della settimana corrente)

– Nome del cliente (se multipli, chiedi quale)

– File KPI allegato o percorso SharePoint

– Lista delle attività manuale (opzionale: se non disponibile, cerca in email/Teams)

3. Passi operativi (la sequenza di azioni)

Sequenza numerata, azioni atomiche, nessuna ambiguità su chi fa cosa.

4. Formato di output (cosa produrre e come)

Specifica il formato file, la struttura del documento, il tono, la lunghezza.

## Output

– File: Word (.docx), nome: “Report_[Cliente]_[Data].docx”

– Struttura: Sommario esecutivo (5 righe max) → Attività → KPI → Next steps

– Tono: professionale, italiano, terza persona

– Salva in: SharePoint/Reports/[Anno]/[Cliente]/

5. Guardrail espliciti (cosa NON fare)

Prima che Copilot Cowork esegua un’azione sensibile come inviare un’email o postare in Teams, mostra un prompt di approvazione. Le approvazioni per azioni a rischio medio e alto includono un indicatore del livello di rischio. Ma le custom skill possono aggiungere un ulteriore livello di cautela: [learn.microsoft.com]

## Guardrail

– NON inviare l’email senza mostrare un’anteprima all’utente

– NON accedere a cartelle diverse da SharePoint/Reports/

– Se il file KPI non è trovato, fermati e chiedi — non procedere con dati stimati

– Chiedi sempre conferma prima di sovrascrivere un file esistente

3.3 I pattern di prompt operativo per attivare la skill

Avere il file SKILL.md perfetto non basta se poi il prompt di attivazione è vago. Ecco i pattern che funzionano meglio:

Pattern 1 — Attivazione diretta per nome

			
Usa la skill weekly-report per preparare il report della settimana per [Cliente X].
Il file KPI è in SharePoint/Reports/2026/ClienteX/KPI_luglio.xlsx

Pattern 2 — Attivazione implicita per descrizione del task

			
Prepara il solito report settimanale per ClienteX. 
Settimana dal 30 giugno al 4 luglio. KPI allegati.

(Cowork riconosce automaticamente la skill corrispondente dalla description nel frontmatter)

Pattern 3 — Attivazione con override di parametri

			
Usa la skill weekly-report ma questa settimana includi anche la sezione 
"Rischi aperti" dopo i KPI. Formato invariato per il resto.

💡 Nella mia esperienza: il Pattern 2 è il più potente perché non richiede di ricordare il nome tecnico della skill. Ma funziona solo se il campo description nel frontmatter è scritto bene — deve rispecchiare il linguaggio naturale con cui un utente descriverebbe il task.

3.4 Limiti da conoscere prima di progettare

Le seguenti limitazioni sono by design: Cowork non può accedere o modificare file memorizzati localmente sul dispositivo — lavora con file in OneDrive e SharePoint. Cowork non può eliminare file o cartelle in OneDrive o SharePoint. Le custom skill create dagli utenti non sono validate da Microsoft — verifica sempre attentamente gli output delle custom skill. [learn.microsoft.com]

Tradotto in implicazioni pratiche per il design:

Limitazione	Impatto sul design della skill
Solo file OneDrive/SharePoint	Specifica sempre percorsi cloud — mai percorsi locali
Nessun delete	Non progettare skill che “puliscono” cartelle — usa archiviazione
Non validata da Microsoft	Aggiungi sempre un passo di revisione umana nel flusso
Max 20 skill attive	Progetta skill generaliste dove possibile — evita la frammentazione
Frontier in preview	Le skill possono smettere di funzionare dopo un aggiornamento — testa spesso

4. Caso d’uso completo — Dalla necessità al SKILL.md pronto

Vediamo un esempio reale dall’inizio alla fine: la skill incident-summary per un team IT.

Step 1 — Definisci il use case

“Ogni volta che si verifica un incident in produzione, devo raccogliere i dettagli, scrivere il summary da inviare agli stakeholder e aggiornare il log su SharePoint. Lo faccio 2-3 volte a settimana, sempre con la stessa struttura.”

Checklist use case valido:

✅ Compito ripetitivo con struttura stabile
✅ Output definito (documento + email)
✅ Input variabile ma tipizzabile (data, severità, servizi coinvolti)
✅ Richiede dati da M365 (email, Teams, SharePoint)
✅ Approvazione umana necessaria prima dell’invio

Step 2 — Mappa gli input e i passi

			
Input:
- Data e ora dell'incident
- Severità (P1/P2/P3)
- Servizi coinvolti
- Cronologia degli eventi (dall'utente o da Teams)
- Root cause (se nota)
- Azioni intraprese
- ETA risoluzione
Passi:
1. Raccoglie input dall'utente (con domande mirate se mancanti)
2. Cerca in Teams le comunicazioni del canale #incidents-prod per il periodo
3. Genera il summary secondo template
4. Mostra anteprima
5. Salva in SharePoint/Incidents/[Anno]/[Mese]/
6. Prepara email per stakeholder (non invia senza approvazione)

		

Step 3 — Scrivi il SKILL.md

			
---
name: incident-summary
description: Prepara il summary di un incident di produzione, 
             aggiorna il log e bozza l'email agli stakeholder
---
# Incident Summary
## Obiettivo
Genera un documento di incident summary strutturato e prepara 
la comunicazione agli stakeholder. Si attiva quando l'utente 
segnala un incident di produzione da documentare.
## Input necessari
Prima di procedere, raccoglie le seguenti informazioni:
- Data e ora di inizio/fine incident (o "ancora aperto")
- Severità: P1 (critico), P2 (alto), P3 (medio)
- Servizi/sistemi coinvolti
- Breve descrizione dell'impatto utente
- Root cause (se nota — altrimenti scrivere "In analisi")
- Azioni intraprese
- ETA risoluzione o stato attuale
Cerca anche in Teams nel canale #incidents-prod le comunicazioni 
relative al periodo indicato per integrare la cronologia.
## Output
### Documento
- Formato: Word (.docx)
- Nome: "Incident_[Severità]_[Data]_[Servizio].docx"
- Salva in: SharePoint/IT/Incidents/[Anno]/[Mese]/
- Struttura:
  1. Executive Summary (5 righe)
  2. Cronologia eventi (tabella: timestamp / evento / responsabile)
  3. Root Cause Analysis
  4. Azioni intraprese
  5. Azioni preventive proposte
  6. Impatto stimato
### Email stakeholder
- Oggetto: "[Severità] Incident Report – [Servizio] – [Data]"
- Destinatari: chiedi all'utente la lista (non usare liste memorizzate)
- Corpo: versione sintetica del summary (max 10 righe)
- Allegato: il documento Word generato
## Guardrail
- NON inviare l'email senza approvazione esplicita dell'utente
- NON inventare dati mancanti — chiedi o scrivi "Non disponibile"
- NON sovrascrivere un documento esistente con lo stesso nome — 
  aggiungi suffisso _v2, _v3
- Se la severità è P1, aggiungi avviso visibile nel documento: 
  "⚠️ INCIDENT CRITICO — Richiede revisione del CISO"

		

Step 4 — Testa con prompt di attivazione

			
Devo documentare un incident P2 di ieri sera.
Dalle 22:15 all'1:30 il servizio di autenticazione 
era degradato per il 30% degli utenti EU.
Root cause: aggiornamento certificato TLS non propagato correttamente.
Usa la skill incident-summary.

		

5. Implicazioni pratiche — Cosa rende una skill davvero utile

Le skill migliori che ho progettato hanno in comune:

Un use case monolitico — una skill = un tipo di task ben definito
Input espliciti — Cowork chiede, non indovina
Guardrail conservativi — meglio chiedere conferma in più che fare un errore autonomo
Output specifico — nome file, percorso di salvataggio, formato: tutto scritto

Gli errori più comuni:

Skill troppo generiche (“aiutami con i report” — inutile)
Skill senza guardrail (“invia l’email” senza approvazione — pericoloso)
Istruzioni ambigue (“formatta bene” — cosa significa “bene”?)
Percorsi locali nel SKILL.md — Cowork non può accedervi

💡 Suggerimento operativo: Prima di scrivere il SKILL.md, fai il task manualmente una volta e prendi nota di ogni decisione che hai preso. Quelle decisioni sono le istruzioni della skill.

6. Conclusioni — Le skill sono documentazione eseguibile

Una custom skill ben progettata è, in fondo, documentazione operativa — ma con una differenza fondamentale rispetto a una procedura scritta nel wiki aziendale: questa la esegue qualcuno.

Il processo di design di una skill mi ha insegnato qualcosa di inaspettato: per scrivere istruzioni chiare per Cowork, devo prima capire davvero come funziona il mio processo. Le skill diventano così uno strumento di chiarezza organizzativa oltre che di automazione.

Le custom skill create dagli utenti non sono validate da Microsoft — verifica sempre attentamente gli output. Questo limite è la responsabilità che accompagna il potere: ogni skill che scrivi è tua — nel senso che ne sei l’autore, il tester e il responsabile. Non una delega cieca, ma una collaborazione consapevole. [learn.microsoft.com]

La vera sfida non è tecnica, ma di design: capire quale compito vale la pena insegnare, e come descriverlo in modo che un sistema AI possa eseguirlo con la stessa cura che ci metteresti tu.

Riferimenti

Microsoft Learn. (30/03/2026). Copilot Cowork common questions (Frontier). Microsoft Corporation. https://learn.microsoft.com/en-us/copilot/microsoft-365/cowork/cowork-faq
GitHub. (2026). Using custom skills with the Copilot SDK. github/docs. https://github.com/github/docs/blob/main/content/copilot/how-tos/copilot-sdk/use-copilot-sdk/custom-skills.md
Microsoft Learn. (20/03/2026). Architettura di protezione dei dati Microsoft 365 Copilot. Microsoft Corporation. https://learn.microsoft.com/it-it/copilot/microsoft-365/microsoft-365-copilot-architecture-data-protection-auditing

Questo articolo fa parte della KB Copilot e Agenti di Argos New Dreams — sezione KB Cowork. Aggiornato il 04/07/2026. Funzionalità in Frontier preview: soggette a modifiche. Per segnalazioni: luca@borio.me