From bd5fb0725bba2f7f9fd05df6e6e1e1012bc0eef2 Mon Sep 17 00:00:00 2001 From: Davide Grilli Date: Wed, 23 Sep 2026 14:04:29 +0200 Subject: [PATCH] Aggiungi indice delle skill e scheda di find-skills MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README.md fa da indice, skills/find-skills.md è la prima scheda e CLAUDE.md descrive come documentare le nuove skill. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 52 ++++++++++++++++-- README.md | 9 ++++ skills/find-skills.md | 122 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 178 insertions(+), 5 deletions(-) create mode 100644 README.md create mode 100644 skills/find-skills.md diff --git a/CLAUDE.md b/CLAUDE.md index 37fd2f7..f1f6178 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,11 +4,53 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Scopo del repository -Questa cartella serve a scrivere documentazione in Markdown per delle skill. Non è un progetto software: non ci sono comandi di build, lint o test. +Un dizionario personale di skill per agenti AI, scritto in Markdown. Non è un progetto software: non ci sono comandi di build, lint o test. Le skill vengono aggiunte nel tempo, di solito con una richiesta come "aggiungi la skill X" o con un comando di installazione (`npx skills add ...`). + +## Struttura + +- `README.md` è l'indice: una tabella con una riga per skill, con il nome che rimanda alla scheda e una descrizione di una frase. Niente dettagli qui. +- `skills/.md` è la scheda di una skill. Il nome del file è il nome della skill. + +[skills/find-skills.md](skills/find-skills.md) è la scheda di riferimento: ogni nuova scheda deve avere lo stesso livello di dettaglio, struttura e tono. + +## Aggiungere una skill + +### 1. Raccogli le fonti + +Leggi sempre il testo completo della skill, non solo un riassunto: + +- il `SKILL.md` grezzo (`https://raw.githubusercontent.com///main//SKILL.md`), che è la fonte principale per "Cosa fa"; +- il README del repository, per comandi e opzioni di installazione; +- la pagina su skills.sh (`https://skills.sh///`), se esiste, per installazioni, stelle e controlli di sicurezza; +- le guide ufficiali di Claude e ChatGPT, se servono per l'installazione nelle app desktop. + +Basati solo su queste fonti. Se un dettaglio non è verificabile o una pagina non è raggiungibile, dillo nella scheda invece di inventarlo. + +### 2. Scrivi la scheda + +Sezioni, in quest'ordine: + +1. **Intestazione:** autore, repository, link al `SKILL.md`, pagina su skills.sh. Aggiungi installazioni e stelle con mese e anno della rilevazione, e l'esito dei controlli di sicurezza, avvisi compresi. +2. **A cosa serve:** il problema che risolve, in poche righe. +3. **Cosa fa**, con le sottosezioni: + - *Quando si attiva*: le richieste o situazioni che la fanno partire; + - *Come lavora*: i passi che segue l'agente, con i comandi reali ed esempi; + - eventuali tabelle o consigli d'uso presenti nel `SKILL.md`; + - *Da sapere*: requisiti (per esempio Node.js), limiti e aspetti di sicurezza (installazioni senza conferma, script eseguiti, accessi esterni). +4. **Installazione**, per piattaforma: + - *Claude Code e Codex*: il comando completo, una tabella che spiega le opzioni, come verificarla o richiamarla, e i comandi per elencarla, aggiornarla e rimuoverla; + - *App desktop di Claude e ChatGPT*: come preparare lo ZIP e i passaggi di caricamento per ciascuna app, più un avviso se la skill non può funzionare davvero lì. +5. **Fonti:** i link effettivamente usati. + +Traduci e adatta il contenuto del `SKILL.md` in italiano invece di copiarlo; lascia in originale comandi, nomi e parole chiave di ricerca. + +### 3. Aggiorna l'indice + +Aggiungi nel `README.md` la riga della skill con una descrizione di una frase. ## Come lavorare qui -- Segui la richiesta dell'utente alla lettera. Struttura, formato, sezioni e stile di ogni documento li decide l'utente, richiesta per richiesta. -- Non esistono ancora convenzioni o template: non inventarne. Se una richiesta è ambigua su qualcosa che cambia il risultato, chiedi invece di decidere tu. -- Se l'utente definisce una convenzione valida per tutti i documenti (per esempio un template o una struttura fissa di cartelle), aggiungila a questo file così resta per le sessioni future. -- Scrivi nella lingua che usa l'utente (di default l'italiano), salvo richiesta diversa. +- Segui la richiesta dell'utente: se chiede una struttura o sezioni diverse per una skill, quella richiesta prevale su questo file. +- Se l'utente chiede più informazioni su una skill già presente, completa la sua scheda seguendo la stessa struttura. +- Se l'utente fissa una nuova convenzione valida per tutte le schede, aggiornala qui. +- Scrivi in italiano, salvo richiesta diversa. diff --git a/README.md b/README.md new file mode 100644 index 0000000..bff2fc1 --- /dev/null +++ b/README.md @@ -0,0 +1,9 @@ +# Skills + +Il mio dizionario delle skill per agenti AI (Claude Code, Codex, app di Claude e ChatGPT): per ognuna, una breve descrizione e un link alla scheda con cosa fa e come si installa. + +## Skill + +| Skill | Descrizione | +|---|---| +| [find-skills](skills/find-skills.md) | Permette all'agente di cercare e installare da solo altre skill con `npx skills`. | diff --git a/skills/find-skills.md b/skills/find-skills.md new file mode 100644 index 0000000..6a30e1f --- /dev/null +++ b/skills/find-skills.md @@ -0,0 +1,122 @@ +# find-skills + +- **Autore:** Vercel Labs +- **Repository:** [vercel-labs/skills](https://github.com/vercel-labs/skills) +- **Sorgente:** [skills/find-skills/SKILL.md](https://github.com/vercel-labs/skills/blob/main/skills/find-skills/SKILL.md) +- **Pagina su skills.sh:** [vercel-labs/skills/find-skills](https://skills.sh/vercel-labs/skills/find-skills) +- **Diffusione (settembre 2026):** circa 3,5 milioni di installazioni; il repository ha circa 32.300 stelle su GitHub +- **Controlli di sicurezza su skills.sh:** Gen Agent Trust Hub e Socket superati; Snyk segnala un avviso (la pagina non spiega il motivo) + +## A cosa serve + +Permette all'agente di trovare e installare da solo altre skill. Quando chiedi "c'è una skill per fare X?" o "come faccio Y?", l'agente cerca nell'ecosistema delle skill invece di rispondere solo con le sue conoscenze. + +## Cosa fa + +### Quando si attiva + +Quando: + +- chiedi "come faccio X?" e X è un compito comune per cui probabilmente esiste una skill; +- chiedi "trova una skill per X" o "esiste una skill per X?"; +- chiedi "sai fare X?" e X è una capacità specialistica; +- vuoi estendere le capacità dell'agente o cerchi strumenti, template o flussi di lavoro; +- dici che ti servirebbe aiuto in un ambito preciso (design, test, deploy, ecc.). + +### Come lavora + +1. **Capisce cosa ti serve:** l'ambito (React, test, deploy...), il compito preciso e se è abbastanza comune da avere già una skill. +2. **Consulta la classifica di [skills.sh](https://skills.sh/),** ordinata per numero di installazioni, prima di cercare. Esempi di fonti molto usate: `vercel-labs/agent-skills` (React, Next.js, web design) e `anthropics/skills` (design frontend, documenti). +3. **Cerca con lo strumento a riga di comando**, se la classifica non basta: + ```bash + npx skills find [--owner ] + ``` + Per esempio, "come rendo più veloce la mia app React?" diventa `npx skills find react performance`. +4. **Verifica la qualità** prima di proporre una skill: + - installazioni: preferisce skill con più di 1.000 installazioni ed è prudente sotto le 100; + - fonte: autori ufficiali (`vercel-labs`, `anthropics`, `microsoft`) valgono più di autori sconosciuti; + - stelle GitHub: diffida dei repository con meno di 100 stelle. +5. **Ti presenta le opzioni:** nome, cosa fa, numero di installazioni, fonte, comando di installazione e link a skills.sh. +6. **Si offre di installare** la skill che scegli, con `npx skills add -g -y`. + +Se non trova niente, lo dice, si offre di aiutarti direttamente e, se il compito ti capita spesso, suggerisce di creare una skill tua con `npx skills init `. + +### Categorie e parole chiave suggerite + +| Categoria | Esempi di ricerca | +|---|---| +| Sviluppo web | react, nextjs, typescript, css, tailwind | +| Test | testing, jest, playwright, e2e | +| DevOps | deploy, docker, kubernetes, ci-cd | +| Documentazione | docs, readme, changelog, api-docs | +| Qualità del codice | review, lint, refactor, best-practices | +| Design | ui, ux, design-system, accessibility | +| Produttività | workflow, automation, git | + +Le ricerche specifiche funzionano meglio ("react testing" invece di "testing"). Se una parola non dà risultati, conviene provare dei sinonimi ("deployment", "ci-cd" al posto di "deploy"). + +### Da sapere + +- Funziona lanciando comandi `npx` nel terminale, quindi dà il meglio negli agenti che lavorano in locale (Claude Code, Codex). Serve Node.js. +- L'installazione proposta usa `-y`, che salta le conferme dello strumento `skills`: la skill scelta viene installata a livello globale senza ulteriori domande. Una skill può contenere istruzioni e script, quindi prima di accettare conviene controllarne la fonte. + +## Installazione + +### Claude Code e Codex + +```bash +npx skills add vercel-labs/skills --skill find-skills -g -a codex -a claude-code +``` + +| Opzione | Significato | +|---|---| +| `--skill find-skills` | installa solo questa skill del repository | +| `-g` | installazione globale (`~/.claude/skills/`, `~/.codex/skills/`); senza, solo nel progetto corrente (`.claude/skills/`, `.agents/skills/`) | +| `-a ` | agente di destinazione, ripetibile (`claude-code`, `codex`, ...) | +| `-y` | salta le domande di conferma | +| `--copy` | copia i file invece di creare collegamenti simbolici | + +Per un solo agente, lascia un solo `-a`. Dopo l'installazione riavvia la sessione. In Codex puoi richiamarla con `$find-skills` o vederla con `/skills`; Claude Code la usa da solo quando la richiesta è pertinente. + +Gestione: + +```bash +npx skills list -g # skill installate +npx skills update find-skills # aggiornamento +npx skills remove find-skills # rimozione +``` + +### App desktop di Claude e ChatGPT + +Queste app richiedono di caricare la skill come ZIP. Preparalo così: + +```bash +git clone --depth 1 https://github.com/vercel-labs/skills.git +cd skills/skills && zip -r ~/find-skills.zip find-skills +``` + +Lo ZIP deve contenere la cartella `find-skills/` con dentro `SKILL.md`. + +**Claude (desktop o web)** + +1. Attiva l'esecuzione del codice in **Settings → Capabilities**. +2. Vai in **Customize → Skills → + → Create skill → Upload a skill** e scegli lo ZIP. +3. Attiva l'interruttore della skill. + +**ChatGPT (desktop o web)** + +1. Vai in **Skills** nella barra laterale, poi **Create → Upload from your computer**, e scegli lo ZIP o la cartella. +2. Attendi l'analisi di sicurezza di ChatGPT. +3. Richiamala con `@` nella chat. + +Le skill personali caricate su desktop e web non si sincronizzano: vanno caricate su ciascuna. + +> **Limite:** nelle app di chat la skill gira in un ambiente isolato, dove probabilmente `npx skills` non può installare niente in modo permanente. Lì può al massimo suggerire quali skill cercare. + +## Fonti + +- [README di vercel-labs/skills](https://github.com/vercel-labs/skills) +- [SKILL.md di find-skills](https://github.com/vercel-labs/skills/blob/main/skills/find-skills/SKILL.md) +- [find-skills su skills.sh](https://skills.sh/vercel-labs/skills/find-skills) +- [Use skills in Claude – Claude Help Center](https://support.claude.com/en/articles/12512180-use-skills-in-claude) +- [Skills in ChatGPT – OpenAI Help Center](https://help.openai.com/en/articles/20001066-skills-in-chatgpt)