Skill: la guida

Le 57 skill di Éclair, in 8 famiglie, aiutano il tuo assistente IA ad aggiungere una funzione al tuo sito Éclair 2.0 senza rompere ciò che funziona. Installale nel progetto, avvia l’agente con il prompt fornito e non attivare nulla prima dei 7 controlli di qualità.

Questa guida descrive ogni passaggio e spiega come scrivere le tue skill. Prima di iniziare, fai un backup come spiega la guida Aggiornare, fare backup, traslocare.

Cosa ti serve prima di iniziare?

• Un sito Éclair 2.0 e, idealmente, una copia di lavoro del codice (il repository ufficiale clonato), perché l’agente possa lanciare i test.
• Python 3 per installare e validare le skill, PHP 8.1 o superiore per gli strumenti di Éclair.
• Un assistente che legge le skill: Claude Code o Codex, per esempio.
• Un backup recente: Sicurezza › Scarica un backup.

Come installare le skill di Éclair nel progetto?

1. Scarica la libreria da GitHub (Code › Download ZIP, o git clone).
2. Nella sua cartella, verifica che sia integra con python3 scripts/validate_skills.py: il messaggio deve indicare 57 skill valide.
3. Elenca famiglie e skill con python3 scripts/install_skills.py --list.
4. Installa ciò che ti serve, per famiglia (--category design) o per nome (--skill eclair-seo-audit), con --project /percorso/del/mio-sito.
5. Per Claude Code, copia le cartelle installate da .agents/skills/ a .claude/skills/.

python3 scripts/validate_skills.py
python3 scripts/install_skills.py --list
python3 scripts/install_skills.py --project /percorso/del/mio-sito --category foundation
python3 scripts/install_skills.py --project /percorso/del/mio-sito --skill eclair-wordpress-migration
python3 scripts/install_skills.py --project /percorso/del/mio-sito --all

Come avviare l’agente con il prompt giusto?

Apri l’assistente nella cartella del progetto e dagli un prompt iniziale chiaro. Questo è fornito con la libreria:

Analizza questo progetto Éclair CMS partendo da eclair/index.php e docs/SKILLS-GUIDE.md. Usa le skill eclair-architecture, eclair-extension-builder, eclair-security-audit ed eclair-test-suite. Descrivi la funzione richiesta in base alle capacità native eclair-extension/1. Crea i file dell’estensione in site/extensions/<id>/ senza modificare il core. Prima di proporre l’attivazione, esegui php tools/validate.php <estensione> --json, php tests/run.php e php tools/measure.php --check. Se manca una capacità, ferma quella parte e crea una RFC e dei test; non inventare API.

Poi aggiungi la tua richiesta in una o due frasi, con i vincoli che contano per te: pubblico, lingue, volume, dati personali.

Quali controlli prima di attivare una funzione?

La libreria definisce sette controlli di qualità. Una funzione si attiva solo quando sono stati superati tutti.

Cosa fare

• Descrivere l’esigenza di business, non la tecnica: l’agente sceglie le skill.
• Lasciare che l’agente legga le capacità del sito prima di scrivere codice.
• Testare su una copia del sito, mai direttamente in produzione.
• Tenere traccia delle decisioni: l’agente scrive una breve nota di architettura.
• Prevedere il ritorno indietro: disattivare una funzione ne conserva i dati.

Cosa non fare

• Modificare app/, assets/, index.php o l’updater: un aggiornamento sovrascriverebbe tutto.
• Attivare una funzione che non ha superato il validatore e i test.
• Mettere in produzione un carrello, un’area riservata o un forum finché il core non ne fornisce il contratto.
• Credere che un punteggio SEO, GEO o Lighthouse sia garantito: sono misure da ripetere.
• Dare all’agente segreti in chiaro: vanno in data/ext/<id>/secrets.php.

Come creare la tua skill?

skills/eclair-mio-settore/
├── SKILL.md
└── references/
    ├── acceptance.md
    └── native-contract.md

1. Crea una cartella skills/eclair-<nome>/ con un file SKILL.md.
2. In cima al file, indica name e una description che dica quando usarla: è ciò che legge l’agente per decidere.
3. Scrivi la diagnosi obbligatoria, la procedura, i risultati attesi, le regole di sicurezza e i criteri di accettazione.
4. Aggiungi i documenti utili in references/: una skill deve essere autonoma.
5. Dichiarala in catalog.json, poi esegui python3 scripts/validate_skills.py e python3 scripts/check_release.py --write.
6. Provala su un progetto reale, poi proponila alla libreria con una pull request.

Cosa fare se qualcosa si blocca?

Il validatore rifiuta il pacchetto: Leggi il messaggio JSON: indica il file o il campo del manifesto in causa. Correggi e rilancia la validazione.

L’agente vuole modificare il core: Rifiuta e ricorda la regola: tutto deve vivere in site/. Se manca una capacità, chiedi una RFC e un test bloccante.

Manca una capacità (account clienti, pagamento…): È normale per alcune famiglie: conserva progetto e test e attendi che il core apra il contratto.

Vedi la libreria su GitHub

Le 57 skill, famiglia per famiglia