Scrivere skill

Una skill è una procedura con un nome che l'assistente può invocare invece di ricostruire ogni volta i passaggi da zero. Le memorie dicono all'assistente che cosa è vero. Le regole gli dicono che cosa non fare. Le skill gli dicono come svolgere un lavoro specifico, passo dopo passo.

Questa pagina spiega quando scrivere una skill, che cosa contiene e come le skill vengono memorizzate e collegate.

Quando scrivere una skill

Ricorri a una skill quando noti che lo stesso schema si ripete. Il segnale è "l'assistente continua a ripercorrere la stessa serie di passaggi e ogni tanto ne salta uno".

• Procedure operative. "Riprodurre in locale un webhook Stripe." "Rigenerare le fixture di seed." "Eseguire la checklist pre-rilascio."
• Flussi di lavoro personalizzati. "Aprire una PR in bozza con le etichette giuste e i revisori giusti." "Incrementare la versione, creare il tag ed eseguire il push."
• Indicazioni specifiche del dominio. "Creare un nuovo evento di analytics dall'inizio alla fine: colonna, tipo, dashboard."

Se lo schema occupa una o due righe, basta una memoria. Ricorri a una skill quando la procedura ha più di tre passaggi o comporta un qualsiasi requisito del tipo "fai queste cose in quest'ordine".

Origini

Un record di skill contiene un valore di origine che indica a Pathrule dove si trova il suo corpo.

• manual. Il corpo viene scritto direttamente in Pathrule e memorizzato così com'è. È il valore predefinito. Usalo quando vuoi che la procedura appartenga interamente al workspace.
• template. Una skill di partenza fornita da Pathrule, copiata nel workspace e modificabile da lì.
• github_ref. La skill punta a un URL GitHub esterno. Usala per le skill pubblicate da ecosistemi di skill di cui ti fidi.

Per le skill github_ref, il workspace conserva un'istantanea del corpo ricavata da quella fonte e la skill è di sola lettura nel workspace: VS Code ti indica di modificare invece la fonte.

Struttura di SKILL.md

Una skill è un piccolo file Markdown con un frontmatter seguito dal corpo della procedura.

---
name: replay-stripe-webhook
description: Replay a Stripe webhook against the local server with the right signing secret and the right idempotency key handling.
---

# Replay a Stripe webhook

Use this when a payment event from production needs to be reproduced locally.

## When to invoke

- A customer reports a missing receipt and you have the event id.
- You are debugging a webhook handler change.

## Procedure

1. Find the event in Stripe Dashboard. Copy its id.
2. Run `stripe events resend evt_xxx --webhook-endpoint we_local`.
3. Watch the local handler. It must accept and process the event without double charging.
4. If the handler returns 5xx, the customer support page is the next stop, not a retry.

## What NOT to do

- Do not replay against production webhooks.
- Do not skip the idempotency key check.

Il frontmatter deve includere name e description. Tutto ciò che segue è il corpo che l'assistente esegue. Il corpo può essere corto o lungo quanto serve.

Collegamento

Una skill risiede in un unico percorso del workspace, esattamente come una regola. Mettila nel percorso in cui la procedura è più pertinente. La skill per riprodurre il webhook va su services/billing/webhooks. La skill di rilascio va nella radice del workspace. Una nuova skill il cui nome coincide con quello di una skill già presente nel workspace viene rifiutata: aggiorna quindi quella esistente invece di aggiungerne una seconda copia.

L'assistente scopre le skill attraverso il contesto che Pathrule fornisce per un percorso (nello stesso modo in cui scopre memorie e regole), tramite pathrule_get_context, e ne legge una per intero con pathrule_read_skill. Durante la sincronizzazione, Pathrule scrive anche le skill nelle cartelle delle skill dei client che le leggono, come .claude/skills per Claude Code e .agents/skills per Codex.

Invocare una skill su richiesta con ::skill-name

Di solito l'assistente sceglie da solo la skill giusta. Quando vuoi imporne una specifica, scrivi :: seguito dal nome della skill in un punto qualsiasi del prompt, per esempio ::release-check o ::replay-stripe-webhook. Per quel turno l'assistente tratta la skill indicata come un flusso di lavoro obbligatorio da seguire, senza che tu debba scrivere lunghe istruzioni. In Claude Code e Codex l'hook del prompt rileva il marcatore prima che l'agente agisca; negli altri client l'assistente riceve la stessa istruzione quando richiede il contesto tramite MCP.

È progettato per fallire in modo sicuro:

• Se il nome corrisponde a più di una skill, non viene invocata alcuna skill invece di tirare a indovinare.
• Se il nome non corrisponde a nessuna skill, all'assistente viene detto di fermarsi e di risolvere la questione con te prima di modificare qualsiasi cosa. Può suggerire candidati pubblicati e attende la tua approvazione prima di aggiungerne uno al workspace.
• Ignora gli usi di :: tipici del codice, come button::before o std::vector, così i prompt normali non vengono fraintesi.

Questo rende ::skill-name un modo rapido, indipendente dal percorso, per portare nel turno corrente una procedura del team già nota.

Flusso di creazione

Due flussi portano allo stesso risultato.

• Creazione manuale. In VS Code, usa New Skill… nel percorso giusto e scrivi il corpo di SKILL.md. Dal terminale, esegui pathrule skill add --path /services/billing/webhooks --name replay-stripe-webhook --description "Replay a Stripe webhook locally"; senza --body, la CLI apre il tuo editor.
• Creazione tramite assistente. In Claude Code (o in qualsiasi client MCP) l'utente chiede all'assistente di "trasformare questo in una skill". L'assistente segue un piccolo schema di creazione delle skill: coglie l'intento, fa domande all'utente, prepara una bozza di SKILL.md e poi chiama pathrule_write_skill con il corpo completo.

Negli scenari a basso impegno l'assistente prepara la bozza della skill nella conversazione e attende l'approvazione prima di chiamare pathrule_write_skill. Il record salvato è quindi la bozza revisionata, non una scrittura silenziosa in background.

Versioni e modifiche concorrenti

Le skill hanno un token di versione, come le memorie e le regole. Due membri del team che modificano la stessa skill generano un conflitto gestito in modo pulito invece di sovrascriversi a vicenda, con le stesse opzioni di risoluzione dei conflitti in VS Code previste per una memoria.

Anti-pattern

• Skill che in realtà sono memorie. Se il corpo dice "questo è vero sul nostro modo di lavorare", trasformalo in una memoria.
• Skill che in realtà sono regole. Se il corpo dice "non fare mai X", trasformalo in una regola.
• Una sola skill che fa troppo. Dividila in due skill con nomi distinti se la procedura ha due punti di ingresso diversi.
• Importare skill esterne di cui non ti fidi. Una skill github_ref è codice che entra in esecuzione nelle istruzioni del tuo assistente. Trattala come una dipendenza.

Creazione in locale e su Cloud

Gli esempi di add da terminale in questa pagina si riferiscono a un workspace Cloud. In modalità locale, crea e modifica le voci in Local Console, in VS Code o tramite MCP locale; i comandi di conoscenza della CLI le elencano, le leggono e le cercano.

Cosa leggere dopo

• Scrivere memorie per fatti e decisioni.
• Scrivere regole per i vincoli.
• Riferimento degli strumenti MCP per gli strumenti che l'assistente usa per scrivere le skill.