Trasformare un documento in una skill

Tutorial · 6 min di lettura

Le conoscenze che vuoi dare a un agente di solito sono già scritte da qualche parte: un PDF di onboarding, una guida di stile in Word, un runbook in Markdown. A mancare non sono le conoscenze. È che un documento è scritto per una persona che lo legge dall'inizio alla fine, mentre una skill deve funzionare per un agente che la carica a metà di un compito e deve agire.

Skilnu può fare la prima passata di questa conversione. Carica un documento e ottieni una bozza di SKILL.md: il modello mentale di fondo, le definizioni, le indicazioni, ristrutturati in istruzioni. Non viene pubblicato nulla. La leggi, correggi ciò che non va e pubblichi quando sei soddisfatto, esattamente come per qualsiasi altra skill.

1. Carica il documento

Nell'applicazione apri + New skill e fai clic su Draft from a document, accanto a «Carica SKILL.md». Scegli il file e attendi: richiede più tempo del resto dell'applicazione, perché occorre leggere e riscrivere un intero documento.

Questi formati funzionano: .pdf, .docx, .txt, .md, .markdown, .rst e .adoc.

Tutto il resto viene rifiutato prima ancora del caricamento. Se hai un formato che non è in questo elenco, esportalo prima in PDF: quella strada è ben coperta.

2. Invia una sezione, non una biblioteca

C'è un limite di circa 40.000 caratteri di testo estratto, all'incirca un capitolo lungo. Oltre quella soglia il caricamento viene rifiutato anziché troncato in silenzio: una skill redatta dai primi 40.000 caratteri di un libro di 300 pagine, consegnata come se venisse dal libro intero, sarebbe peggio di un errore.

È meno limitante di quanto sembri, perché ciò che rende buona una skill è esattamente ciò che ci sta dentro: un argomento coerente. «I nostri standard di revisione del codice» è una skill. «L'intero manuale di ingegneria» è una cartella piena. Se hai un documento voluminoso, dividilo per capitoli e redigi ciascuno separatamente: otterrai skills migliori di quelle che una passata unica avrebbe comunque prodotto.

3. I PDF scansionati vanno prima passati all'OCR

Un PDF che in realtà è una serie di fotografie delle pagine non contiene testo da estrarre, quindi la bozza torna con un messaggio che lo spiega anziché come skill vuota. Passalo prima in un qualsiasi strumento OCR — la maggior parte delle applicazioni PDF ha «riconosci testo» integrato — e carica la versione consultabile.

Un modo rapido per capirlo: apri il PDF e prova a selezionare una frase. Se non ci riesci, è un'immagine.

4. Leggi la bozza con attenzione

La bozza arriva nel modulo di composizione, con nome e descrizione compilati dal suo stesso frontmatter. È una prima passata di un modello che ha letto il tuo documento una volta: leggila come leggeresti il primo tentativo di un collega capace, non come un lavoro finito.

Tre cose vale sempre la pena verificare:

Ha conservato i dettagli concreti? Commands, thresholds, names of internal tools, the actual numbers. These are the most useful part of a skill and the easiest thing to lose when prose gets condensed.

Si è inventato qualcosa? The draft is told to stay inside what the document supports, but if your document was vague somewhere, check that the draft was vague in the same place rather than confidently filling the gap.

Sono istruzioni o è un riassunto? The failure mode to watch for is a draft that describes what the document says instead of telling the agent what to do. If a section reads like a book report, rewrite it as a rule.

5. Pubblicala

Modifica il modulo finché sei soddisfatto, poi pubblica normalmente. Da quel momento è una skill come le altre: può essere versionata, altre skills possono dipenderne, puoi condividerla con la tua squadra e aggiungerla alla tua libreria MCP.

Farlo da un agente

Lo stesso flusso è disponibile via MCP, come due strumenti, perché tra l'uno e l'altro il file deve raggiungere l'archiviazione. Chiedi un URL di caricamento, invia i byte, poi chiedi la bozza:

get_document_upload_url(filename="handbook.pdf")
  -> { upload_url, document_key }

PUT the file's bytes to upload_url
  (no auth header -- the URL is already signed)

draft_skill_from_document(document_key=...)
  -> { name, description, skill_md }

La versione per agenti accetta un argomento instructions in più che il modulo web non espone, ed è davvero utile qui: «concentrati sul capitolo 3», «scrivilo per chi è alle prime armi», «conserva tutti gli esempi di codice». Si aggiunge alle tue istruzioni di compilazione permanenti invece di sostituirle.

Come ovunque, draft_skill_from_document si limita a creare una bozza. Pubblicarla è una chiamata publish_skill separata, quindi un agente non può trasformare un documento in una skill pubblicata senza che tu abbia prima visto la bozza.

Quanto costa

Ogni bozza consuma un'unità della tua quota giornaliera di compilazione, sul modello che hai scelto nelle Impostazioni: lo stesso budget usato dalla pubblicazione con compilazione. Una bozza fallita che non ha mai raggiunto il modello, come un file non supportato o uno oltre il limite di lunghezza, non consuma nulla.

Il documento che carichi è spazio temporaneo. Viene eliminato non appena la bozza è generata, con successo o meno, e ciò che in qualche modo sopravvive sparisce entro 24 ore. Non fa mai parte della skill pubblicata: solo la bozza che rivedi ne fa parte.

A cosa serve davvero

I candidati migliori sono documenti che già codificano un modo di lavorare: una guida di stile, una checklist di revisione, un runbook per gli incidenti, il capitolo di un libro tecnico che vuoi far applicare a un agente anziché citare. Materiale di consultazione privo di procedura — un dump di API, un glossario, un foglio di calcolo esportato in PDF — dà una skill scarna, perché nella fonte non c'è alcuna indicazione da estrarre.

Una buona prova prima di caricare: qualcuno potrebbe leggere questo documento e poi fare qualcosa in modo diverso? Se sì, ne uscirà una skill. Se è solo qualcosa da consultare, probabilmente no.