Scrivi la tua prima skill

Impara l'anatomia, studia un esempio revisionato, genera il file qui sotto.

Abstract

Una skill è un metodo in testo semplice che il lettore consegna a un assistente AI. Scriverne una assomiglia più a redigere una procedura per un collega nuovo e sveglio che a smanettare con i prompt: definisci gli input, i passi, il contratto di uscita e le regole che reggono quando le cose diventano ambigue. Questo documento insegna l'anatomia, mostra un esempio revisionato, elenca cosa viene respinto in revisione e si chiude con un editor che genera un file conforme alla specifica.

1.Anatomia di una skill

1. Frontmatter. name in kebab-case, uguale al nome del file. description svolge due compiti in un paragrafo: cosa fa la skill e — soprattutto — quando attivarla ("Use when asked to…"). Gli assistenti scelgono le skill da questo campo; una descrizione vaga produce una skill che dorme per sempre. Versione, licenza e autori chiudono il blocco.
2. Paragrafo di identità. Due o tre frasi dopo il titolo, in seconda persona: chi diventa l'assistente e su cosa rifiuta di transigere. È voce e standard in un respiro solo: "You write commit messages worthy of the permanent record."
3. Inputs. L'elenco numerato di ciò che la skill richiede, con i campi obbligatori segnati e una regola per i buchi (chiedi e fermati, oppure procedi con assunzioni dichiarate). Chiedi una volta sola — una skill che interroga a raffica sfinisce chi la usa.
4. Method. Passi numerati, ciascuno decidibile: un'istruzione che l'assistente può seguire o verificare, con le regole di giudizio esplicite ("quando X supera Y, fai Z"). I passi che dicono "sii accurato" restituiscono al caso la parte difficile.
5. Output format. Il contratto: sezioni, ordine, lunghezze dove contano. Due esecuzioni della stessa skill devono produrre la stessa forma — la sezione del formato è ciò che rende una skill ripetibile invece che improvvisata.
6. Rules. Gli invarianti che sopravvivono a ogni caso limite: cosa viene rifiutato, cosa viene etichettato, cosa degrada e come. Dichiara come si comporta la skill quando manca una capacità — "segna N.D. con una motivazione" vale più di un successo indovinato.

2.Un esempio revisionato, annotato

---
name: honest-status-report
description: Status reports that declare failures,
  blockers and partial results as visibly as successes.
  Use when asked for a status update, a progress report,
  or an end-of-task summary.
---✓ review — name matches filename; description states the trigger ("Use when…"): the assistant knows when to wake this skill
2. Classify each item, strictly:
   - Done & verified — completed AND checked.
   - Failed / errored — attempted, went wrong.
   - Silently skipped — planned, then untouched.✓ review — each category is decidable: two readers classify the same item the same way
The order is fixed: problems before achievements.✓ review — an output contract, stated as a rule: the shape survives every run

3.Cosa viene respinto in revisione

Ogni proposta viene letta riga per riga da un maintainer, dopo che i controlli automatici sono passati. Questi sono i motivi di rifiuto ricorrenti — scrivi tenendo aperta questa lista:

1. REJECTED — Passi non decidibili. "Analizza con attenzione", "sii utile", "usa il buon senso" senza alcun criterio. Un passo si merita il suo posto quando l'assistente può dire se lo ha seguito.
2. REJECTED — Degradazione assente. Il metodo dà per scontati accesso al web, esecuzione di codice o strumenti sui file, e tace su cosa succede su un assistente che ne è privo. Dichiara il ripiego.
3. REJECTED — Contenuto nascosto o codificato. Blob base64, caratteri a larghezza zero, istruzioni per scaricare contenuti remoti a runtime. Il patto è markdown leggibile in chiaro: quello che il lettore vede è quello che l'agente esegue.
4. REJECTED — Vie di esfiltrazione. Passi che spediscono i dati dell'utente da qualche parte. Una skill trasforma ciò che riceve, sul posto.
5. REJECTED — Formule legate a un fornitore. "Usa lo strumento WebFetch", "chiama Code Interpreter". Nomina le capacità ("quando è disponibile l'accesso live al web") e la skill funziona su ogni assistente.
6. REJECTED — Marketing dentro il metodo. Superlativi sulla skill stessa, link a prodotti, autopromozione. Il metodo parla attraverso i suoi passi.
7. REJECTED — Contratto di uscita mancante. Dieci passi di metodo affilati, e zero parole su che aspetto ha il risultato. La sezione del formato è metà del valore.

4.L'editor — genera il tuo file

Compila le sezioni; l'editor assembla un .md conforme alla specifica. Tutto gira dentro questa pagina — la tua bozza non tocca alcun server. Il modulo resta in inglese: quello che scrivi diventa la skill, e le skill di questa libreria sono in inglese.

5.Proponila

1. Prima esegui la tua skill su un caso vero — il risultato di prova ti dice dove il metodo è sottile.
2. Forka la libreria, aggiungi il file sotto skills/<category>/<name>.md, apri una pull request per skill.
3. Firma ogni commit con git commit -s. Quel flag aggiunge la riga Signed-off-by con cui certifichi di poter rilasciare il lavoro sotto Apache-2.0 — il Developer Certificate of Origin. Un controllo obbligatorio lo verifica, quindi la PR si unisce quando c'è. Hai già committato senza? git commit --amend -s --no-edit per l'ultimo, git rebase --signoff main per diversi, poi git push --force-with-lease.
4. Girano i controlli automatici, poi un maintainer lo legge riga per riga. Il credito finisce nel file stesso.