Creare skill Rakenne con lo Skill Workshop

Le skill Rakenne sono flussi di elaborazione documentale che l’agente può eseguire quando gli utenti descrivono un compito. Lo Skill Workshop è un tipo di progetto dedicato che ti permette di creare e pubblicare le tue skill conversando con l’agente — senza codice. Questo tutorial ti guida attraverso l’intero flusso: dalla creazione di un progetto workshop alla pubblicazione di una skill nella biblioteca della tua organizzazione.

Cosa ti serve

• Accesso a un’istanza Rakenne dove puoi creare progetti.
• Un’idea chiara di un flusso di dominio che vuoi trasformare in una skill (es. “redigere verbali da trascrizioni”, “revisione contratti con il nostro playbook”, “creare checklist di conformità dal regolamento X”).

Step 1: Crea un progetto Skill Workshop

1. In Rakenne avvia Crea progetto (o equivalente nella tua UI).
2. Nella scelta del tipo di progetto seleziona Skill Workshop.
3. Assegna un nome al progetto (es. “La mia creazione di skill”) e crealo.

L’area di lavoro viene provisionata con:

• Skill skill-creator — Una skill integrata in .pi/skills/skill-creator/ che guida il flusso di creazione.
• AGENTS.md — Istruzioni che dicono all’agente che questo è un workspace di creazione skill e che le skill vanno in output/.
• output/ — Una directory vuota dove risiederà ogni skill che crei (una sottodirectory per skill).

Usi la stessa area di lavoro che conosci già: chat con l’agente, albero file, anteprima documenti. L’unica differenza è il template e l’obiettivo: produrre skill invece di un singolo documento.

Step 2: Avvia la conversazione di creazione

Apri il progetto e, nella chat, descrivi cosa vuoi costruire. Ad esempio:

• “Voglio creare una skill che trasforma le trascrizioni delle riunioni in note strutturate con decisioni e azioni.”
• “Ci serve una skill che aiuti a redigere valutazioni d’impatto sulla privacy usando il nostro template interno e la PIPEDA.”

L’agente userà la skill skill-creator e non creerà alcun file finché non avrà compreso il tuo flusso. Ti farà domande in modo strutturato (fase Elicit).

Step 3: Rispondi alle domande di elicitation

L’agente chiederà:

1. A cosa serve il flusso — Dominio e compito (es. note di riunione, revisione contratti, conformità).
2. Cosa lo attiva — Quando qualcuno userebbe questa skill (es. “quando l’utente ha una trascrizione e vuole note strutturate”).
3. Quali passaggi coinvolge — La sequenza (es. ricevere input → estrarre decisioni e azioni → confermare ambiguità → produrre documento).
4. Come è l’output — Tipo di documento, sezioni, formato (es. executive summary, log decisioni, action items).
5. Conoscenza di dominio — Regolamenti, standard, template o materiale di riferimento che l’agente deve usare.

Rispondi in linguaggio semplice. L’agente trasformerà le tue risposte in una skill strutturata; non devi conoscere markdown o YAML. Se hai template o documenti di riferimento puoi aggiungerli dopo o descriverli così l’agente può referenziare placeholder.

Step 4: Lascia che l’agente faccia scaffold e scriva la skill

Quando l’agente ha abbastanza informazioni, farà:

1. Scegliere uno slug — Un identificatore kebab-case (es. meeting-notes, contract-review-playbook).
2. Chiamare scaffold_skill — Crea output/{slug}/ con un template SKILL.md e opzionalmente le directory references/ e assets/.
3. Modificare SKILL.md — Compila i passaggi del flusso, i link ai file di riferimento e il linguaggio di trigger nella description.
4. Aggiungere file reference e asset — La conoscenza di dominio va in references/; template o esempi di output in assets/.

Tutto avviene nella chat; puoi seguire l’albero file e aprire i file per controllare. Le skill sono scritte solo sotto output/.

Step 5: Valida e affina

Prima di considerare la skill pronta, l’agente eseguirà validate_skill. Controlla:

• SKILL.md esiste e ha frontmatter YAML valido (name, description).
• Qualità della description — La description include linguaggio di trigger (es. “Use when…”, “Use for…”).
• Lunghezza del body — Body di SKILL.md sotto 500 righe (contenuto lungo va in references/).
• Integrità dei riferimenti — I link in SKILL.md puntano a file esistenti; nessun link rotto.
• metadata.json — Presente e valida (o avviso se manca; la aggiungerai allo step successivo).

Se qualcosa fallisce, l’agente suggerirà correzioni (es. aggiungere trigger, correggere un path, spostare contenuto in un file di riferimento). Puoi affinare in chat e ri-validare finché tutti i controlli passano.

Step 6: Prepara i metadati per la biblioteca

Quando sei soddisfatto del contenuto della skill, l’agente preparerà per la pubblicazione:

1. Eseguire preview_metadata — Mostra come la skill apparirà nella biblioteca. Se metadata.json non esiste, viene generata una bozza dal frontmatter di SKILL.md.
2. Modificare metadata.json — Insieme imposterai title (nome leggibile per la biblioteca), description (breve riassunto), tags (sostantivi comuni inglesi orientati al dominio, es. “Productivity”, “Meetings”, “Legal”, “Compliance”) e examples (due o tre prompt di esempio).
3. Validare di nuovo — Un ultimo validate_skill assicura che metadati e struttura siano completi.

Dopo questo, l’agente ti dirà che la skill è pronta per la pubblicazione.

Step 7: Pubblica nella tua biblioteca

1. Nella barra del progetto clicca Publish Skill.
2. Una finestra elenca le skill nella tua directory output/ (ogni cartella che contiene un SKILL.md). Seleziona la skill da pubblicare.
3. Conferma. Il frontend chiama l’API di publish; la skill viene copiata nella biblioteca di skill della tua organizzazione e registrata nel catalogo.
4. Vedrai un messaggio di successo (es. “Skill pubblicata in biblioteca”). La skill è ora disponibile quando installi skill su qualsiasi progetto del tuo tenant. Ripubblicare lo stesso slug aggiorna la skill esistente.

Anatomia di una skill Rakenne

Una skill minima in output/{slug}/ è così:

• SKILL.md — Obbligatorio. Frontmatter YAML con name (slug) e description (incluso linguaggio di trigger). Body: passaggi del flusso, regole e link ai riferimenti.
• metadata.json — Obbligatorio per la pubblicazione. title, description, tags (array), examples (array di prompt di esempio). Usato dalla UI della biblioteca.
• references/ — Opzionale. File Markdown (o altri) con conoscenza di dominio; linkati da SKILL.md così l’agente può leggerli durante il flusso.
• assets/ — Opzionale. Template o asset statici che l’agente usa per produrre l’output (es. meeting_notes_template.md).

Il flusso skill-creator mantiene SKILL.md conciso e sposta il contenuto dettagliato in references/ così l’agente ha un flusso chiaro e scansionabile più contesto ricco quando serve.

Suggerimenti

• Un flusso per skill — Se hai più flussi distinti, crea una skill per flusso; puoi creare più skill nello stesso progetto workshop (ciascuna nel proprio output/{slug}/).
• Il linguaggio di trigger conta — L’agente usa la description della skill per decidere quando attivarla. Frasi come “Use when the user wants to…”, “Use for drafting…” o “Use to generate…” aiutano a far corrispondere l’intento.
• Itera nel workshop — Puoi riaprire il progetto in qualsiasi momento, modificare file o chattare con l’agente per cambiare la skill, ri-validare e Publish Skill di nuovo per aggiornare la copia in biblioteca.
• Niente extension.ts per skill di dominio — Lo Skill Workshop è per skill basate su markdown (SKILL.md + references + assets). Le estensioni TypeScript sono fuori dallo scope del flusso guidato; lo skill-creator non crea né modifica extension.ts.

Prossimi passi

• Usa Session Management and Context Hygiene così ogni attività di creazione resta in una sessione focalizzata.
• Leggi Rakenne 0.2.0 — Skill Workshop e altro per il set completo di funzionalità e i miglioramenti alla biblioteca.
• Dopo la pubblicazione, installa la tua skill su un progetto di elaborazione documenti ed esegui alcuni prompt di esempio per confermare il comportamento atteso.