dtt-ita-skill-library

Pacchetto npm estendibile per installare skill di Claude, Codex e GitHub Copilot nel progetto corrente. Versione della libreria: 1.0.3. Le cinque nuove skill Salesforce e la skill Note di rilascio sono alla versione 1.0.0 (versione 1 nel formato SemVer).

Richiede Node.js 22 o successivo. Nessuna dipendenza runtime.

Skill Salesforce

Cinque skill originali per il ciclo di lavoro Salesforce, ciascuna con implementazione Claude, Codex e GitHub Copilot. Restano sei skill nel catalogo contando la preesistente Note di rilascio.

| Skill | Scopo | | --- | --- | | salesforce-discovery | Processi, requisiti, assessment e criteri di accettazione | | salesforce-solution-planning | Architettura, scelte tecnologiche, backlog, dipendenze e stime | | salesforce-implementation | Configurazione e sviluppo front-end/back-end, desktop e mobile | | salesforce-quality-security | Test, revisione sicurezza, regressioni e verifiche per persona/runtime | | salesforce-release-operations | Manifest, validazione, deploy, migrazioni, cutover e monitoraggio |

Ogni skill impone all'agente di dichiarare nome, versione e scopo prima di applicarla. E un'istruzione obbligatoria nella skill, non un hook che puo garantire il comportamento di qualsiasi modello.

Gli entrypoint sono brevi e autonomi. I riferimenti tecnici si leggono soltanto quando pertinenti: configurazione front-end, configurazione back-end, Apex, Flow/metadati, LWC, integrazioni e desktop/mobile. Sono inclusi scenari online/offline, autorizzazioni server, configurazione delle pagine, limiti delle verifiche su browser e prove sui dispositivi effettivi. Nessuna org o credenziale e inclusa; CLI/MCP sono richiesti solo per le operazioni che li necessitano.

La progettazione deriva da documentazione Salesforce, esempi pubblici Apex/LWC e confronto critico con skill online, non dal riuso di skill locali. Vedi ricerca e confronto e scenari di valutazione. I limiti di lunghezza sono controlli sul contesto, non misure del consumo reale di token o una promessa di superiorita universale.

Avvio locale

Puoi scaricare il progetto da GitHub:

git clone https://github.com/lucabenedettini/skill-library.git
cd skill-library

Dalla cartella di questa libreria:

node bin/cli.js
node bin/cli.js --help

Per usare il comando in un altro progetto, installa prima il pacchetto locale:

npm install --global "C:\percorso\dtt-ita-skill-library"
cd percorso-del-progetto
dtt-ita-skill-library

La destinazione è sempre la directory corrente del terminale, anche se il pacchetto è installato globalmente. Non viene cercata automaticamente la radice Git.

Uso dopo la pubblicazione npm

npx --yes dtt-ita-skill-library@latest
npx --yes dtt-ita-skill-library@latest --help

Questi comandi richiedono che sia stata completata la prima pubblicazione su npm (vedi sotto). @latest recupera la versione pubblicata nel tag npm latest, comprese tutte le skill. Una CLI avviata da una copia locale o globale usa il catalogo di quella copia: per aggiornare un'installazione globale usa npm install --global dtt-ita-skill-library@latest. Il catalogo resta stabile durante la sessione; rilancia npx ...@latest per nuove pubblicazioni.

--yes deve precedere il nome del pacchetto: evita solo la conferma di download del programma nella cache npm. Non installa skill nel progetto e non salta la conferma del menu. La domanda iniziale viene mostrata prima che il codice della libreria sia eseguito: il pacchetto non puo rimuoverla. In PowerShell puoi usare npx.cmd --yes dtt-ita-skill-library@latest. Non serve modificare la configurazione globale di npm.

Flusso interattivo

1. Scorri le skill con Su/Giù; Invio o Destra apre la scheda.
2. Leggi descrizione e indicazioni su quando usare la skill.
3. Scorri le implementazioni e selezionane una o più con Spazio.
4. Premi Invio per vedere destinazioni, versioni e operazioni previste.
5. Premi y per confermare oppure n per annullare e tornare al catalogo. Invio da solo non conferma.
6. Dopo l'installazione il catalogo riappare automaticamente, con il messaggio di esito.

Sinistra/Esc torna al catalogo; q dal catalogo o Ctrl+C esce. Durante la scrittura i tasti sono ignorati per non interrompere l'aggiornamento a metà.

| Agente | Destinazione relativa al terminale | | --- | --- | | Claude | .claude/skills/<id>/ | | Codex | .agents/skills/<id>/ | | GitHub Copilot | .github/skills/<id>/ |

I percorsi seguono la documentazione di Claude, Codex e GitHub Copilot. Alcuni agenti leggono anche le cartelle di altri agenti: installare tutte le varianti non garantisce che ciascun agente veda esclusivamente la propria. Le varianti iniziali mantengono quindi una procedura compatibile tra agenti.

Installazione e aggiornamento

Il riepilogo rileva separatamente ogni implementazione. Se la cartella esiste, mostra AGGIORNA, altrimenti INSTALLA. Una ricevuta .dtt-skill.json registra versione e agente; le installazioni preesistenti senza ricevuta mostrano una versione sconosciuta.

Solo dopo y vengono copiati SKILL.md e tutte le risorse dell'implementazione. L'aggiornamento sostituisce l'intera cartella della skill, eliminando anche file obsoleti e modifiche locali; le altre skill rimangono intatte. Anche una versione uguale viene riallineata al catalogo. Se si usa una vecchia copia della libreria, si installa la sua versione: il riepilogo mostra sempre origine e destinazione della versione.

Le copie sono preparate prima della sostituzione e i backup temporanei permettono il ripristino in caso di errore gestito. Non è garantita l'atomicità in caso di arresto del sistema o interruzione forzata del processo; eventuali backup si trovano nelle cartelle .dtt-install-* accanto alle skill. Non avviare due installazioni contemporanee nello stesso progetto. Collegamenti simbolici e junction nelle destinazioni sono rifiutati per evitare scritture fuori progetto.

Aggiungere una skill

Il catalogo è scoperto automaticamente: non serve aggiornare un indice o il codice della CLI.

skills/
  release-notes/
    skill.json
    claude/SKILL.md
    codex/SKILL.md
    copilot/SKILL.md

Crea skills/<id>/skill.json seguendo questo schema:

{
  "id": "mia-skill",
  "name": "La mia skill",
  "version": "1.0.0",
  "description": "Descrizione di cosa fa la skill.",
  "whenToUse": "Le richieste o situazioni in cui usarla.",
  "agents": ["claude", "codex", "copilot"]
}

L'id deve coincidere con il nome della cartella: lettere minuscole, numeri e trattini, massimo 63 caratteri. Puoi dichiarare anche solo un sottoinsieme degli agenti. Ogni agente dichiarato deve avere la propria cartella con SKILL.md:

---
name: mia-skill
description: Descrive il compito e quando attivare questa skill.
metadata:
  version: "1.0.0"
---

# La mia skill

Istruzioni specifiche per eseguire il compito.

Il validatore della libreria richiede questi campi nella forma mostrata: name e description su una riga, metadata.version tra doppi apici. Non è un parser YAML generico. La versione del manifest e quella dei tre SKILL.md devono coincidere. Puoi aggiungere references/, scripts/, assets/ e metadati specifici dell'agente all'interno della sua cartella: vengono copiati insieme alla skill. I link simbolici nel catalogo non sono ammessi.

Per un nuovo tipo di agente aggiungi una voce in src/catalog.js con etichetta e percorso, poi dichiarala nei manifest interessati.

Aggiornare e distribuire

1. Modifica le istruzioni e le risorse della skill.
2. Incrementa la versione in skill.json e nei relativi SKILL.md.
3. Incrementa anche la versione di package.json per una nuova pubblicazione npm.
4. Esegui le verifiche e crea l'archivio:

npm test
npm run validate
npm pack
npm run check:package

L'archivio della versione corrente si chiama dtt-ita-skill-library-1.0.3.tgz. Puoi distribuirlo e installarlo con npm install --global percorso/dtt-ita-skill-library-1.0.3.tgz anche prima della pubblicazione sul registry.

Prima pubblicazione su npm (manuale)

Servono un account su npmjs.com, accesso al nome dtt-ita-skill-library e l'autenticazione richiesta da npm, inclusa la 2FA. La configurazione iniziale è UNLICENSED: nessuna licenza open source è stata scelta implicitamente. Se vuoi concedere una licenza open source, sceglila e aggiungila prima di pubblicare.

Dalla cartella del repository, usa Node.js 24 e una versione aggiornata di npm:

git pull --ff-only origin main
npm ci
npm test
npm pack --dry-run
npm login
npm publish --access public

npm login richiede il tuo intervento nel browser. Non inserire password, codici 2FA o token nel repository. npm publish pubblica la versione corrente di package.json; alla prima pubblicazione è 1.0.0. Il comando esegue anche i test tramite prepublishOnly e la validazione tramite prepack.

La disponibilità del nome sul registry non è stata verificata: se appartiene a un altro account, interrompi e scegli un nome disponibile o ottieni i permessi. npm non permette di ripubblicare la stessa versione. Verifica l'esito con npm view dtt-ita-skill-library version.

Collegamento npm e GitHub (manuale, una sola volta)

Dopo la prima pubblicazione, apri la pagina del pacchetto su npm, Settings → Trusted Publisher, scegli GitHub Actions e imposta:

| Campo | Valore | | --- | --- | | Organization or user | lucabenedettini | | Repository | skill-library | | Workflow filename | publish.yml | | Environment name | Lascia vuoto | | Allowed actions | Abilita la pubblicazione diretta con npm publish |

Usa solo il nome publish.yml, senza .github/workflows/. Il workflow è già presente nel repository. Non servono un secret NPM_TOKEN o un environment GitHub. La configurazione utilizza OIDC su runner GitHub-hosted e npm 11.6.2. Riferimento: Trusted publishing npm.

Se GitHub Actions è disabilitato nel repository, abilitalo in Settings → Actions → General. Il workflow richiede soltanto lettura del repository e id-token: write per la pubblicazione; non serve concedere permessi generali di scrittura.

Rilasci successivi (automatici tramite tag)

Il workflow ci.yml verifica push e pull request verso main su Windows e Linux, con Node.js 22 e 24. Il workflow publish.yml parte al push di un tag vX.Y.Z: controlla che corrisponda a package.json e che il commit appartenga alla cronologia di main, esegue test, crea e verifica l'archivio, quindi pubblica su npm. I normali commit e il solo aumento di versione senza tag non pubblicano nulla. I tag prerelease come v1.1.0-beta.1 vengono rifiutati.

Per rilasciare una correzione, assicurati di essere su main, aggiorna il checkout e salva le modifiche in un commit. Poi, con la working tree pulita:

git switch main
git pull --ff-only origin main
npm test
npm version patch
git push --atomic origin main --follow-tags

npm version patch incrementa package.json e package-lock.json, crea un commit e un tag annotato (ad esempio v1.0.1). Usa minor per una nuova funzionalità compatibile o major per modifiche incompatibili. Git deve avere nome ed email configurati; puoi usare l'indirizzo GitHub noreply mostrato nelle impostazioni del tuo account per mantenere privata l'email personale.

Le versioni delle skill sono indipendenti da quella del pacchetto: aggiorna manualmente skill.json e metadata.version nei relativi SKILL.md quando cambi una skill. npm version non modifica quei file. Le skill non modificate possono mantenere la loro versione.

Controlla il risultato nella scheda Actions del repository. Il collegamento npm va completato prima di inviare un tag di rilascio. Se la configurazione di autenticazione non era pronta, correggila e riesegui il workflow fallito, purché quella versione non sia stata già pubblicata. Non inviare v1.0.0 per ripubblicare la prima versione caricata manualmente.

Gli utenti accedono al nuovo catalogo con npx --yes dtt-ita-skill-library@latest e aggiornano le copie delle skill nei progetti tramite la selezione e la conferma y.

Comandi

Descrizioni delle skill

Ogni scheda del menu contiene tre righe: scopo, quando sceglierla e istruzioni d'uso. Download e installazione sono spiegati nell'help, senza ripeterli nella descrizione di ogni skill. I campi description, whenToUse e howToUse in skill.json contengono testi specifici per ciascuna skill. I test verificano tre righe senza a capo interni, ciascuna di massimo 78 caratteri. Usa un terminale di almeno 80 colonne per evitare che il terminale vada automaticamente a capo. Avvia poi l'agente nel progetto e chiedigli esplicitamente di usare la skill installata, fornendo gli input indicati nella riga Uso.

| Comando | Comportamento | | --- | --- | | dtt-ita-skill-library | Apre il menu interattivo | | dtt-ita-skill-library --help | Mostra guida e tasti disponibili | | dtt-ita-skill-library --version | Mostra la versione della libreria | | dtt-ita-skill-library --list | Stampa il catalogo senza modificare file | | dtt-ita-skill-library --validate | Valida metadati e file delle skill |

--help, --version, --list e --validate funzionano anche senza un terminale interattivo.