diff --git a/README.md b/README.md index f6f6cdf..345b315 100644 --- a/README.md +++ b/README.md @@ -30,6 +30,22 @@ Le schede sono divise in due gruppi, e dentro ogni gruppo per argomento: |---|---| | [project-estimation](skills/project-estimation.md) | Stima durata, costi e risorse di un progetto con tecniche strutturate (PERT, bottom-up, per analogia). | +### Second brain + +Memoria a lungo termine dell'agente in note Markdown tue (vault Obsidian, LLM Wiki e simili). + +*Ancora nessuna skill.* + +### Ufficio + +Documenti, fogli di calcolo, presentazioni, posta e calendario. + +| Skill | Descrizione | +|---|---| +| [pdf](skills/pdf.md) | Fa leggere, unire, dividere, compilare, creare e ripulire (OCR) i file PDF, scegliendo lo strumento giusto per ogni compito. | +| [pptx](skills/pptx.md) | Fa creare, leggere e modificare presentazioni PowerPoint (`.pptx`, `.potx`), controllando ogni slide trasformata in immagine per correggere testo fuori dai bordi e sovrapposizioni. | +| [xlsx](skills/xlsx.md) | Fa creare, modificare e ripulire fogli Excel (`.xlsx`, `.xlsm`, `.csv`) con formule vere, ricalcolate e controllate; non scrive macro VBA. | + ### Ecosistema delle skill | Skill | Descrizione | @@ -42,15 +58,30 @@ Le schede sono divise in due gruppi, e dentro ogni gruppo per argomento: | Nome | Tipo | Descrizione | |---|---|---| +| [ecc](skills/ecc.md) | Sistema con 71 agenti, 314 skill, hook e regole | Everything Claude Code: pianificazione, test first, revisori per linguaggio, hook di qualità e sicurezza, memoria tra le sessioni; più grande e invasivo di superpowers. | | [superpowers](skills/superpowers.md) | Plugin con più skill | Metodologia di sviluppo per l'agente: brainstorming, piani, test first, debug sistematico e review, con skill che si attivano da sole. | +### Second brain + +Memoria a lungo termine dell'agente in note Markdown tue (vault Obsidian, LLM Wiki e simili). + +| Nome | Tipo | Descrizione | +|---|---|---| +| [claude-obsidian](skills/claude-obsidian.md) | Plugin con 15 skill | Fa dell'agente il custode di un "secondo cervello" in un vault Obsidian: cattura le fonti, le trasforma in note collegate con citazioni e risponde dalle tue note. | +| [obsidian-skills](skills/obsidian-skills.md) | Raccolta di 6 skill | Raccolta ufficiale per Obsidian: Markdown di Obsidian, Bases, Canvas, riga di comando, estrazione di pagine web e modelli. | +| [obsidian-wiki](skills/obsidian-wiki.md) | Framework di 39 skill | Fa costruire all'agente un "secondo cervello": un vault Obsidian di note collegate che raccoglie documenti, sessioni e progetti e risponde con citazioni. | + ### Conoscenza e note | Nome | Tipo | Descrizione | |---|---|---| | [graphify](skills/graphify.md) | Skill + programma Python | Trasforma codice, documenti e media di un progetto in un grafo di conoscenza che l'agente interroga invece di rileggere i file. | -| [obsidian-skills](skills/obsidian-skills.md) | Raccolta di 6 skill | Raccolta ufficiale per Obsidian: Markdown di Obsidian, Bases, Canvas, riga di comando, estrazione di pagine web e modelli. | -| [obsidian-wiki](skills/obsidian-wiki.md) | Framework di 39 skill | Fa costruire all'agente un "secondo cervello": un vault Obsidian di note collegate che raccoglie documenti, sessioni e progetti e risponde con citazioni. | + +### Ufficio + +Documenti, fogli di calcolo, presentazioni, posta e calendario. + +*Ancora nessuna skill.* ### Ecosistema di Claude Code diff --git a/skills/claude-obsidian.md b/skills/claude-obsidian.md new file mode 100644 index 0000000..1c33b4a --- /dev/null +++ b/skills/claude-obsidian.md @@ -0,0 +1,192 @@ +# claude-obsidian + +- **Autore:** AgriciDaniel (con la community AI Marketing Hub Pro) +- **Repository:** [AgriciDaniel/claude-obsidian](https://github.com/AgriciDaniel/claude-obsidian) (licenza MIT, versione 3.0.1) +- **Sorgenti:** cartella [skills/](https://github.com/AgriciDaniel/claude-obsidian/tree/main/skills), un `SKILL.md` per skill; il punto d'ingresso è [skills/wiki/SKILL.md](https://github.com/AgriciDaniel/claude-obsidian/blob/main/skills/wiki/SKILL.md) +- **Pagina su skills.sh:** [AgriciDaniel/claude-obsidian](https://skills.sh/AgriciDaniel/claude-obsidian) +- **Diffusione (ottobre 2026):** circa 6.500 installazioni complessive tramite `npx skills` su 15 skill (da 546 per `obsidian-markdown` a 297 per `wiki-cli`); il repository ha circa 16.000 stelle e 1.600 fork su GitHub +- **Controlli di sicurezza su skills.sh:** la pagina non riporta esiti per questo repository + +> Non è una sola skill ma un **plugin di Claude Code con 15 skill** e 3 agenti, più un programma Python (`scripts/claude-obsidian.py`) che fa le scritture sul vault. Le skill sono pensate per funzionare insieme. + +## A cosa serve + +Fa dell'agente il custode di un "secondo cervello": un vault di [Obsidian](https://obsidian.md) fatto di note Markdown tue, sul tuo disco. Gli dai fonti (articoli, trascrizioni, appunti), lui le legge, scrive note collegate che citano la fonte e le archivia in un grafo di conoscenza. Poi risponde alle domande a partire da quelle note. Segue il pattern LLM Wiki di Karpathy: la conoscenza si compila una volta e si mantiene, invece di rifare ogni volta la stessa ricerca. + +## Cosa fa + +### Quando si attiva + +Le skill partono quando la richiesta corrisponde alla loro descrizione, oppure con `/claude-obsidian:`. Per esempio: + +- vuoi creare un vault, o adottarne uno che hai già ("set up a wiki", "second brain"); +- vuoi dare in pasto all'agente fonti da trasformare in note; +- chiedi che cosa sai già su un argomento; +- vuoi salvare una risposta o un'intuizione come nota; +- vuoi controllare lo stato del vault (link rotti, pagine orfane); +- vuoi una ricerca web guidata, una board Canvas o una tabella Bases. + +### Come lavora + +1. **Cattura.** Le fonti vanno nella cartella `inbox/`. Ognuna viene conservata come copia intatta, identificata dal contenuto, prima di essere riassunta (`capture plan`, poi `capture apply`). +2. **Ancoraggio.** Le affermazioni importanti rimandano alle fonti che le sostengono; le prove deboli o in conflitto restano visibili. +3. **Accumulo.** Domande, ricerche e controlli attingono a ciò che il vault contiene già. + +Come sceglie il vault, in quest'ordine: l'argomento `--vault`, la variabile `CLAUDE_OBSIDIAN_VAULT`, il file `.claude-obsidian.json` più vicino, un vault inizializzato non ambiguo nella cartella corrente o sopra. Se la scelta manca o è ambigua, si ferma senza scrivere. La cartella del plugin non viene mai usata come vault. + +Creazione e adozione del vault sono prima un'anteprima, poi un'applicazione con l'hash del piano approvato: + +```bash +CORE=/percorso/assoluto/scripts/claude-obsidian.py +python3 "$CORE" init /percorso/del/vault --generated-at --operation-id init-reviewed +python3 "$CORE" init /percorso/del/vault --generated-at --operation-id init-reviewed \ + --approved-plan-sha256 --apply +``` + +Per un vault Obsidian che hai già, `adopt` al posto di `init`: aggiunge solo i metadati e i file di base mancanti, senza toccare le tue note. `--force` va usato solo dopo aver controllato i conflitti. + +### Le skill per gruppo + +**Costruire e usare il vault (5)** + +| Skill | A cosa serve | +|---|---| +| `wiki` | crea un vault nuovo o adotta uno esistente, controlla che sia pronto e smista le richieste alle altre skill | +| `wiki-ingest` | trasforma le fonti catturate in pagine collegate, con le fonti registrate | +| `wiki-query` | risponde dal contenuto del vault; in sola lettura | +| `save` | conserva una risposta o un'intuizione come nota, solo se glielo chiedi | +| `wiki-lint` | trova link rotti, pagine orfane, metadati mancanti e sezioni vuote | + +**Estendere il flusso (7)** + +| Skill | A cosa serve | +|---|---| +| `autoresearch` | ricerca sul web limitata da un budget, solo con il tuo consenso, unita al vault dopo revisione | +| `canvas` | crea e aggiorna board Canvas di Obsidian | +| `defuddle` | prepara la cattura pulita di una pagina web in Markdown; il pulitore è uno strumento esterno facoltativo | +| `wiki-fold` | riassume il registro delle operazioni in sintesi brevi e tracciabili | +| `wiki-mode` | decide come archiviare le note nuove: Generic, LYT, PARA o Zettelkasten | +| `wiki-retrieve` | ricerca locale BM25, con riordino facoltativo dei risultati | +| `wiki-cli` | legge e cerca tramite la riga di comando ufficiale di Obsidian | + +**Riferimento (3)** + +| Skill | A cosa serve | +|---|---| +| `obsidian-markdown` | Markdown di Obsidian corretto: link, incorporamenti, callout, proprietà | +| `obsidian-bases` | file `.base` nativi: tabelle, schede, filtri e formule | +| `think` | un ciclo di revisione strutturato per le decisioni difficili | + +I tre agenti (`wiki-ingest`, `wiki-lint`, `verifier`) sono in sola lettura: restituiscono bozze e rapporti, e scrive nel vault solo il programma Python. + +### Modalità di archiviazione + +`wiki-mode` cambia dove finiscono le note nuove; cambiare modalità non sposta quelle esistenti. + +| Modalità | Come archivia | +|---|---| +| Generic (predefinita) | fonti, concetti, entità e sessioni | +| LYT | Maps of Content e note atomiche collegate | +| PARA | Projects, Areas, Resources, Archives | +| Zettelkasten | ID stabili, note atomiche, molti collegamenti | + +### Cosa legge davvero + +| Ingresso | Supporto | +|---|---| +| File locali | copiati e identificati dal contenuto | +| Immagini | metadati, hash, dimensioni | +| PDF ed EPUB | solo metadati, hash e dimensione; nessuna estrazione del testo integrata | +| Pagine web e YouTube | preparate come piano da approvare; per scaricarle serve un esecutore separato | +| OCR | richiede uno strumento esterno configurato | +| Ricerca BM25 | locale e deterministica | +| Riordino o modelli remoti | facoltativi, con consenso esplicito | + +### Da sapere + +- **Scritture sicure:** legge ogni nota che toccherà e ne registra l'impronta SHA-256; gli aiutanti restituiscono solo bozze e Claude le fonde in un unico piano applicato come una sola transazione. Se una nota cambia nel frattempo, la scrittura si ferma invece di sovrascrivere. Un registro tiene i backup, e `transaction recover` annulla una scrittura interrotta. Non fa commit Git da solo. +- **Consensi separati:** ricerca web, checkpoint Git e qualunque dato inviato fuori dal computer sono passaggi a parte che richiedono approvazione. La configurazione di base non usa la rete. +- **Blocco:** coordina solo scrittori locali che cooperano; altri dispositivi ed editor esterni non lo condividono, quindi servono i backup. +- **Limiti dichiarati:** non registra le trascrizioni da solo, non è un servizio di sincronizzazione né un verificatore di fatti, e non sostituisce i backup. +- **Hook:** il README non ne menziona. +- **Requisiti:** Python 3.11 o più recente, Claude Code (o un altro agente compatibile con le Agent Skills), Bash per gli script di installazione; Obsidian per la parte visiva; Git solo per sviluppo o checkpoint. +- **Windows:** le scritture sul vault richiedono WSL; su Windows nativo si possono solo ispezionare e vedere le anteprime. + +## Installazione + +### Claude Code e Codex + +**Plugin di Claude Code** (metodo consigliato): + +```bash +claude plugin marketplace add AgriciDaniel/claude-obsidian +claude plugin install claude-obsidian@agricidaniel-claude-obsidian +claude plugin list +``` + +Poi apri la cartella che vuoi come vault e avvia Claude Code lì: + +```text +claude +/claude-obsidian:wiki # crea o adotta il vault (mostra prima un'anteprima) +/claude-obsidian:wiki-ingest # trasforma il contenuto di inbox/ in note collegate +/claude-obsidian:wiki-query # fai una domanda, risposta dalle tue note +/claude-obsidian:save # conserva una buona risposta come nota +/claude-obsidian:wiki-lint # controllo: link rotti, orfane, lacune +``` + +Apri la stessa cartella in Obsidian con **Open folder as vault**. Le skill hanno il prefisso del plugin, per esempio `/claude-obsidian:wiki`. + +**Codex e altri agenti** (OpenCode, Gemini, ZCode, Cursor, Windsurf): da un clone del repository, uno script collega le skill. Senza `--apply` mostra solo l'anteprima. + +```bash +git clone https://github.com/AgriciDaniel/claude-obsidian.git +cd claude-obsidian +bash scripts/setup-multi-agent.sh --host codex # anteprima, non scrive +bash scripts/setup-multi-agent.sh --host codex --apply # collega le skill +bash scripts/setup-multi-agent.sh --check # verifica +``` + +| Opzione | Significato | +|---|---| +| `--host ` | agente di destinazione: `codex`, `opencode`, `gemini`, `zcode`, `cursor`, `windsurf` (ripetibile) | +| `--apply` | applica le modifiche; senza, è solo un'anteprima | +| `--check` | controlla che i collegamenti funzionino | +| `--workspace ` | cartella di lavoro, obbligatoria per Cursor e Windsurf | + +Lo script crea i collegamenti solo dove non c'è già niente e non sostituisce mai una skill o un collegamento esistente. Per Codex le skill finiscono in `~/.agents/skills/`. Dopo l'installazione riavvia la sessione. + +Gestione: + +```bash +claude plugin marketplace update agricidaniel-claude-obsidian # aggiornamento (1) +claude plugin update claude-obsidian@agricidaniel-claude-obsidian # aggiornamento (2) +claude plugin uninstall claude-obsidian@agricidaniel-claude-obsidian # rimozione (non toglie il vault) +claude plugin marketplace remove agricidaniel-claude-obsidian +``` + +Dopo l'aggiornamento riavvia Claude Code. Chi ha installato la 3.0.0 con il vecchio nome `agricidaniel-obsidian` deve reinstallare con il nome nuovo (guida `docs/namespace-migration.md`). Per gli altri agenti, rimuovi solo i collegamenti che lo script ti ha elencato. + +Esiste anche `npx skills add AgriciDaniel/claude-obsidian` (la pagina su skills.sh lo elenca), ma l'installazione documentata dal progetto è quella sopra. Non ho verificato come si comporti il programma Python con questo metodo. + +### App desktop di Claude e ChatGPT + +La documentazione del progetto non dice niente sulle app desktop di Claude e ChatGPT. Il caricamento di una skill come ZIP segue la procedura generale: + +1. Prepara lo ZIP con la cartella di una skill (per esempio `skills/wiki-query`), che deve contenere `SKILL.md`. +2. **Claude (desktop o web):** attiva l'esecuzione del codice in **Settings → Capabilities**, poi **Customize → Skills → + → Create skill → Upload a skill** e scegli lo ZIP; attiva l'interruttore. +3. **ChatGPT (desktop o web):** **Skills** nella barra laterale, **Create → Upload from your computer**, attendi l'analisi di sicurezza e richiamala con `@` nella chat. + +Le skill personali caricate su desktop e web non si sincronizzano: vanno caricate su ciascuna. + +> **Limite:** qui non ha senso usarla. Le skill chiamano lo script `scripts/claude-obsidian.py` per percorso assoluto e lavorano su un vault nel tuo disco, mentre le app di chat girano in un ambiente isolato senza accesso a questi file. Serve un agente che giri in locale, come Claude Code o Codex. + +## Fonti + +- [README di AgriciDaniel/claude-obsidian](https://github.com/AgriciDaniel/claude-obsidian) +- [docs/install-guide.md](https://github.com/AgriciDaniel/claude-obsidian/blob/main/docs/install-guide.md) +- [Cartella skills/](https://github.com/AgriciDaniel/claude-obsidian/tree/main/skills) +- [SKILL.md di wiki](https://github.com/AgriciDaniel/claude-obsidian/blob/main/skills/wiki/SKILL.md) +- [claude-obsidian su skills.sh](https://skills.sh/AgriciDaniel/claude-obsidian) +- [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) diff --git a/skills/ecc.md b/skills/ecc.md new file mode 100644 index 0000000..eb5e081 --- /dev/null +++ b/skills/ecc.md @@ -0,0 +1,203 @@ +# ecc (Everything Claude Code) + +- **Autore:** Affaan Mustafa (affaan-m) +- **Repository:** [affaan-m/everything-claude-code](https://github.com/affaan-m/everything-claude-code) (il nome canonico indicato dal progetto è `affaan-m/ECC`; licenza MIT, versione 2.2.3 del 1 ottobre 2026) +- **Sorgenti:** [README](https://github.com/affaan-m/everything-claude-code), [AGENTS.md](https://github.com/affaan-m/everything-claude-code/blob/main/AGENTS.md), cartelle `agents/`, `skills/`, `hooks/`, `rules/` +- **Pagina su skills.sh:** [affaan-m/ecc](https://skills.sh/affaan-m/ecc) +- **Diffusione (ottobre 2026):** circa 1,4 milioni di installazioni complessive su skills.sh, che elenca 330 skill; il repository ha circa 292.900 stelle e 43.300 fork su GitHub +- **Controlli di sicurezza su skills.sh:** la pagina del repository non riporta esiti +- **Canali ufficiali** (indicati dal progetto): il repository GitHub, i pacchetti npm `ecc-universal` e `ecc-agentshield`, la GitHub App, il plugin `ecc@ecc` e il sito ecc.tools. Il progetto avverte che copie non ufficiali possono contenere malware. + +> Non è una skill ma un **sistema di ottimizzazione per agenti di sviluppo**: 71 agenti, 314 skill, 98 comandi, hook, regole e uno scanner di sicurezza. I numeri sono quelli della pagina GitHub alla versione 2.2.3; skills.sh ne conta 330 e altre fonti, di versioni diverse, ne danno altri. Esistono molti fork (per esempio [unju-ai/ecc](https://github.com/unju-ai/ecc) o [ysyecust/everything-claude-code](https://github.com/ysyecust/everything-claude-code), quest'ultimo adattato al C++20); questa scheda riguarda solo il repository di affaan-m. + +## A cosa serve + +Dà all'agente un flusso di lavoro di ingegneria software strutturato: pianificare prima di costruire, scrivere i test per primi, farsi rivedere il codice da un agente con contesto pulito, verificare, e ricordare quanto imparato tra le sessioni. Invece di aggiungere una sola metodologia, offre un catalogo molto ampio di specialisti (revisori e risolutori di errori di build per ogni linguaggio) e di automazioni, da cui scegliere ciò che serve. È un'alternativa più grande e più invasiva di [superpowers](superpowers.md). + +## Cosa fa + +### Quando si attiva + +I componenti partono in modi diversi: + +- **agenti:** l'agente principale li delega quando il compito corrisponde (per esempio un revisore di Go dopo una modifica a codice Go); +- **skill:** si attivano quando la richiesta corrisponde alla loro descrizione; +- **comandi:** li lanci tu (`/ecc:plan`, `/code-review`...); +- **hook:** scattano da soli prima e dopo gli strumenti dell'agente e a inizio e fine sessione; +- **regole:** sono sempre caricate, se le copi nella cartella delle regole. + +### Come lavora + +Il flusso di sviluppo indicato dal progetto: + +1. **Pianifica** le funzioni complesse prima di scrivere codice (`/ecc:plan "..."`, agente `planner`). +2. **Test per primi:** prima un test che fallisce, poi il codice minimo per farlo passare, poi il rifacimento; obiettivo di copertura dell'80% o più con test unitari, di integrazione ed E2E (agente `tdd-guide`). +3. **Revisione** con contesto pulito (`/code-review`), più revisori per linguaggio e per sicurezza (`security-reviewer`) prima dei commit. +4. **Documentazione** aggiornata nel posto giusto (`doc-updater`), poi commit con messaggi in stile *conventional commits*. + +Principi dichiarati: delegare i compiti di dominio ad agenti specializzati e lanciare in parallelo quelli indipendenti; sicurezza prima di tutto (convalida degli ingressi, niente segreti scritti nel codice, query parametrizzate); immutabilità (creare nuovi oggetti invece di modificare quelli esistenti). + +Comandi principali: + +```text +/ecc:plan "..." # pianificazione +/code-review # revisione con contesto pulito +/build-fix /refactor-clean /security-scan +/context-budget /save-session /resume-session +/skill-create /mcp /evolve +agentshield scan --path . # audit della configurazione dell'agente +``` + +I comandi sono mantenuti per compatibilità: il progetto dice che i nuovi flussi vanno scritti come skill. + +### Cosa contiene + +| Cartella | Contenuto | +|---|---| +| `agents/` | 71 sottoagenti specializzati | +| `skills/` | 314 skill di flusso di lavoro e di conoscenza di dominio: la superficie principale | +| `commands/` | 98 comandi, mantenuti per compatibilità | +| `hooks/` | automazioni a eventi | +| `rules/` | regole sempre valide, comuni e per linguaggio | +| `scripts/` | utilità Node.js multipiattaforma | +| `mcp-configs/` | 14 configurazioni di server MCP | +| `tests/` | batteria di test del progetto | + +**Agenti, per gruppo** (l'elenco completo è in `agents/`): + +| Gruppo | Agenti | +|---|---| +| Flusso base | `planner`, `architect`, `tdd-guide`, `code-reviewer`, `security-reviewer`, `spec-miner` (ricava specifiche da progetti esistenti), `doc-updater`, `refactor-cleaner`, `e2e-runner` (Playwright), `docs-lookup` (documentazione via Context7) | +| Linguaggi e framework | revisori e, dove serve, risolutori di errori di build per C/C++, F#, Go, Kotlin, Python/Django/FastAPI, Java/Spring, Rust, PyTorch, TypeScript/JavaScript, React, Vue, Swift, Flutter/Dart, C#/.NET, PHP, HarmonyOS e database (PostgreSQL/Supabase) | +| Analisi della qualità | `silent-failure-hunter` (errori ingoiati), `type-design-analyzer`, `pr-test-analyzer`, `code-explorer`, `code-simplifier`, `comment-analyzer`, `agent-evaluator` | +| Prestazioni e architettura | `performance-optimizer`, `code-architect`, `a11y-architect` (accessibilità WCAG 2.2), `harness-optimizer`, `loop-operator` | +| Reti | `network-architect`, `homelab-architect`, `network-config-reviewer`, `network-troubleshooter` | +| ML | `mle-reviewer`, `rag-pipeline-reviewer` | +| Pubblicazione open source | `opensource-forker`, `opensource-sanitizer`, `opensource-packager` | +| Altri ambiti | `healthcare-reviewer`, `chief-of-staff` (smista e scrive la posta), `marketing-agent`, `seo-specialist`, `bengali-reviewer`, `conversation-analyzer` | +| GAN harness | `gan-planner`, `gan-generator`, `gan-evaluator` | + +L'elenco delle skill non l'ho trovato in forma ordinata: i documenti letti citano solo i linguaggi e i framework coperti (Go, Python, Perl, Swift, TypeScript, HarmonyOS/ArkTS, Django, NestJS, Spring Boot, Laravel). Non ho letto i singoli `SKILL.md`. + +### Hook installati + +Secondo `hooks/README.md`: + +| Momento | Cosa fanno | +|---|---| +| Prima di uno strumento | blocca `npm run dev` e simili fuori da tmux; ricorda tmux per i comandi lunghi; ricorda di rivedere le modifiche prima del push; controllo prima del commit (analizza i file in stage, convalida i messaggi di commit, cerca `console.log`, `debugger` e segreti, e blocca sui problemi gravi); avvisa per file `.md` o `.txt` non standard; suggerisce `/compact` ogni circa 50 chiamate; valuta le regole locali di Hookify | +| Dopo uno strumento | registra l'URL della PR dopo `gh pr create`; analisi in background dopo le build; controlli rapidi di qualità; formatta i file JS/TS con Prettier; esegue `tsc --noEmit` dopo le modifiche a `.ts`/`.tsx`; avvisa dei `console.log` | +| Inizio sessione | carica il contesto precedente, riconosce il gestore dei pacchetti | +| Prima della compattazione | salva lo stato | +| Fine sessione | salva il riepilogo della sessione, estrae schemi per l'apprendimento continuo, registra una stima dei costi, mostra una notifica sul desktop (macOS) | + +Si regolano con variabili d'ambiente: `ECC_HOOK_PROFILE` (`minimal`, `standard` predefinito, `strict`), `ECC_DISABLED_HOOKS` (elenco di identificatori separati da virgole, per esempio `pre:bash:tmux-reminder,post:edit:typecheck`), `ECC_HOOKS_ENABLED` come interruttore generale e `ECC_GATEGUARD=off` per spegnere solo GateGuard. + +### Da sapere + +- **Invasivo:** installa hook che girano a ogni comando e a ogni modifica, scrivono script sotto `~/.claude/` e salvano lo stato delle sessioni (riepiloghi, schemi appresi, stime dei costi). La documentazione degli hook non dice dove finiscano questi file né cosa contengano, e non descrive chiamate di rete. +- **Contesto:** regole e server MCP consumano la finestra di contesto. Il progetto consiglia poche regole (le regole comuni più un solo linguaggio), meno di 10 server MCP e meno di 80 strumenti attivi. Il plugin non attiva da solo i server MCP inclusi. +- **Un solo metodo di installazione per strumento:** sovrapporne più di uno duplica skill, comandi e hook (errori come "Duplicate hooks file"). Se usi il plugin, non copiare a mano `hooks/hooks.json` nelle impostazioni. +- **Impostazioni consigliate dal progetto:** modello Sonnet come predefinito, sforzo medio, compattazione del contesto al 50% invece che al 95%. +- **Requisiti:** Node.js 18 o più recente; per il plugin di Claude Code anche Git e Claude Code 2.1 o più recente nel `PATH`. Alcune funzioni facoltative su Windows nativo e macOS richiedono Bash, Python o WSL. +- **Servizi a pagamento:** il progetto si finanzia con sponsor e un livello a pagamento, *ECC Pro* (GitHub App ospitata con analisi dei repository privati e verifiche sulle PR). Il resto è libero. +- **Sicurezza:** include AgentShield (scanner delle configurazioni degli agenti, con analisi approfondita facoltativa basata su Opus), GateGuard e un controllo della catena di fornitura nella CI. Sono dichiarazioni del progetto: non le ho verificate. +- **Maturità e supporto:** Claude Code è il riferimento stabile; Codex e Qoder hanno plugin nativi con meno hook; Cursor e OpenCode sono adattatori in beta; GitHub Copilot ha solo istruzioni in chat e skill/agenti in beta nella CLI; Gemini, Zed, Antigravity, Qwen, Hermes, OpenClaw, Kimi, CodeBuddy e JoyCode sono sperimentali. Il progetto non dichiara parità di funzioni fuori da Claude Code. +- **Memoria condivisa (Memory Vault):** passaggio di consegne tra strumenti in Markdown, installato a parte da npm. La memoria richiamata va trattata come contesto non verificato, non come istruzioni. +- **Fonti non lette per intero:** ho letto il README quasi per intero, ma non le guide collegate (installazione dettagliata, risoluzione dei problemi, Windows) né i singoli file di skill e agenti. + +## Installazione + +### Claude Code e Codex + +**Claude Code, installazione guidata** (consigliata dal progetto): + +```bash +npx ecc-universal@2.2.3 setup +``` + +**Claude Code, comandi del plugin:** + +```text +/plugin marketplace add https://github.com/affaan-m/ECC +/plugin install ecc@ecc +``` + +**Codex, plugin nativo:** + +```bash +codex plugin marketplace add affaan-m/ECC +codex plugin add ecc@ecc +codex plugin list --json +``` + +**Più strumenti insieme** (Claude Code, Codex, Kimi Code), con procedura guidata: + +```bash +npx ecc-universal@2.2.3 install --guided +``` + +**Installazione manuale o minima**, da una copia del repository: + +```bash +./install.sh --profile minimal --target claude +./install.sh --profile full --enable-hooks +``` + +| Opzione | Significato | +|---|---| +| `--profile minimal` / `--profile full` | insieme ridotto o completo di componenti | +| `--target claude` | strumento di destinazione | +| `--enable-hooks` / `--no-hooks` | una delle due va indicata se l'installazione aggiungerebbe hook | + +Altre vie descritte dal progetto: Qoder CLI (`qoder plugins install .`), Cursor, OpenCode e altri tramite adattatori; non le ho provate. + +**Regole:** i plugin di Claude Code non le distribuiscono. Copia `rules/common` più un solo pacchetto per il tuo linguaggio in `~/.claude/rules/ecc/`, e tienile poche perché sono sempre caricate. + +Dopo l'installazione riavvia la sessione. Non fare due installazioni diverse sullo stesso strumento. + +Gestione: il progetto indica i comandi `list-installed`, `doctor`, `repair` e `uninstall --dry-run` per vedere, riparare o togliere un'installazione, e dice che rilanciare l'installazione guidata aggiorna ECC o ne cambia l'ambito e il profilo degli hook. La sintassi esatta non l'ho verificata. Per il plugin vale il gestore dei plugin dell'agente (`/plugin` in Claude Code); per un aggiornamento di versione cambia il numero nel comando `npx`. + +```bash +npx skills add affaan-m/ecc # solo le skill, senza agenti, hook e regole +``` + +Quest'ultimo comando è la forma standard dello strumento `skills` per i repository di skill, che skills.sh elenca per questo progetto: non l'ho provato e porta solo le skill, non l'insieme intero. + +### App desktop di Claude e ChatGPT + +Queste app caricano una skill alla volta come ZIP; il plugin completo non si può installare, e perdi agenti, hook e regole, che sono la parte principale. Per provare una singola skill: + +```bash +git clone --depth 1 https://github.com/affaan-m/ECC.git +cd ECC/skills && zip -r ~/.zip +``` + +Lo ZIP deve contenere la cartella della skill 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:** qui non ha senso usarlo come sistema. ECC lavora con sottoagenti, hook, regole e comandi su un progetto locale, e le app di chat non li hanno. Una singola skill di conoscenza può funzionare, ma senza il resto del flusso; non ho verificato come reagiscono le app a una skill che presuppone altri componenti. + +## Fonti + +- [README di affaan-m/everything-claude-code](https://github.com/affaan-m/everything-claude-code) +- [AGENTS.md](https://github.com/affaan-m/everything-claude-code/blob/main/AGENTS.md) +- [hooks/README.md](https://github.com/affaan-m/everything-claude-code/blob/main/hooks/README.md) +- [Cartella agents/](https://github.com/affaan-m/everything-claude-code/tree/main/agents) +- [Release del progetto](https://github.com/affaan-m/everything-claude-code/releases) +- [ecc su skills.sh](https://skills.sh/affaan-m/ecc) +- [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) diff --git a/skills/pdf.md b/skills/pdf.md new file mode 100644 index 0000000..2c9b561 --- /dev/null +++ b/skills/pdf.md @@ -0,0 +1,171 @@ +# pdf + +- **Autore:** Anthropic +- **Repository:** [anthropics/skills](https://github.com/anthropics/skills), la raccolta di skill di esempio di Anthropic +- **Sorgente:** [skills/pdf/SKILL.md](https://github.com/anthropics/skills/blob/main/skills/pdf/SKILL.md), con le guide [forms.md](https://github.com/anthropics/skills/blob/main/skills/pdf/forms.md) e [reference.md](https://github.com/anthropics/skills/blob/main/skills/pdf/reference.md) e una cartella `scripts/` +- **Pagina su skills.sh:** [anthropics/skills/pdf](https://skills.sh/anthropics/skills/pdf) +- **Diffusione (ottobre 2026):** circa 219.700 installazioni (su skills.sh dal 20 gennaio 2026); il repository ha circa 184.900 stelle e 21.900 fork 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) +- **Licenza:** proprietaria (termini in `LICENSE.txt`). Il README del repository precisa che le skill per i documenti (`docx`, `pdf`, `pptx`, `xlsx`) sono *source-available*, non open source, e che le skill del repository sono dimostrative: conviene provarle bene prima di affidarsi a loro. + +## A cosa serve + +Dà all'agente un metodo per lavorare sui file PDF: leggerli, unirli e dividerli, compilarli, crearne di nuovi e ripulire quelli scansionati. Invece di improvvisare ogni volta con la libreria che gli viene in mente, sceglie lo strumento indicato per ciascun compito. + +## Cosa fa + +### Quando si attiva + +Ogni volta che la richiesta riguarda un file PDF o la sua creazione: + +- leggere o estrarre testo e tabelle, leggere i metadati; +- unire più PDF in uno, dividerne uno in più file, ruotare le pagine; +- aggiungere una filigrana; +- creare un PDF nuovo; +- compilare un modulo; +- proteggere con password o togliere la password; +- estrarre le immagini incorporate; +- fare l'OCR di un PDF scansionato per renderlo ricercabile. + +### Come lavora + +L'agente sceglie lo strumento in base al compito: + +| Compito | Strumento | Come | +|---|---|---| +| Unire | pypdf | aggiunge le pagine di ogni file a un unico file di uscita | +| Dividere | pypdf | scrive una pagina per file | +| Estrarre il testo | pdfplumber | testo pagina per pagina, con il layout | +| Estrarre le tabelle | pdfplumber | tabelle pagina per pagina; si possono convertire in pandas ed esportare in Excel | +| Creare PDF | reportlab | `Canvas` per impaginazioni semplici, `Platypus` per documenti di più pagine con testo che scorre | +| Unire da riga di comando | qpdf | opzione `--empty --pages` | +| OCR | pytesseract | prima converte le pagine in immagini con pdf2image | +| Compilare moduli | pdf-lib o pypdf | segue `forms.md` | + +Esempio di unione, dalla guida: + +```python +from pypdf import PdfWriter, PdfReader + +writer = PdfWriter() +for pdf_file in ["doc1.pdf", "doc2.pdf", "doc3.pdf"]: + reader = PdfReader(pdf_file) + for page in reader.pages: + writer.add_page(page) + +with open("merged.pdf", "wb") as output: + writer.write(output) +``` + +Altre operazioni previste: + +- **Strumenti da riga di comando:** `pdftotext` (poppler-utils) per estrarre il testo, anche con il layout o solo un intervallo di pagine; `qpdf` per unire, dividere per intervallo, ruotare pagine e togliere una password; `pdftk` se è installato. +- **Filigrane:** carica una pagina di filigrana e la sovrappone a ogni pagina. +- **Immagini:** `pdfimages` esporta le immagini incorporate. +- **Password:** copia le pagine in un nuovo file e lo cifra con password utente e proprietario. +- **Pedici e apici:** nei PDF creati con reportlab non usa i caratteri Unicode per pedici e apici, perché i font integrati non li hanno e compaiono come quadrati neri; usa i marcatori `` e `` dentro i `Paragraph`. +- **Casi avanzati:** `reference.md` copre pypdfium2, pdf-lib per JavaScript e la risoluzione dei problemi. Non l'ho letto per intero. + +### Compilare i moduli + +Il flusso è in `forms.md` e dipende dal tipo di PDF. Il primo passo è controllare se il modulo ha campi compilabili (`scripts/check_fillable_fields.py`). + +**PDF con campi compilabili:** + +1. `extract_form_field_info.py` elenca i campi (identificatore, pagina, posizione, tipo: testo, casella, gruppo di opzioni, scelta). +2. `convert_pdf_to_images.py` crea un'immagine per pagina, per capire a cosa serve ogni campo. +3. Si scrive `field_values.json` con i valori da inserire. +4. `fill_fillable_fields.py` compila il modulo; se segnala errori, si correggono e si rilancia. + +**PDF senza campi compilabili:** + +1. `extract_form_structure.py` estrae etichette, linee, caselle e righe. +2. Due approcci: *strutturale* (preferito, se ci sono etichette di testo utili) o *visivo* (per le scansioni, con ingrandimenti fatti con ImageMagick); si possono combinare. +3. `check_bounding_boxes.py` valida i riquadri, perché riquadri sovrapposti o troppo piccoli rovinano il testo. +4. `fill_pdf_form_with_annotations.py` scrive il testo come annotazioni. +5. Si controlla il risultato rendendolo di nuovo in immagini. + +Avvertenze della guida: i passi vanno fatti in ordine; identificatori e valori devono coincidere con quelli estratti; l'estrazione strutturale riconosce solo le caselle quadrate; i sistemi di coordinate dei campi compilabili e dell'approccio strutturale hanno origini diverse, e mescolarli sposta il testo; il risultato va sempre controllato a vista. + +### Da sapere + +- **Requisiti:** librerie Python pypdf, pdfplumber, reportlab, pandas (per esportare le tabelle), pytesseract e pdf2image (per l'OCR); strumenti poppler-utils e qpdf, pdftk facoltativo; ImageMagick per l'approccio visivo dei moduli. Per l'OCR serve anche il programma Tesseract (installato a parte; la guida non lo spiega). +- **Script eseguiti:** per i moduli l'agente lancia gli script della cartella `scripts/` (otto file Python). Non li ho letti uno per uno. +- **Nessun accesso esterno** dichiarato: lavora sui file locali. +- **Limite di fedeltà:** estrazione e OCR non sono perfette su layout complessi o scansioni di bassa qualità; l'autore invita a verificare il risultato. + +## Installazione + +### Claude Code e Codex + +```bash +npx skills add anthropics/skills --skill pdf -g -a codex -a claude-code +``` + +| Opzione | Significato | +|---|---| +| `--skill pdf` | 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 | + +Non ho trovato il comando esatto sulla pagina di skills.sh: è la forma standard dello strumento `skills`, la stessa usata per le altre schede. + +Alternativa solo per Claude Code, dal marketplace di Anthropic (installa tutte le skill per i documenti: `docx`, `pdf`, `pptx`, `xlsx`): + +```text +/plugin marketplace add anthropics/skills +/plugin install document-skills@anthropic-agent-skills +``` + +Dopo l'installazione riavvia la sessione. Claude Code la usa da solo quando la richiesta è pertinente, oppure puoi citarla ("usa la skill PDF per estrarre i campi del modulo `percorso/file.pdf`"). In Codex la richiami con `$pdf` o la vedi con `/skills`. + +Gestione: + +```bash +npx skills list -g # skill installate +npx skills update pdf # aggiornamento +npx skills remove pdf # rimozione +``` + +```text +/plugin uninstall document-skills@anthropic-agent-skills # rimozione del plugin +``` + +### 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/anthropics/skills.git +cd skills/skills && zip -r ~/pdf.zip pdf +``` + +Lo ZIP deve contenere la cartella `pdf/` con dentro `SKILL.md` (e gli altri file della cartella: `forms.md`, `reference.md`, `scripts/`). + +**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 con esecuzione del codice. Funziona solo se lì sono disponibili le librerie e gli strumenti elencati sopra (non l'ho verificato), e legge solo i file che alleghi alla conversazione. Il README del repository dice che le skill di esempio sono già disponibili sui piani a pagamento di Claude.ai, ma non specifica se `pdf` sia tra queste. + +## Fonti + +- [README di anthropics/skills](https://github.com/anthropics/skills) +- [SKILL.md di pdf](https://github.com/anthropics/skills/blob/main/skills/pdf/SKILL.md) +- [forms.md di pdf](https://github.com/anthropics/skills/blob/main/skills/pdf/forms.md) +- [Cartella skills/pdf](https://github.com/anthropics/skills/tree/main/skills/pdf) e [scripts/](https://github.com/anthropics/skills/tree/main/skills/pdf/scripts) +- [pdf su skills.sh](https://skills.sh/anthropics/skills/pdf) +- [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) diff --git a/skills/pptx.md b/skills/pptx.md new file mode 100644 index 0000000..bb8f83c --- /dev/null +++ b/skills/pptx.md @@ -0,0 +1,166 @@ +# pptx + +- **Autore:** Anthropic +- **Repository:** [anthropics/skills](https://github.com/anthropics/skills), la raccolta di skill di esempio di Anthropic +- **Sorgente:** [skills/pptx/SKILL.md](https://github.com/anthropics/skills/blob/main/skills/pptx/SKILL.md), con `LICENSE.txt` e una cartella `scripts/` +- **Pagina su skills.sh:** [anthropics/skills/pptx](https://skills.sh/anthropics/skills/pptx) +- **Diffusione (ottobre 2026):** circa 245.300 installazioni (su skills.sh dal 20 gennaio 2026); il repository ha circa 184.900 stelle e 21.900 fork su GitHub +- **Controlli di sicurezza su skills.sh:** Gen Agent Trust Hub e Snyk superati; Socket segnala un avviso (la pagina non spiega il motivo) +- **Licenza:** proprietaria (termini in `LICENSE.txt`). Il README del repository precisa che le skill per i documenti (`docx`, `pdf`, `pptx`, `xlsx`) sono *source-available*, non open source, e che le skill del repository sono dimostrative: conviene provarle bene prima di affidarsi a loro. + +## A cosa serve + +Fa creare, leggere e modificare presentazioni PowerPoint all'agente, controllando poi il risultato slide per slide. Non si limita a scrivere un file: lo trasforma in immagini, cerca testo che esce dai bordi, sovrapposizioni e problemi di spaziatura, e li corregge prima di consegnare. + +## Cosa fa + +### Quando si attiva + +Ogni volta che la richiesta riguarda un file `.pptx` o `.potx`: + +- creare una presentazione nuova (slide, pitch deck); +- leggere o estrarre il testo di una presentazione; +- modificarne una esistente: duplicare o riordinare slide, cambiare i contenuti; +- partire da un modello (`.potx`), lavorare con layout, note del relatore e commenti. + +### Come lavora + +L'agente sceglie il percorso in base al compito: + +| Compito | Come | +|---|---| +| Creare | scrive uno script **pptxgenjs** (libreria JavaScript) che genera il file | +| Modificare o usare un modello | decomprime il file, modifica l'XML delle slide e lo ricomprime | +| Leggere | estrae il testo con **markitdown** (un blocco per slide) o costruisce una griglia di miniature per vedere i layout | + +Alternativa nominata per la creazione: **python-pptx**, con limiti nella duplicazione delle slide, nella formattazione del testo e in alcuni tipi di immagine. + +**Script di aiuto** (cartella `scripts/`): + +| Script | A cosa serve | +|---|---| +| `thumbnail.py` | griglia di miniature con etichette; ogni presentazione deve avere un prefisso suo, così le griglie non si sovrascrivono | +| `add_slide.py` | duplica slide o layout e gestisce da solo la contabilità interna del pacchetto | +| `clean.py` | toglie slide, immagini e relazioni non più referenziate; va lanciato quando l'elenco delle slide è definitivo | +| `validate.py` | controlla schema, relazioni, tipi di contenuto e grafici; con `--original` per le presentazioni nate da un modello | +| `soffice.py` | avvolge LibreOffice per la conversione senza interfaccia | + +**Controllo di qualità**, in quattro passi: + +1. controlla il contenuto con markitdown: testo mancante, refusi, segnaposto dimenticati; +2. esegue la validazione (con `--original` se parte da un modello); +3. converte in PDF e poi in immagini JPEG e ispeziona ogni slide: bordi, sovrapposizioni, spaziatura, allineamento, contrasto; +4. dopo le correzioni rigenera PDF e immagini dal file modificato e ricontrolla solo le slide cambiate. + +### Regole per modificare + +- prima tutte le modifiche strutturali (aggiungere, togliere, riordinare), poi i contenuti, perché duplicare una slide ne copia lo stato attuale; +- le slide non si copiano a mano, ma con `add_slide.py`; +- l'XML si legge con `defusedxml.minidom` e non con `ElementTree`, per non perdere gli spazi dei nomi; +- gli spazi non usati di un modello vanno rimossi del tutto, con le immagini che contengono; +- un paragrafo per ogni voce di elenco, con i puntini ereditati dal layout. + +### Trappole di pptxgenjs che la skill segnala + +- imposta il layout prima di aggiungere le slide: quello predefinito è 10" × 5,625", non il formato panoramico; +- colori esadecimali senza `#` e senza cifre di trasparenza, altrimenti il file si corrompe; +- non riusare gli stessi oggetti di opzioni tra le chiamate, perché la libreria li modifica; +- gli scostamenti delle ombre non possono essere negativi; +- si usa `charSpacing`, non `letterSpacing`; +- gli elenchi puntati con l'opzione `bullet`, non con caratteri letterali; +- un'istanza del generatore per ogni file di uscita; +- niente sfumature: si usa un'immagine con la sfumatura; +- i grafici restano nativi (quelli in pila non accettano le etichette `outEnd`; i grafici combinati con assi secondari richiedono due voci per `valAxes` e `catAxes`); +- non riordinare mai i figli di ``; +- validare dopo ogni generazione e correggere il problema nel generatore, non nel file. + +### Indicazioni di design + +- una palette adatta all'argomento, con un colore dominante e un accento deciso; +- un elemento visivo per slide (immagine, grafico, icona, forma) e layout vari; +- caratteri sicuri per il corpo del testo (Arial, Calibri, Cambria, Times New Roman e simili); +- titoli da 36-44 pt, intestazioni di sezione da 20-24 pt, testo da 14-16 pt, didascalie da 10-12 pt; +- margini di almeno 0,5" e distanze di 0,3-0,5"; +- da evitare: righe decorative sotto i titoli, barre o strisce colorate, sfondi color crema, testo centrato nel corpo, testo che esce dalla forma. + +### Da sapere + +- **Requisiti:** Node.js con pptxgenjs, Python con markitdown, Pillow, defusedxml e lxml, LibreOffice e Poppler (`pdftoppm`). La skill indica anche react-icons, react, react-dom e sharp tra i pacchetti usati (per le icone). pptxgenjs è dato come già installato nell'ambiente previsto. +- **Script eseguiti:** i cinque della cartella `scripts/`, più i comandi di LibreOffice e `pdftoppm`. Non ho letto i file Python: GitHub non mostrava il contenuto di `scripts/`. +- **Nessun accesso esterno** dichiarato: lavora sui file locali. +- **Qualità del risultato:** il controllo è visivo e lo fa il modello guardando le immagini; non sostituisce una rilettura tua. + +## Installazione + +### Claude Code e Codex + +```bash +npx skills add anthropics/skills --skill pptx -g -a codex -a claude-code +``` + +| Opzione | Significato | +|---|---| +| `--skill pptx` | 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 | + +Non ho trovato il comando esatto sulla pagina di skills.sh: è la forma standard dello strumento `skills`, la stessa usata per le altre schede. + +Alternativa solo per Claude Code, dal marketplace di Anthropic (installa tutte le skill per i documenti: `docx`, `pdf`, `pptx`, `xlsx`): + +```text +/plugin marketplace add anthropics/skills +/plugin install document-skills@anthropic-agent-skills +``` + +Dopo l'installazione riavvia la sessione. Claude Code la usa da solo quando la richiesta è pertinente. In Codex la richiami con `$pptx` o la vedi con `/skills`. + +Gestione: + +```bash +npx skills list -g # skill installate +npx skills update pptx # aggiornamento +npx skills remove pptx # rimozione +``` + +```text +/plugin uninstall document-skills@anthropic-agent-skills # rimozione del plugin +``` + +### 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/anthropics/skills.git +cd skills/skills && zip -r ~/pptx.zip pptx +``` + +Lo ZIP deve contenere la cartella `pptx/` con dentro `SKILL.md` e la cartella `scripts/`. + +**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 con esecuzione del codice. Funziona solo se lì sono disponibili pptxgenjs, LibreOffice e Poppler (non l'ho verificato), e legge solo i file che alleghi alla conversazione. Il README del repository dice che le skill di esempio sono già disponibili sui piani a pagamento di Claude.ai, ma non specifica se `pptx` sia tra queste. + +## Fonti + +- [README di anthropics/skills](https://github.com/anthropics/skills) +- [SKILL.md di pptx](https://github.com/anthropics/skills/blob/main/skills/pptx/SKILL.md) +- [Cartella skills/pptx](https://github.com/anthropics/skills/tree/main/skills/pptx) +- [pptx su skills.sh](https://skills.sh/anthropics/skills/pptx) +- [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) diff --git a/skills/xlsx.md b/skills/xlsx.md new file mode 100644 index 0000000..44d6ecd --- /dev/null +++ b/skills/xlsx.md @@ -0,0 +1,157 @@ +# xlsx + +- **Autore:** Anthropic +- **Repository:** [anthropics/skills](https://github.com/anthropics/skills), la raccolta di skill di esempio di Anthropic +- **Sorgente:** [skills/xlsx/SKILL.md](https://github.com/anthropics/skills/blob/main/skills/xlsx/SKILL.md), con `LICENSE.txt` e una cartella `scripts/` +- **Pagina su skills.sh:** [anthropics/skills/xlsx](https://skills.sh/anthropics/skills/xlsx) +- **Diffusione (ottobre 2026):** circa 190.400 installazioni (su skills.sh dal 19 gennaio 2026); il repository ha circa 184.900 stelle e 21.900 fork su GitHub +- **Controlli di sicurezza su skills.sh:** Gen Agent Trust Hub e Snyk superati; Socket segnala un avviso (la pagina non spiega il motivo). La pagina avverte inoltre che `SKILL.md` contiene direttive di shell che possono eseguire comandi di sistema, da controllare prima di installare. +- **Licenza:** proprietaria (termini in `LICENSE.txt`). Il README del repository precisa che le skill per i documenti (`docx`, `pdf`, `pptx`, `xlsx`) sono *source-available*, non open source, e che le skill del repository sono dimostrative: conviene provarle bene prima di affidarsi a loro. + +## A cosa serve + +Fa creare, modificare, leggere e ripulire fogli di calcolo Excel all'agente, con formule vere (non risultati incollati) e senza errori nei calcoli. Un foglio che l'agente produce da solo si ricalcola quando cambiano i dati, ha una formattazione professionale e viene controllato prima di essere consegnato. + +## Cosa fa + +### Quando si attiva + +Quando un foglio di calcolo è l'ingresso o il risultato principale del lavoro, in formato `.xlsx`, `.xlsm`, `.xltx`, `.csv` o `.tsv`: + +- creare una cartella di lavoro nuova; +- modificare un file esistente, aggiungere colonne, calcolare formule, formattare, fare grafici; +- pulire dati disordinati e trasformarli in un foglio ben fatto; +- convertire tra formati tabellari. + +Non si attiva quando il risultato è un documento Word, un rapporto HTML, uno script a sé, una pipeline su database o un'integrazione con Google Sheets. + +### Come lavora + +1. **Sceglie lo strumento:** + - `openpyxl` per creare e modificare file con formule e formattazione; + - `pandas` (`read_excel`, `to_excel`) per importare ed esportare molti dati; + - `markitdown file.xlsx` per una lettura rapida in sola lettura (non mostra le coordinate delle celle). + Per leggere sia le formule sia i valori di un modello servono due caricamenti del file con `load_workbook`. Le librerie sono già installate: la skill dice di non lanciare `pip install` se non fallisce un `import`. +2. **Scrive formule, non risultati:** il foglio deve ricalcolarsi se cambiano gli ingressi. +3. **Ricalcola e controlla.** `openpyxl` salva le formule senza i valori già calcolati, quindi lancia: + ```bash + python scripts/recalc.py output.xlsx [secondi_di_attesa] + ``` + (30 secondi per impostazione predefinita). LibreOffice ricalcola il file e lo script restituisce un JSON con `status`, `total_formulas`, `total_errors` e `error_summary`. Un'uscita senza errori non garantisce un foglio corretto: la skill dice di provare a mano alcune formule. +4. **Consegna** senza errori di formula; se il file ne aveva già, controlla l'originale prima di dare la colpa al proprio lavoro. + +### Regole per ogni risultato + +- carattere professionale (Arial o Times New Roman), salvo indicazioni diverse; +- nomi dei fogli, intestazioni e formule come li chiedi tu, alla lettera; +- ipotesi e numeri scritti a mano documentati nel file, con la fonte quando possibile; +- se modifica un file esistente: adotta le sue convenzioni, scrive solo nelle celle di ingresso previste e non tocca le formule esistenti. + +### Formule: cosa usa e cosa evita + +| Tipo | Funzioni | +|---|---| +| Preferite (Excel 2007) | `SUMIFS`, `INDEX`, `MATCH`, `IFERROR`, `SUMPRODUCT` | +| Più recenti, con prefisso `_xlfn.` | `TEXTJOIN`, `CONCAT`, `IFS`, `SWITCH`, `MAXIFS`, `MINIFS` | +| Da evitare | `XLOOKUP`, `XMATCH`, `SORT`, `FILTER`, `UNIQUE`, `SEQUENCE` (ordina e filtra in Python) | + +### Trappole di openpyxl che la skill segnala + +- `data_only=True` toglie le formule: salvare quel file le sostituisce per sempre con i valori. +- Nelle celle unite si scrive solo in quella in alto a sinistra. +- I file `.xlsm` vanno aperti con `keep_vba=True`, altrimenti perdono le macro. +- I nomi dei fogli con spazi vanno tra apici nei riferimenti tra fogli. +- Salvare di nuovo una cartella che rimanda ad altri file ne toglie i collegamenti: prima copia i valori. + +### Convenzioni dei modelli finanziari + +Valgono salvo diversa indicazione tua o del file: + +| Elemento | Convenzione | +|---|---| +| Colori | blu per gli ingressi scritti a mano, nero per le formule, verde per i collegamenti ad altri fogli, rosso per quelli ad altri file, sfondo giallo per le ipotesi chiave | +| Numeri | formato valuta con le unità nelle intestazioni, zeri come trattino, negativi tra parentesi, percentuali salvate come frazioni, multipli come `0.0x`, anni salvati come testo | +| Struttura | un'ipotesi per cella con etichetta, formule coerenti tra i periodi, divisori protetti dallo zero | + +### Da sapere + +- **Macro VBA: non le scrive.** La skill non tratta la scrittura né la modifica di codice VBA. Dice soltanto di conservare le macro esistenti aprendo i `.xlsm` con `keep_vba=True`. Per VBA servono altre skill. +- **Grafici e tabelle pivot:** la descrizione dice che copre i grafici, ma il testo non dà indicazioni specifiche su grafici o tabelle pivot. +- **Requisiti:** Python con openpyxl, pandas e markitdown (preinstallati negli ambienti previsti) e LibreOffice (`soffice`), che la skill configura da sola negli ambienti isolati tramite `scripts/office/soffice.py`. +- **Script eseguiti:** `scripts/recalc.py` e `scripts/office/soffice.py`. Non li ho letti uno per uno, e non ho potuto vedere il contenuto della cartella `scripts/` su GitHub. +- **Nessun accesso esterno** dichiarato: lavora sui file locali. + +## Installazione + +### Claude Code e Codex + +```bash +npx skills add anthropics/skills --skill xlsx -g -a codex -a claude-code +``` + +| Opzione | Significato | +|---|---| +| `--skill xlsx` | 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 | + +La pagina di skills.sh indica la forma `npx skills add https://github.com/anthropics/skills --skill xlsx`; la sintassi con `anthropics/skills` è equivalente. + +Alternativa solo per Claude Code, dal marketplace di Anthropic (installa tutte le skill per i documenti: `docx`, `pdf`, `pptx`, `xlsx`): + +```text +/plugin marketplace add anthropics/skills +/plugin install document-skills@anthropic-agent-skills +``` + +Dopo l'installazione riavvia la sessione. Claude Code la usa da solo quando la richiesta è pertinente. In Codex la richiami con `$xlsx` o la vedi con `/skills`. + +Gestione: + +```bash +npx skills list -g # skill installate +npx skills update xlsx # aggiornamento +npx skills remove xlsx # rimozione +``` + +```text +/plugin uninstall document-skills@anthropic-agent-skills # rimozione del plugin +``` + +### 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/anthropics/skills.git +cd skills/skills && zip -r ~/xlsx.zip xlsx +``` + +Lo ZIP deve contenere la cartella `xlsx/` con dentro `SKILL.md` e la cartella `scripts/`. + +**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 con esecuzione del codice. Funziona solo se lì sono disponibili openpyxl, pandas e LibreOffice (non l'ho verificato), e legge solo i file che alleghi alla conversazione. Il README del repository dice che le skill di esempio sono già disponibili sui piani a pagamento di Claude.ai, ma non specifica se `xlsx` sia tra queste. + +## Fonti + +- [README di anthropics/skills](https://github.com/anthropics/skills) +- [SKILL.md di xlsx](https://github.com/anthropics/skills/blob/main/skills/xlsx/SKILL.md) +- [Cartella skills/xlsx](https://github.com/anthropics/skills/tree/main/skills/xlsx) +- [xlsx su skills.sh](https://skills.sh/anthropics/skills/xlsx) +- [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)