La promessa e' potente: trasformare un'idea in una funzionalita' installabile in pochi minuti. Il rischio, pero', e' altrettanto concreto: un plugin generato male puo' aprire problemi di sicurezza, rallentare il sito, salvare dati nel modo sbagliato o entrare in conflitto con altri componenti.

Questa guida mostra un metodo pratico per creare plugin WordPress attraverso l'intelligenza artificiale senza cadere nella trappola del codice casuale. Troverai prompt, architettura, esempi PHP, checklist SEO e riferimenti ufficiali. Se vuoi approfondire il metodo da prompt a codice, leggi anche l'articolo su dal prompt al plugin WordPress, la guida su AI e sviluppo WordPress per progettare e ottimizzare plugin e l'approfondimento sugli hook WordPress per plugin professionali.

Perche' l'AI cambia lo sviluppo dei plugin WordPress

WordPress e' un ecosistema enorme: hook, azioni, filtri, shortcode, REST API, Options API, metadati, ruoli utente, nonce, capability, traduzioni e standard di codice. L'intelligenza artificiale puo' aiutarti a navigare tutto questo piu' velocemente, ma non deve sostituire la comprensione tecnica.

L'AI e' utile soprattutto in cinque aree:

• trasformare un'idea vaga in requisiti tecnici;
• generare boilerplate coerente con WordPress;
• proporre hook, funzioni e struttura dei file;
• revisionare codice alla ricerca di errori;
• scrivere documentazione, readme e checklist di test.

Il punto chiave e' questo: un modello linguistico puo' produrre codice plausibile, ma non ha la responsabilita' del sito. Quella resta tua. Per questo conviene lavorare con un workflow ripetibile, non con prompt improvvisati.

Il workflow corretto: dall'idea al plugin installabile

Il metodo piu' sicuro per creare plugin WordPress con AI e' diviso in sette fasi. Ogni fase ha un obiettivo preciso e una verifica concreta.

1. Definisci il problema che il plugin deve risolvere.
2. Trasforma l'idea in requisiti funzionali e tecnici.
3. Chiedi all'AI una struttura minima, non un plugin gigante.
4. Genera il codice un file alla volta.
5. Fai revisionare sicurezza, naming e compatibilita'.
6. Testa in locale o staging con debug attivo.
7. Documenta uso, limiti e manutenzione.

Questo flusso si integra bene con un workflow piu' ampio di sviluppo WordPress con AI per temi e plugin, soprattutto quando lavori su progetti cliente o siti con traffico reale.

Prima di scrivere codice: il prompt di analisi

L'errore piu' comune e' chiedere subito: "creami un plugin WordPress". E' il modo piu' rapido per ottenere codice generico. Prima devi chiedere all'AI di chiarire il progetto.

Usa un prompt come questo:

Agisci come sviluppatore WordPress senior specializzato in plugin sicuri e manutenibili.

Voglio creare un plugin WordPress chiamato "MRT Reading CTA".
Obiettivo: aggiungere automaticamente alla fine degli articoli un box con tempo di lettura stimato e una call to action configurabile.

Prima di scrivere codice, produci:
1. requisiti funzionali;
2. requisiti di sicurezza;
3. hook WordPress necessari;
4. dati da salvare e dove salvarli;
5. struttura minima dei file;
6. rischi tecnici;
7. checklist di test.

Non generare ancora codice PHP.

Questo prompt forza il modello a progettare prima di produrre. La qualita' del risultato aumenta perche' il codice nasce da un perimetro chiaro.

Struttura minima consigliata

Per un plugin semplice non serve un framework interno. Serve una struttura leggibile, con nomi coerenti e pochi file.

mrt-reading-cta/
├── mrt-reading-cta.php
├── includes/
│   └── admin-settings.php
├── assets/
│   └── css/
│       └── frontend.css
└── readme.txt

Questa struttura basta per un plugin piccolo con impostazioni admin e output frontend. Se il plugin cresce, puoi separare shortcode, REST API, integrazioni esterne e classi dedicate. Ma all'inizio la semplicita' e' una forma di sicurezza.

Esempio pratico: plugin con tempo di lettura e CTA

Immaginiamo di creare un plugin che aggiunge alla fine di ogni articolo un box con tempo di lettura stimato e link a un servizio. E' un caso reale, utile per blog, content marketing e siti editoriali.

Ecco un esempio minimale, pensato per mostrare i concetti fondamentali:

<?php
/**
 * Plugin Name: MRT Reading CTA
 * Description: Aggiunge un box con tempo di lettura stimato e call to action alla fine degli articoli.
 * Version: 0.1.0
 * Author: MrTux
 * Text Domain: mrt-reading-cta
 */

if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

define( 'MRT_READING_CTA_VERSION', '0.1.0' );

add_filter( 'the_content', 'mrt_reading_cta_append_box' );

function mrt_reading_cta_append_box( $content ) {
    if ( ! is_singular( 'post' ) || ! in_the_loop() || ! is_main_query() ) {
        return $content;
    }

    $plain_text = wp_strip_all_tags( $content );
    $word_count = str_word_count( $plain_text );
    $minutes    = max( 1, (int) ceil( $word_count / 220 ) );
    $cta_url    = get_option( 'mrt_reading_cta_url', home_url( '/contatti/' ) );

    $box  = '<div class="mrt-reading-cta">';
    $box .= '<p><strong>' . esc_html( sprintf( 'Tempo di lettura: %d minuti', $minutes ) ) . '</strong></p>';
    $box .= '<p>' . esc_html__( 'Vuoi trasformare questa idea in un plugin su misura?', 'mrt-reading-cta' ) . '</p>';
    $box .= '<a href="' . esc_url( $cta_url ) . '">' . esc_html__( 'Richiedi una consulenza WordPress', 'mrt-reading-cta' ) . '</a>';
    $box .= '</div>';

    return $content . $box;
}

Questo snippet mostra gia' alcuni principi importanti:

• blocco dell'accesso diretto con ABSPATH;
• uso di the_content solo nei post singoli;
• controllo su loop principale e query principale;
• escape dell'URL con esc_url();
• escape del testo con esc_html() ed esc_html__();
• opzione configurabile con fallback sicuro.

Non e' ancora un plugin commerciale, ma e' una base sensata. Da qui puoi chiedere all'AI di aggiungere una pagina impostazioni, un file CSS, traduzioni e test.

Prompt per aggiungere una pagina impostazioni

La pagina impostazioni e' una delle parti dove l'AI sbaglia piu' spesso. Puo' dimenticare nonce, capability o sanitizzazione. Devi quindi essere molto esplicito.

Partendo dal plugin MRT Reading CTA, aggiungi una pagina impostazioni sotto "Impostazioni > Reading CTA".

Vincoli obbligatori:
- accesso solo a utenti con capability manage_options;
- salvataggio di una singola opzione mrt_reading_cta_url;
- campo URL sanificato con esc_url_raw;
- form protetto da nonce;
- output sempre escapato;
- text domain mrt-reading-cta;
- nessun framework esterno;
- codice compatibile con WordPress 6.x e PHP 8.1.

Restituisci solo il codice necessario e spiega quali parti devo testare.

Un prompt cosi' riduce il rischio di codice superficiale. Non basta dire "sicuro": devi specificare cosa significa sicurezza in WordPress.

Sicurezza: la checklist che l'AI deve rispettare

La sicurezza e' il confine tra un esperimento e un plugin installabile. Quando usi AI per generare codice WordPress, controlla sempre questi elementi.

Le fonti ufficiali restano indispensabili: consulta il WordPress Plugin Handbook, la sezione sulla sicurezza dei plugin WordPress, la documentazione su validazione, sanitizzazione ed escaping e le linee guida per plugin WordPress.org.

Come usare l'AI per fare code review

Dopo aver generato il codice, cambia ruolo al modello. Non chiedergli di "migliorare" il plugin. Chiedigli di fare revisione tecnica con vincoli stretti.

Analizza questo plugin WordPress come revisore senior.
Non riscrivere tutto.
Segnala solo problemi concreti in queste aree:
1. capability mancanti o sbagliate;
2. nonce assenti;
3. input non sanificati;
4. output non escapati;
5. uso scorretto di hook;
6. naming collision;
7. problemi di compatibilita' PHP/WordPress;
8. possibili warning con WP_DEBUG attivo.

Per ogni problema dammi: rischio, riga coinvolta e patch minima.

Questo tipo di prompt rende l'AI piu' utile. La obbliga a cercare difetti verificabili invece di proporre refactoring estetici.

Test in staging con WP-CLI

Un plugin generato con AI non va mai testato direttamente sul sito live. Crea uno staging o un ambiente locale. Poi usa comandi semplici e ripetibili.

# verifica che WordPress veda il plugin
wp plugin list

# attiva il plugin
wp plugin activate mrt-reading-cta

# controlla l'opzione salvata
wp option get mrt_reading_cta_url

# disattiva il plugin per verificare rollback base
wp plugin deactivate mrt-reading-cta

La documentazione di WP-CLI e' fondamentale per trasformare i test in una procedura ripetibile. Per controlli piu' avanzati puoi usare anche WordPress Coding Standards, utile per intercettare problemi di stile e sicurezza ricorrenti.

AI, REST API e integrazioni esterne

Molti plugin moderni integrano servizi AI esterni: OpenAI, Claude, Gemini, modelli locali o API proprietarie. Qui serve ancora piu' attenzione. Un plugin che invia prompt, dati utente o contenuti a servizi esterni deve considerare privacy, timeout, gestione errori e consenso.

Se il plugin usa endpoint REST, non lasciare mai permessi vaghi. La documentazione della WordPress REST API mostra come registrare route e callback in modo corretto.

Esempio di endpoint protetto:

add_action( 'rest_api_init', function () {
    register_rest_route(
        'mrt-reading-cta/v1',
        '/settings',
        array(
            'methods'             => 'POST',
            'callback'            => 'mrt_reading_cta_save_settings',
            'permission_callback' => function () {
                return current_user_can( 'manage_options' );
            },
        )
    );
} );

Se l'AI propone __return_true come permission_callback, chiedi una giustificazione. Per dati pubblici puo' essere accettabile. Per impostazioni, azioni admin o contenuti riservati e' quasi sempre un errore.

Come trasformare un plugin AI in contenuto SEO

Creare plugin WordPress con l'intelligenza artificiale puo' diventare anche una strategia editoriale. Ogni plugin risolve un problema specifico e quel problema puo' diventare un articolo, una guida, una landing page o un case study.

Il formato che funziona meglio e':

• problema reale del lettore;
• soluzione con plugin;
• prompt usato;
• codice spiegato;
• errori corretti;
• checklist di sicurezza;
• risultato finale.

Questo e' lo stesso principio che trovi nei contenuti su plugin AI per WordPress dedicati a contenuti, SEO e automazione: l'AI diventa utile quando viene collegata a un risultato concreto, misurabile e replicabile.

Errori da evitare

Quando crei plugin WordPress attraverso l'AI, evita questi errori.

• Pubblicare codice generato senza leggerlo.
• Installare il plugin direttamente in produzione.
• Dimenticare nonce nei form admin.
• Usare capability troppo permissive.
• Stampare dati utente senza escape.
• Creare tabelle custom quando bastano opzioni o meta.
• Caricare CSS e JavaScript su tutte le pagine senza motivo.
• Salvare API key in chiaro senza valutare permessi e privacy.
• Fidarti di funzioni WordPress inventate o obsolete.
• Chiedere all'AI un plugin enorme invece di procedere per moduli.

La regola e' semplice: se non sai spiegare cosa fa ogni blocco di codice, non e' ancora pronto.

Le migliori risorse da tenere aperte

Quando lavori con AI e WordPress, tieni sempre aperte queste risorse ufficiali e tecniche:

• WordPress Plugin Handbook per struttura, API e standard di sviluppo.
• WordPress Hooks Reference per verificare azioni e filtri.
• Plugin Security Handbook per nonce, capability e gestione input/output.
• WordPress REST API Handbook per endpoint e permission callback.
• WP-CLI Handbook per test, automazione e gestione da terminale.
• WordPress Coding Standards per controlli di qualita' sul codice PHP.
• OpenAI API Documentation se vuoi integrare modelli AI esterni in un plugin.

Checklist finale prima della pubblicazione

Prima di considerare pronto un plugin generato con AI, verifica questi punti.

1. Il plugin ha uno scopo chiaro in una frase.
2. Il nome dello slug e il prefisso delle funzioni sono coerenti.
3. Tutti i file bloccano accesso diretto.
4. Ogni form admin usa nonce.
5. Ogni azione sensibile controlla le capability.
6. Ogni input e' validato o sanificato.
7. Ogni output e' escapato.
8. Il plugin si attiva e disattiva senza errori.
9. WP_DEBUG non mostra warning o notice.
10. Il codice e' stato testato in staging.
11. Il readme spiega installazione, uso e limiti.
12. Eventuali API esterne hanno timeout e gestione errori.

Questa checklist puo' diventare un prompt finale:

Verifica questo plugin contro la checklist seguente.
Non proporre nuove funzionalita'.
Segnala solo i punti non rispettati e suggerisci la correzione minima.

Conclusione

Creare plugin WordPress attraverso l'intelligenza artificiale e' una delle applicazioni piu' concrete dell'AI nello sviluppo web. Il vantaggio non e' solo scrivere codice piu' velocemente. Il vero vantaggio e' ridurre il tempo tra idea, prototipo, revisione e test.

La differenza tra un plugin utile e un rischio per il sito sta nel metodo. Usa l'AI per chiarire requisiti, generare una base, revisionare codice e preparare documentazione. Usa la tua competenza per decidere architettura, sicurezza, compatibilita' e pubblicazione.

Se vuoi iniziare oggi, scegli una funzionalita' piccola: uno shortcode, un box CTA, una pagina impostazioni, un'integrazione semplice. Genera poco codice, controllalo bene, testalo in staging e miglioralo a piccoli passi. E' cosi' che l'intelligenza artificiale diventa uno strumento professionale, non una scorciatoia pericolosa.

Per chi lavora su siti WordPress, questo cambia il metodo. Invece di chiedere all'AI "crea un tema moderno", conviene progettare un sistema leggibile da persone e agenti: brief, pagine, componenti, token, accessibilità, template, pattern e test. È lo stesso cambio di mentalità che ho già approfondito parlando di web design WordPress con Novamira.ai e di temi WordPress generati dall'intelligenza artificiale: l'AI funziona meglio quando ha un perimetro tecnico preciso.

In questa guida vediamo un flusso completo: prima si scrive la specifica, poi si usa Google Stitch per esplorare l'interfaccia, quindi si traduce il design in DESIGN.md, si implementa un block theme WordPress con theme.json, template e pattern, e infine si controlla tutto con prompt mirati, WP-CLI e test manuali. Se vuoi ripassare le basi tradizionali, puoi affiancare questa guida a come creare un tema WordPress da zero.

La tesi è semplice: il tema non deve emergere dal codice per tentativi. Deve derivare da una specifica. Il codice è una conseguenza, non il punto di partenza.

Perché partire da una specifica prima del codice

Per progettare in modo efficace un tema WordPress con standard attuali bisogna insistere su un punto: chi usa bene gli agenti AI non salta la parte difficile, salta solo la parte più meccanica dell'implementazione. Nel caso di un tema WordPress, la parte difficile non è creare una cartella in wp-content/themes. È decidere cosa il tema deve fare, cosa non deve toccare, come deve comportarsi nel Site Editor, quali blocchi deve supportare e quali vincoli non possono essere violati.

Una specifica utile deve rispondere almeno a queste domande:

• Quale problema risolve il tema e per quale pubblico?
• Quali pagine e template sono indispensabili al primo rilascio?
• Quali componenti devono essere riutilizzabili come pattern Gutenberg?
• Quali token regolano colori, font, spaziature, raggi, ombre e layout?
• Quali file l'agente AI può modificare e quali deve lasciare intatti?
• Quali criteri definiscono "finito": responsive, accessibilità, performance, SEO, compatibilità editor?

Questa è la differenza tra vibe coding casuale e sviluppo assistito serio: non chiedi all'AI di indovinare, le dai un contratto operativo.

Architettura del workflow

Il flusso consigliato è diviso in sette fasi. Ogni fase produce un output che diventa input per la successiva.

Step 1: scrivere il brief tecnico del tema

Prima di aprire Stitch o un editor, crea un file SPEC.md. Questo file descrive il risultato atteso in modo verificabile.

# SPEC.md - Tema WordPress per studio professionale

## Obiettivo
Creare un block theme WordPress per uno studio di consulenza B2B.
Il tema deve comunicare autorevolezza, chiarezza, velocità e affidabilità.

## Pagine prioritarie
- Homepage
- Servizi
- Caso studio
- Blog
- Contatti
- 404

## Vincoli
- Nessun page builder esterno.
- Compatibile con Site Editor e Gutenberg.
- Tutte le sezioni riutilizzabili devono diventare pattern.
- Nessun H1 duplicato nei template.
- Palette e tipografia governate da theme.json.
- CSS custom ridotto al minimo.

## Criteri di completamento
- Mobile, tablet e desktop senza overflow.
- Contrasto WCAG AA sulle CTA principali.
- Template principali presenti in /templates.
- Header e footer presenti in /parts.
- Pattern registrati in /patterns.
- Score PageSpeed da verificare prima del rilascio.

Il prompt iniziale per l'agente AI non deve chiedere codice. Deve chiedere di verificare la specifica.

Agisci come senior WordPress theme architect.

Leggi questa specifica per un block theme WordPress.
Non generare codice.

Task:
1. Trova requisiti ambigui.
2. Elenca decisioni mancanti.
3. Proponi una struttura file coerente con un block theme moderno.
4. Indica quali parti devono diventare template e quali pattern.
5. Restituisci solo una checklist tecnica approvabile.

SPEC:
[incolla qui SPEC.md]

Step 2: progettare le prime schermate con Google Stitch

Google descrive Stitch come un canvas AI-native per creare, iterare e collaborare su UI ad alta fedeltà usando linguaggio naturale. Nel workflow WordPress non va usato come scorciatoia per copiare HTML a caso, ma come strumento di esplorazione: produce direzioni visive, layout e varianti che poi vanno convertite in un sistema WordPress mantenibile.

Un prompt efficace per Stitch deve contenere obiettivo, pubblico, tono, struttura e vincoli. Ecco un esempio pronto.

Design a responsive WordPress block theme homepage for a B2B consulting studio.

Business goal:
Generate qualified leads for consulting calls.

Audience:
Small business owners and marketing managers who need a reliable WordPress partner.

Visual direction:
Clean, editorial, professional, calm. Avoid generic SaaS gradients and oversized decorative blobs.

Page structure:
1. Header with logo, navigation and primary CTA.
2. Hero with clear value proposition and one CTA.
3. Trust strip with service areas.
4. Services grid with 3 cards.
5. Case study preview.
6. Process section with 4 steps.
7. FAQ.
8. Final CTA.
9. Footer with contacts and legal links.

Constraints:
- Design must translate cleanly into WordPress Gutenberg blocks.
- Use reusable sections that can become block patterns.
- Keep text readable on mobile.
- Use accessible contrast for buttons and links.

Dopo aver ottenuto una variante convincente, non fermarti allo screenshot. Chiedi a Stitch o all'agente di estrarre le decisioni di design: palette, font, scala tipografica, spacing, componenti e stati. Queste informazioni diventano il materiale per DESIGN.md.

Step 3: trasformare il design in DESIGN.md

DESIGN.md è utile perché rende esplicito il design system in un formato testuale leggibile dagli agenti. Il repository ufficiale di Google Labs include anche comandi CLI per validare, confrontare ed esportare token. La documentazione WordPress, invece, indica theme.json come il file fondamentale per impostazioni e stili globali di un block theme. Il ponte naturale è questo: DESIGN.md governa il linguaggio visivo, theme.json lo applica in WordPress.

Un esempio essenziale di DESIGN.md per il tema potrebbe essere:

# DESIGN.md

## Brand
Name: Studio Atlas
Personality: clear, practical, reliable, technical.
Audience: business owners, marketing managers, WordPress site owners.

## Color Tokens
- primary: #1E3A5F
- primary-hover: #15304F
- accent: #D97706
- background: #F7F8FA
- surface: #FFFFFF
- text: #17202A
- muted: #5F6B7A
- border: #D9DEE7

## Typography
- heading-font: Inter Tight, system-ui, sans-serif
- body-font: Inter, system-ui, sans-serif
- h1: 56px / 1.08 / 700
- h2: 40px / 1.15 / 700
- h3: 26px / 1.25 / 650
- body: 18px / 1.7 / 400
- small: 14px / 1.5 / 400

## Spacing
- xs: 8px
- sm: 16px
- md: 24px
- lg: 40px
- xl: 64px
- section: 96px

## Components
Button primary:
- background: primary
- text: #FFFFFF
- radius: 6px
- padding: 14px 22px
- hover: primary-hover
- focus: 2px solid accent

Card:
- background: surface
- border: 1px solid border
- radius: 8px
- padding: 24px
- no decorative shadow unless needed for hierarchy

## WordPress Rules
- Prefer core blocks and patterns.
- Avoid hard-coded inline styles in templates.
- Put global decisions in theme.json.
- Use CSS only for behavior not expressible through theme.json.

Prima di usare questo file come contesto per un agente, validalo. La CLI ufficiale consente il controllo strutturale.

# comando lint
npx @google/design.md lint DESIGN.md

Quando fai evolvere il design, confronta due versioni per evitare regressioni nei token.

# confronto due versioni
npx @google/design.md diff DESIGN.md DESIGN-v2.md

Step 4: creare lo scheletro del block theme

Un tema a blocchi moderno parte da pochi file ordinati. La documentazione ufficiale WordPress ricorda che i block theme usano blocchi per tutte le parti del sito, inclusi header, contenuto e footer. Per questo conviene progettare la struttura in modo compatibile con Site Editor.

studio-atlas/
├── style.css
├── functions.php
├── theme.json
├── screenshot.png
├── templates/
│   ├── index.html
│   ├── front-page.html
│   ├── single.html
│   ├── page.html
│   ├── archive.html
│   └── 404.html
├── parts/
│   ├── header.html
│   └── footer.html
├── patterns/
│   ├── hero-consulenza.php
│   ├── servizi-grid.php
│   ├── processo.php
│   ├── faq.php
│   └── cta-finale.php
└── assets/
    ├── css/
    └── js/

Il file style.css contiene l'intestazione riconosciuta da WordPress.

/*
Theme Name: Studio Atlas
Theme URI: https://example.com/studio-atlas
Author: Emilio Petrozzi
Description: Block theme WordPress progettato con DESIGN.md, Google Stitch e specifiche AI.
Version: 1.0.0
Requires at least: 6.5
Tested up to: 6.9
Requires PHP: 8.0
Text Domain: studio-atlas
*/

Il prompt per generare lo scheletro deve limitare il raggio d'azione dell'agente.

Agisci come sviluppatore senior WordPress specializzato in block theme.

Contesto:
- SPEC.md definisce requisiti e pagine.
- DESIGN.md definisce token e componenti.

Task:
Crea lo scheletro del tema "studio-atlas".

Vincoli:
- Non creare plugin.
- Non usare page builder.
- Non inserire CSS inline nei template.
- Usa theme.json per colori, font, spacing e layout.
- Crea solo file necessari al primo rilascio.

Output:
1. Alberatura file.
2. Contenuto di style.css.
3. Contenuto minimo di functions.php.
4. Contenuto iniziale di theme.json.
5. Note sui file da completare dopo approvazione.

Step 5: tradurre DESIGN.md in theme.json

theme.json è il punto in cui il design system diventa editoriale: palette, tipografia, spaziature e layout appaiono sia nel frontend sia nell'editor. WordPress lo definisce una lingua comune tra tema, plugin, utenti e interfaccia di editing.

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 2,
  "settings": {
    "appearanceTools": true,
    "layout": {
      "contentSize": "760px",
      "wideSize": "1180px"
    },
    "color": {
      "palette": [
        { "slug": "primary", "name": "Primary", "color": "#1E3A5F" },
        { "slug": "accent", "name": "Accent", "color": "#D97706" },
        { "slug": "background", "name": "Background", "color": "#F7F8FA" },
        { "slug": "surface", "name": "Surface", "color": "#FFFFFF" },
        { "slug": "text", "name": "Text", "color": "#17202A" },
        { "slug": "muted", "name": "Muted", "color": "#5F6B7A" }
      ]
    },
    "typography": {
      "fontFamilies": [
        {
          "slug": "inter",
          "name": "Inter",
          "fontFamily": "Inter, system-ui, sans-serif"
        },
        {
          "slug": "inter-tight",
          "name": "Inter Tight",
          "fontFamily": "\"Inter Tight\", Inter, system-ui, sans-serif"
        }
      ],
      "fontSizes": [
        { "slug": "small", "name": "Small", "size": "14px" },
        { "slug": "base", "name": "Base", "size": "18px" },
        { "slug": "h2", "name": "Heading 2", "size": "40px" },
        { "slug": "hero", "name": "Hero", "size": "56px" }
      ]
    },
    "spacing": {
      "spacingScale": {
        "steps": 0
      },
      "spacingSizes": [
        { "slug": "sm", "name": "Small", "size": "16px" },
        { "slug": "md", "name": "Medium", "size": "24px" },
        { "slug": "lg", "name": "Large", "size": "40px" },
        { "slug": "xl", "name": "Extra Large", "size": "64px" }
      ]
    }
  },
  "styles": {
    "color": {
      "background": "var:preset|color|background",
      "text": "var:preset|color|text"
    },
    "typography": {
      "fontFamily": "var:preset|font-family|inter",
      "fontSize": "var:preset|font-size|base",
      "lineHeight": "1.7"
    },
    "elements": {
      "heading": {
        "typography": {
          "fontFamily": "var:preset|font-family|inter-tight",
          "lineHeight": "1.15"
        }
      },
      "button": {
        "border": {
          "radius": "6px"
        },
        "color": {
          "background": "var:preset|color|primary",
          "text": "var:preset|color|surface"
        }
      }
    }
  }
}

Prompt consigliato per questa conversione:

Agisci come WordPress block theme engineer.

Input:
- DESIGN.md con token colore, tipografia, spacing e componenti.
- SPEC.md con vincoli del tema.

Task:
Genera un theme.json compatibile con WordPress 6.5+.

Regole:
- Usa version 2 e $schema ufficiale.
- Inserisci palette, fontFamilies, fontSizes, spacingSizes e layout.
- Evita valori duplicati non necessari.
- Non generare template.
- Non usare commenti nel JSON.

Output:
Solo JSON valido.

Step 6: creare template e parti riutilizzabili

I template HTML di un block theme sono markup Gutenberg. L'obiettivo non è replicare pixel per pixel l'output di Stitch, ma ricostruire le sezioni usando blocchi core, classi coerenti e pattern.

Esempio di parts/header.html:

<!-- wp:group {"align":"full","style":{"spacing":{"padding":{"top":"16px","bottom":"16px"}}},"layout":{"type":"constrained"}} -->
<div class="wp-block-group alignfull" style="padding-top:16px;padding-bottom:16px">
  <!-- wp:group {"layout":{"type":"flex","justifyContent":"space-between","flexWrap":"wrap"}} -->
  <div class="wp-block-group">
    <!-- wp:site-title {"level":0} /-->
    <!-- wp:navigation {"layout":{"type":"flex","justifyContent":"right"}} /-->
    <!-- wp:buttons -->
    <div class="wp-block-buttons">
      <!-- wp:button -->
      <div class="wp-block-button"><a class="wp-block-button__link wp-element-button">Prenota una consulenza</a></div>
      <!-- /wp:button -->
    </div>
    <!-- /wp:buttons -->
  </div>
  <!-- /wp:group -->
</div>
<!-- /wp:group -->

Prompt per generare template senza perdere controllo:

Agisci come Gutenberg block theme developer.

Task:
Crea i template HTML per:
- front-page.html
- single.html
- archive.html
- 404.html
- parts/header.html
- parts/footer.html

Vincoli:
- Usa solo markup di blocchi core WordPress.
- Non creare un H1 nel contenuto se il template già usa post-title.
- Usa template parts per header e footer.
- Le sezioni complesse devono richiamare pattern, non duplicare markup.
- Non usare CSS inline salvo padding/spaziature supportate dai blocchi.

Output:
Un file alla volta, con percorso e contenuto completo.

Step 7: convertire le sezioni in pattern Gutenberg

I pattern sono il punto in cui un tema diventa davvero usabile. Un cliente o editor può inserire una hero, una CTA o una FAQ senza chiedere modifiche al codice. Un pattern PHP minimo contiene intestazione e markup blocchi.

<?php
/**
 * Title: Hero consulenza
 * Slug: studio-atlas/hero-consulenza
 * Categories: featured
 */
?>

<!-- wp:group {"align":"full","style":{"spacing":{"padding":{"top":"96px","bottom":"80px"}}},"backgroundColor":"background","layout":{"type":"constrained"}} -->
<div class="wp-block-group alignfull has-background-background-color has-background" style="padding-top:96px;padding-bottom:80px">
  <!-- wp:heading {"level":1,"fontSize":"hero"} -->
  <h1 class="wp-block-heading has-hero-font-size">Un sito WordPress più chiaro, veloce e facile da gestire</h1>
  <!-- /wp:heading -->

  <!-- wp:paragraph {"fontSize":"base"} -->
  <p class="has-base-font-size">Progettiamo temi WordPress su misura con design system, Gutenberg e workflow AI controllati.</p>
  <!-- /wp:paragraph -->

  <!-- wp:buttons -->
  <div class="wp-block-buttons">
    <!-- wp:button -->
    <div class="wp-block-button"><a class="wp-block-button__link wp-element-button">Richiedi una consulenza</a></div>
    <!-- /wp:button -->
  </div>
  <!-- /wp:buttons -->
</div>
<!-- /wp:group -->

Per pattern più complessi, come pricing o FAQ, chiedi prima all'agente una lista di campi modificabili. Poi genera il markup. Questo riduce il rischio di sezioni belle ma scomode da gestire.

Step 8: aggiungere funzioni WordPress minime

Un block theme pulito deve avere un functions.php essenziale. Evita di trasformarlo in un plugin mascherato: registra asset, supporti e piccole ottimizzazioni legate al tema. Per logiche avanzate, meglio creare un plugin dedicato. Puoi approfondire la logica degli hook nella guida su azioni e filter WordPress.

<?php
/**
 * Studio Atlas theme setup.
 */

add_action('after_setup_theme', function () {
    add_theme_support('wp-block-styles');
    add_theme_support('editor-styles');
    add_editor_style('assets/css/editor.css');
});

add_action('wp_enqueue_scripts', function () {
    wp_enqueue_style(
        'studio-atlas-style',
        get_stylesheet_uri(),
        array(),
        wp_get_theme()->get('Version')
    );
});

add_filter('should_load_separate_core_block_assets', '__return_true');

Se servono interazioni più evolute, valuta la Interactivity API, disponibile in WordPress Core dalla versione 6.5 tramite il pacchetto @wordpress/interactivity. Non usarla per tutto: è utile quando l'interazione appartiene a blocchi e componenti, non per animazioni decorative superflue.

Prompt ottimizzati per implementare il tema passo passo

La regola operativa è: un prompt, un risultato verificabile. Non chiedere all'agente di "fare tutto il tema" in una volta sola. Spezza il lavoro.

Prompt 1: revisione architetturale

Agisci come reviewer senior WordPress.

Analizza SPEC.md e DESIGN.md.
Non scrivere codice.

Dimmi:
1. Quali requisiti sono incompleti.
2. Quali rischi tecnici vedi.
3. Quali template e pattern sono davvero necessari.
4. Quali decisioni devono finire in theme.json.
5. Quali controlli fare prima del rilascio.

Prompt 2: implementazione controllata

Agisci come implementatore WordPress.

Task:
Implementa solo theme.json e style.css.

Input:
- SPEC.md
- DESIGN.md

Vincoli:
- Non modificare template.
- Non creare pattern.
- Non aggiungere dipendenze.
- Mantieni JSON valido.
- Usa token coerenti con DESIGN.md.

Dopo l'implementazione:
1. Spiega le scelte.
2. Elenca cosa resta da fare.
3. Suggerisci un comando di verifica.

Prompt 3: generazione pattern

Agisci come Gutenberg pattern designer.

Task:
Crea il pattern "servizi-grid.php".

Requisiti:
- 3 card servizio.
- Ogni card ha titolo, testo breve e link.
- Usa colori e font di theme.json.
- Markup compatibile con blocchi core.
- Nessun CSS custom nel pattern.

Output:
Solo contenuto completo del file PHP.

Prompt 4: QA finale

Agisci come QA engineer WordPress.

Analizza il tema appena creato.

Controlla:
- Struttura file.
- Validità theme.json.
- Presenza template principali.
- Presenza header e footer.
- Pattern registrati.
- Possibili H1 duplicati.
- Accessibilità base.
- Responsive risk.
- SEO tecnica.

Output:
Tabella con problema, severità, file coinvolto e correzione consigliata.

Verifiche tecniche prima della pubblicazione

Quando il tema è pronto, installalo prima in locale o staging. Se hai WP-CLI disponibile, puoi automatizzare alcune verifiche.

# verifica temi installati
wp theme list

Attiva il tema solo in ambiente di test.

# attivazione in staging
wp theme activate studio-atlas

Controlla che WordPress non segnali errori PHP dopo l'attivazione.

# controllo errori recenti
wp eval 'echo "Tema attivo: " . wp_get_theme()->get("Name");'

La checklist finale deve includere:

• Homepage leggibile su mobile senza overflow orizzontale.
• Menu e CTA accessibili da tastiera.
• Un solo H1 per pagina.
• Contrasto sufficiente per testo, link e pulsanti.
• Template per singolo articolo, pagina, archivio e 404.
• Pattern modificabili nel Site Editor.
• Nessun contenuto essenziale hard-coded se deve essere gestito dal cliente.
• Font caricati in modo efficiente.
• Performance controllata con PageSpeed Insights.

Errori comuni da evitare

Il primo errore è usare Stitch come se producesse direttamente un tema WordPress finito. Può aiutare molto nella direzione UI, ma il tema deve rispettare gerarchie WordPress, Gutenberg, template parts e manutenzione futura.

Il secondo errore è mettere tutto in CSS. Se palette, font e spacing finiscono solo in style.css, l'editor non riflette davvero il design system. Il cliente vedrà opzioni incoerenti e tenderà a rompere il layout.

Il terzo errore è chiedere all'AI output troppo ampi. Prompt enormi come "crea tutto il tema" generano codice plausibile ma difficile da verificare. Meglio far lavorare l'agente su una porzione alla volta, con file e confini chiari.

Il quarto errore è non documentare le decisioni. Se il tema evolve, aggiorna SPEC.md e DESIGN.md. Altrimenti l'agente continuerà a lavorare su istruzioni vecchie e produrrà incoerenze.

Risorse utili

• Google Stitch: canvas AI per esplorare interfacce e prototipi.
• Blog Google su Stitch e vibe design: panoramica ufficiale dell'evoluzione di Stitch.
• Google Labs DESIGN.md: specifica, CLI, lint, diff ed export token.
• Documentazione WordPress su theme.json: base tecnica per stili globali e impostazioni.
• Documentazione WordPress sui block theme: introduzione al modello Site Editor.
• Interactivity API: standard WordPress per blocchi interattivi moderni.

FAQ

Posso creare un tema WordPress completo solo con Stitch?

No, non in modo professionale. Stitch è utile per ideazione, layout e direzione visiva. Un tema WordPress completo richiede struttura del tema, theme.json, template, pattern, compatibilità Gutenberg, test e controlli tecnici.

DESIGN.md sostituisce theme.json?

No. DESIGN.md documenta il design system in forma leggibile dagli agenti AI. theme.json applica quelle decisioni dentro WordPress, rendendole disponibili al frontend e all'editor.

Meglio un tema classico o un block theme?

Per un nuovo progetto orientato a Gutenberg e Site Editor, un block theme è spesso la scelta più coerente. Un tema classico resta valido quando il progetto ha vincoli legacy, template PHP complessi o dipendenze già consolidate.

Gli agenti AI possono implementare direttamente il tema?

Sì, ma solo se ricevono specifiche, confini e criteri di verifica. Il punto del documento allegato è proprio questo: l'AI produce risultati migliori quando il lavoro di progettazione è esplicito, scritto e verificabile.

Conclusione

Creare un tema WordPress completo con AI non significa delegare il pensiero al modello. Significa spostare il valore sulla progettazione: descrivere bene il sistema, definire vincoli, produrre un design system e far implementare porzioni controllate. Google Stitch aiuta a esplorare l'interfaccia, DESIGN.md conserva la coerenza visiva, theme.json porta quella coerenza dentro WordPress.

La domanda utile, prima di generare codice, è questa: se un altro sviluppatore o un agente AI dovesse costruire il tema senza parlarti, avrebbe abbastanza informazioni per farlo correttamente? Se la risposta è no, non manca un prompt migliore. Manca una specifica migliore.

Una strategia efficace parte sempre da obiettivi chiari: aumentare traffico qualificato, generare lead, vendere prodotti, migliorare la fidelizzazione o ridurre il costo di acquisizione. L'AI diventa utile quando aiuta a trasformare questi obiettivi in azioni misurabili, non quando viene usata come scorciatoia per pubblicare contenuti generici. Chi lavora già con articoli WordPress ottimizzati SEO con AI può usare lo stesso metodo anche per campagne, funnel e automazioni.

Perché usare l'AI nel web marketing

L'AI applicata al web marketing lavora su tre aree principali: analisi, produzione e ottimizzazione. Nella fase di analisi aiuta a leggere dati provenienti da analytics, CRM, campagne pubblicitarie, email marketing e comportamento degli utenti. Nella produzione velocizza contenuti, headline, newsletter, script video, landing page e varianti di annunci. Nell'ottimizzazione aiuta a capire cosa migliorare: keyword, CTA, segmenti di pubblico, messaggi, offerte e funnel. In ottica SEO, questo deve restare coerente con le linee guida di Google sui contenuti utili e pensati per le persone.

• Analisi dei dati: individua pattern, anomalie, pagine deboli e opportunità di crescita.
• Creazione contenuti: supporta outline, articoli, email, post social, script e FAQ.
• Automazione marketing: rende più coerenti follow-up, nurturing, segmentazione e recupero utenti.
• Ottimizzazione conversioni: aiuta a testare CTA, microcopy, offerte e sequenze di funnel.

Il metodo corretto: prima i dati, poi gli strumenti

Il primo errore è partire dallo strumento invece che dal problema. Prima di scegliere un'app AI, conviene raccogliere dati già disponibili: pagine più visitate, query SEO, campagne con miglior rendimento, email con più click, form più compilati e contenuti che generano contatti. Queste informazioni mostrano dove intervenire. Per misurare le azioni davvero importanti, Google Analytics 4 usa gli eventi chiave, quindi conversioni, invii form, click strategici e acquisti vanno configurati prima di valutare l'impatto dell'AI.

Da qui puoi usare l'AI per creare una diagnosi operativa. Per esempio, puoi esportare le pagine con molte visite ma poche conversioni e chiedere quali frizioni potrebbero bloccare l'utente. Oppure puoi analizzare le query di Search Console per capire quali contenuti aggiornare, quali keyword presidiare e quali intenzioni di ricerca coprire con nuove pagine.

Strategia SEO con AI: contenuti più utili e meglio organizzati

Nella SEO l'intelligenza artificiale è utile per ricerca keyword, cluster tematici, outline, meta title, meta description, FAQ e aggiornamento dei contenuti esistenti. Ma la qualità resta decisiva. Un articolo scritto solo per riempire keyword non crea fiducia e non porta risultati stabili. Per questo è utile collegare il lavoro editoriale anche a contenuti già pubblicati sul sito, come la guida su come usare l'AI per aumentare le conversioni su WordPress.

Il modo migliore per usare l'AI nella SEO è partire dall'intento di ricerca. Un utente informativo cerca spiegazioni chiare. Un utente comparativo vuole criteri, pro e contro, esempi e alternative. Un utente vicino alla conversione cerca prove, garanzie, prezzi, tempi e passaggi successivi.

1. Definisci la keyword principale e le keyword secondarie.
2. Identifica l'intento di ricerca reale.
3. Crea una struttura con H2 e H3 progressivi.
4. Inserisci esempi pratici, casi d'uso e link utili.
5. Ottimizza title, description, slug e link interni.
6. Rivedi sempre il testo prima della pubblicazione.

Automazioni marketing: cosa automatizzare davvero

Le automazioni funzionano quando sono collegate al comportamento dell'utente. Un contatto che scarica una guida introduttiva non dovrebbe ricevere lo stesso messaggio di chi visita più volte una pagina servizio. Un cliente che ha già acquistato ha esigenze diverse da un nuovo lead appena entrato nel funnel. In questo senso, l'automazione marketing va progettata come parte del customer journey, non come semplice invio programmato di email.

L'AI può aiutare a creare sequenze più pertinenti, ma ogni automazione deve avere uno scopo preciso. Non basta inviare più email: bisogna inviare il messaggio giusto, al segmento giusto, nel momento giusto. Anche piattaforme come Mailchimp descrivono la marketing automation come un sistema basato su trigger, segmenti e comportamenti, non come una sequenza uguale per tutti.

Advertising e social media: testare meglio, non solo di più

Per advertising e social media l'AI è molto utile nella generazione di varianti creative. Può proporre headline, angoli comunicativi, descrizioni, script brevi, post social e sequenze per campagne. Il rischio è però generare troppe varianti senza una logica. Le piattaforme pubblicitarie, come la documentazione di Google Ads sulle risorse degli annunci, confermano l'importanza di testare messaggi e asset coerenti con intento, landing page e obiettivo della campagna.

Ogni variante dovrebbe testare un'ipotesi precisa: risparmio di tempo, vantaggio economico, riduzione del rischio, prova sociale, semplicità, urgenza o autorevolezza. Solo così i test diventano leggibili e migliorano davvero le campagne.

• Per Meta Ads: usa l'AI per creare angoli creativi diversi e copy brevi.
• Per Google Ads: lavora su intento, promessa e coerenza con la landing page.
• Per LinkedIn: punta su autorevolezza, casi pratici e problemi B2B specifici.
• Per newsletter: segmenta in base a interessi, click e livello di consapevolezza.

Workflow pratico per impostare una strategia AI

Una strategia di web marketing con l'AI può essere costruita con un processo semplice e ripetibile. L'obiettivo è evitare attività scollegate e creare un sistema in cui contenuti, dati, automazioni e conversioni lavorano insieme.

1. Definisci l'obiettivo: traffico, lead, vendite, retention o riduzione dei costi.
2. Raccogli i dati: analytics, Search Console, CRM, email, ads e comportamento utenti.
3. Segmenta il pubblico: utenti freddi, tiepidi, caldi e clienti esistenti.
4. Mappa il funnel: contenuti informativi, pagine di confronto, landing e follow-up.
5. Usa l'AI per creare ipotesi: nuovi contenuti, CTA, email, ads e automazioni.
6. Pubblica e misura: controlla traffico, click, lead, vendite e conversion rate.
7. Ottimizza: aggiorna ciò che funziona e rimuovi ciò che non porta risultati.

Errori da evitare

L'AI può accelerare il marketing, ma può anche amplificare errori già presenti. Se il posizionamento è confuso, l'AI produrrà messaggi confusi. Se non ci sono dati affidabili, le analisi saranno deboli. Se non esiste una metrica, diventa impossibile capire cosa funziona.

• Pubblicare contenuti senza revisione: il testo deve essere controllato, arricchito e adattato al brand.
• Automatizzare senza segmentazione: messaggi uguali per tutti riducono pertinenza e fiducia.
• Misurare solo il traffico: contano anche lead, vendite, qualità dei contatti e conversioni.
• Usare troppi strumenti: uno stack semplice e ben integrato vale più di dieci tool scollegati.
• Confondere output e strategia: produrre di più non significa comunicare meglio.

FAQ su AI e web marketing

L'AI può migliorare davvero il web marketing?

Sì, se viene usata dentro un processo misurabile. Aiuta ad analizzare dati, creare contenuti, segmentare il pubblico, automatizzare campagne e migliorare conversioni. Non sostituisce però strategia, esperienza e revisione umana.

Da dove conviene iniziare?

Conviene iniziare dai dati già disponibili: analytics, Search Console, CRM, piattaforme email e campagne advertising. Dopo questa analisi, l'AI può aiutare a definire priorità, contenuti e automazioni.

L'AI è utile per la SEO?

Sì, soprattutto per ricerca keyword, outline, meta tag, FAQ, cluster tematici e aggiornamento dei contenuti. Il contenuto finale deve però essere utile, verificato e coerente con l'intento di ricerca.

Quali attività si possono automatizzare?

Si possono automatizzare email di benvenuto, follow-up, recupero carrelli, nurturing dei lead, report periodici e alcune attività di content repurposing. Ogni automazione deve avere una metrica chiara.

Conclusione

Impostare strategie di web marketing con l'AI significa costruire un sistema più ordinato, misurabile e adattabile. L'intelligenza artificiale aiuta a leggere i dati, produrre contenuti più mirati, automatizzare passaggi ripetitivi e testare ipotesi con maggiore velocità.

Il risultato migliore arriva quando l'AI non sostituisce la strategia, ma la rende più precisa. Obiettivi chiari, dati affidabili, contenuti utili, automazioni intelligenti e misurazione costante sono la base per crescere online senza trasformare il marketing in rumore.

È qui che entra in gioco DESIGN.md, il nuovo formato open source pubblicato da Google Labs Code per descrivere una visual identity in modo leggibile sia dagli esseri umani sia dagli agenti di coding. L’idea è semplice ma molto potente: creare un file testuale, versionabile e validabile che contenga design token, razionale visivo, regole sui componenti e indicazioni pratiche su cosa fare e cosa evitare.

In altre parole, DESIGN.md prova a diventare per il design quello che altri file di configurazione sono già diventati per sviluppo, linting, formattazione e automazione: una fonte di verità chiara, portabile e adatta ai workflow moderni con AI.

Cos’è DESIGN.md e perché è importante

DESIGN.md è un formato pensato per descrivere l’identità visiva di un prodotto agli agenti di codice. La definizione ufficiale del repository google-labs-code/design.md parla di una specifica per dare agli agenti una comprensione persistente e strutturata di un design system.

Il punto chiave è la parola persistente. Un agente AI può ricevere istruzioni nel prompt, ma quelle istruzioni spesso sono temporanee, incomplete o ambigue. Un file DESIGN.md, invece, può stare nel repository accanto al codice, essere revisionato in pull request, validato con una CLI e riutilizzato da strumenti diversi.

Il formato unisce due livelli:

• una parte machine-readable in YAML front matter, dove vengono definiti token come colori, tipografia, spacing, radius e componenti;
• una parte human-readable in Markdown, dove si spiega il perché delle scelte e come applicarle in situazioni reali.

Questa combinazione è interessante perché i soli token non bastano. Sapere che il colore primario è #1A1C1E dice poco sul tono dell’interfaccia. Sapere anche che quel colore rappresenta “deep ink”, autorevolezza e leggibilità editoriale aiuta l’agente a usarlo con più coerenza.

Il problema che DESIGN.md prova a risolvere

Molti team hanno già un design system, ma spesso è distribuito in troppi luoghi: Figma, Storybook, documentazione interna, file CSS, Tailwind config, component library, issue di progetto e memoria informale del team. Quando entra in scena un agente AI, questa frammentazione diventa un problema tecnico.

Un agente può generare una pagina funzionante, ma senza un contesto stabile rischia di:

• inventare colori non presenti nel brand;
• usare font o pesi tipografici incoerenti;
• creare bottoni con radius e padding casuali;
• mescolare stili editoriali, SaaS, dashboard e landing page;
• ignorare contrasto e accessibilità;
• produrre componenti apparentemente belli ma scollegati dal sistema reale.

DESIGN.md riduce questo rischio perché trasforma le linee guida di design in un contratto leggibile dal codice e dagli agenti. Non sostituisce Figma o una libreria componenti, ma aggiunge un livello di istruzioni condivise che può viaggiare con il repository.

Come è fatto un file DESIGN.md

La struttura ufficiale prevede un file Markdown con front matter YAML opzionale. Il front matter contiene i token normativi; il corpo Markdown contiene spiegazioni, razionale e linee guida.

Ecco un esempio semplificato:

---
version: alpha
name: Editorial Tech
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  headline-lg:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
  body-md:
    fontFamily: Public Sans
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.6
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
  lg: 32px
components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "#ffffff"
    rounded: "{rounded.sm}"
    padding: 12px
---

## Overview

Interfaccia editoriale, tecnica e autorevole. Il prodotto deve comunicare
precisione, leggibilità e affidabilità, evitando decorazioni inutili.

## Colors

Il colore primario è usato per testi e titoli. Il terziario è riservato
alle azioni principali e agli stati di enfasi.

Questo esempio mostra il principio operativo: i valori precisi sono nei token, mentre il Markdown spiega come interpretarli. Un agente può quindi rispettare sia la misura esatta sia l’intenzione progettuale.

I token supportati: colori, tipografia, spacing e componenti

La specifica ufficiale descrive un insieme di gruppi token pensati per coprire gli aspetti fondamentali di una UI.

I gruppi principali sono:

• colors, per palette e ruoli cromatici;
• typography, per font, dimensioni, pesi, line-height e letter-spacing;
• rounded, per la scala dei bordi arrotondati;
• spacing, per distanze, margini e ritmo visivo;
• components, per collegare i token a elementi come bottoni, chip, input e stati.

Un dettaglio tecnico importante è il supporto ai riferimenti tra token con sintassi {path.to.token}. Per esempio, un bottone può usare backgroundColor: "{colors.tertiary}", evitando duplicazione e riducendo il rischio di divergenze.

Questa scelta rende DESIGN.md più simile a un piccolo linguaggio di configurazione che a una semplice pagina di documentazione. È leggibile, ma anche analizzabile da un linter.

Le sezioni Markdown consigliate

Il corpo del file non è libero in modo caotico. La specifica suggerisce un ordine canonico delle sezioni, tutte basate su heading ##:

1. Overview;
2. Colors;
3. Typography;
4. Layout;
5. Elevation & Depth;
6. Shapes;
7. Components;
8. Do’s and Don’ts.

Questo ordine serve a dare prevedibilità agli strumenti. Un agente sa dove cercare la personalità visiva, dove trovare le regole tipografiche, dove leggere i vincoli di layout e dove individuare errori da evitare.

La scelta è pragmatica: DESIGN.md non vuole essere un trattato di brand identity, ma un formato operativo. Deve essere abbastanza espressivo per guidare un’interfaccia reale, ma abbastanza strutturato per essere letto e validato da una CLI.

Esempio pratico: usare DESIGN.md in un progetto frontend

Immagina un team che sta costruendo una dashboard SaaS. Nel repository sono presenti componenti React, Tailwind, test e documentazione. Senza DESIGN.md, un agente AI chiamato a creare una nuova pagina “Billing” potrebbe copiare pattern visti in altre parti del codice, ma potrebbe anche introdurre nuove sfumature, radius non standard o gerarchie tipografiche incoerenti.

Con DESIGN.md, il workflow diventa più controllabile:

1. il team definisce colori, tipografia, spacing e componenti principali;
2. il file viene salvato nel repository;
3. l’agente legge DESIGN.md prima di generare UI;
4. la CLI valida token, riferimenti e contrasto;
5. eventuali modifiche al design system vengono confrontate con diff.

Il risultato non è una garanzia assoluta di qualità, ma riduce drasticamente l’improvvisazione. In un contesto con più agenti o più sviluppatori, questo è un vantaggio concreto.

Comandi CLI: lint, diff, export e spec

Google distribuisce anche una CLI installabile come pacchetto npm @google/design.md. Dal README ufficiale emerge un set di comandi pensato per validare, confrontare ed esportare il formato.

Il comando più immediato è il lint:

# comando lint
npx @google/design.md lint DESIGN.md

Il linter restituisce JSON strutturato con finding, severità, percorso e messaggio. Questo è utile perché un agente può leggere l’output e correggere il file in modo mirato.

Per confrontare due versioni:

# confronto due versioni
npx @google/design.md diff DESIGN.md DESIGN-v2.md

Questo aiuta a capire se sono stati aggiunti, rimossi o modificati token. In una pull request, può diventare un controllo utile per evitare regressioni nel design system.

Per esportare i token:

npx @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json
npx @google/design.md export --format css-tailwind DESIGN.md > theme.css
npx @google/design.md export --format dtcg DESIGN.md > tokens.json

Gli export sono importanti perché collegano DESIGN.md agli strumenti già usati dai team: Tailwind, CSS custom properties e formati compatibili con il mondo dei design token.

Un riferimento pratico da aggiungere al workflow è Stitch di Google, che consente di lavorare su interfacce e prototipi con un percorso orientato anche all’esportazione nel formato DESIGN.md. Questo rende il file ancora più interessante: non è solo una specifica da scrivere manualmente, ma può diventare un formato di passaggio tra progettazione visuale, generazione assistita e codice.

Le regole di linting più utili

La documentazione cita diverse regole di linting, tra cui riferimenti rotti, contrasto, assenza di colore primario, token orfani, sezioni mancanti, tipografia mancante e ordine delle sezioni.

Queste verifiche rendono DESIGN.md più serio di una semplice convenzione testuale. Un file può essere scritto male, ma la CLI permette di intercettare almeno una parte degli errori prima che arrivino nel codice generato.

Perché DESIGN.md interessa a chi lavora con AI coding agent

Il valore più evidente è per chi usa agenti AI nel frontend. Strumenti di coding assistito possono già generare componenti, landing page e layout, ma spesso hanno bisogno di contesto. DESIGN.md offre quel contesto in una forma leggera.

Un agente può leggere frasi come:

• “usa il colore primario solo per l’azione più importante”;
• “evita ombre pesanti, usa gerarchie tonali”;
• “mantieni radius da 4px per un aspetto tecnico”;
• “non usare più di due pesi tipografici nella stessa schermata”.

Queste indicazioni sono diverse dai token numerici. Sono regole di comportamento progettuale. Per un essere umano sono normali linee guida; per un agente diventano vincoli espliciti da seguire.

Differenze rispetto a tokens.json, Figma variables e Tailwind config

DESIGN.md non nasce per sostituire tutto. Un file tokens.json resta più adatto allo scambio formale di token tra strumenti. Figma variables restano fondamentali nel lavoro dei designer. Tailwind config resta centrale quando si implementa una UI con utility class.

La differenza è che DESIGN.md mette nello stesso posto token e razionale. Questo lo rende particolarmente adatto agli agenti, perché gli agenti non hanno bisogno solo di valori: hanno bisogno di contesto.

Per esempio, un token può dire che tertiary vale #B8422E; il testo può spiegare che quel colore è “Boston Clay” e che deve essere usato solo per interazioni primarie. Questa seconda informazione può fare la differenza tra una UI coerente e una UI tecnicamente corretta ma visivamente confusa.

Limiti attuali del formato

DESIGN.md è indicato come formato in stato alpha. Questo significa che lo schema, la CLI e le convenzioni potrebbero cambiare. È quindi intelligente adottarlo con aspettative realistiche.

I limiti più evidenti sono:

• la specifica è ancora giovane;
• la sezione componenti è flessibile e in evoluzione;
• non sostituisce test visivi, review di design o accessibilità manuale;
• richiede disciplina nella manutenzione;
• può diventare obsoleto se non viene aggiornato insieme al prodotto.

Detto questo, il formato è già utile per sperimentare un workflow più ordinato tra design system e AI coding.

Come introdurre DESIGN.md in un team

Il modo migliore non è provare a documentare tutto subito. Conviene partire da un file piccolo ma accurato.

Un percorso pratico può essere:

1. definire nome, descrizione e personalità del prodotto;
2. inserire palette primaria, secondaria, accento e neutral;
3. aggiungere 4-6 livelli tipografici realmente usati;
4. documentare spacing e radius principali;
5. descrivere 3 componenti critici: bottone primario, card e input;
6. scrivere 5 regole “do” e 5 regole “don’t”;
7. eseguire il lint e correggere gli errori;
8. usare il file in una singola feature generata con agenti AI;
9. confrontare output generato prima e dopo DESIGN.md.

Questo approccio evita il classico errore dei design system: puntare alla perfezione iniziale e non arrivare mai all’adozione reale.

SEO tecnico e opportunità per sviluppatori WordPress

Anche se DESIGN.md nasce per agenti di codice e design system, il tema è rilevante anche per chi lavora con WordPress, temi custom e page builder avanzati. Un file di questo tipo potrebbe aiutare a mantenere coerenza visiva quando si generano componenti, blocchi Gutenberg, pattern di tema o layout con strumenti AI.

Per esempio, un team WordPress potrebbe creare un DESIGN.md per descrivere:

• palette del brand;
• gerarchia tipografica del tema;
• spaziature dei blocchi editoriali;
• stile di card, bottoni e call to action;
• regole per landing page e template WooCommerce;
• vincoli di accessibilità e contrasto.

In futuro, agenti AI capaci di leggere DESIGN.md potrebbero generare pattern Gutenberg più coerenti, componenti React per block editor o CSS custom properties allineate alla brand identity. È un ponte naturale tra content management, frontend engineering e automazione.

Per approfondire il tema nel contesto WordPress, sono collegati due percorsi utili: una guida su AI per migliorare SEO, UX e design su WordPress e un approfondimento sui tool essenziali per il web design WordPress. Entrambi aiutano a collegare DESIGN.md a casi d’uso concreti: coerenza visiva, automazione dei layout, qualità UX e produzione di interfacce più controllabili.

FAQ

DESIGN.md è un file di configurazione ufficiale di Google?

È un progetto open source pubblicato nel repository Google Labs Code. La specifica è in fase alpha e propone un formato per descrivere visual identity e design system agli agenti di coding.

DESIGN.md sostituisce Figma?

No. Figma resta uno strumento visuale per progettare, discutere e prototipare. DESIGN.md aggiunge un formato testuale, versionabile e leggibile dagli agenti, utile dentro i repository di codice.

Qual è la differenza tra DESIGN.md e design tokens?

I design token definiscono valori come colori, font, spacing e radius. DESIGN.md può contenere quei token, ma aggiunge anche spiegazioni in Markdown, cioè il razionale che aiuta gli agenti a capire come applicarli.

Si può usare DESIGN.md con Tailwind?

Sì. La CLI documenta export verso Tailwind v3 in JSON e Tailwind v4 tramite CSS @theme, oltre al formato DTCG per design token.

È pronto per la produzione?

È utilizzabile per sperimentazioni e workflow interni, ma va considerato un formato alpha. Prima di inserirlo in processi critici, conviene testarlo su un progetto pilota e monitorare l’evoluzione della specifica.

Conclusione

DESIGN.md è interessante perché affronta un problema reale: gli agenti AI possono scrivere codice, ma senza una memoria progettuale rischiano di generare interfacce incoerenti. Un file testuale, versionabile e validabile può diventare il ponte tra design system, frontend e automazione.

Il valore non sta solo nei token, ma nel contesto: colori con significato, tipografia con ruolo, componenti con stati, regole pratiche e divieti espliciti. Per chi lavora con AI coding agent, design system o sviluppo WordPress avanzato, DESIGN.md è un formato da osservare subito e da testare in un piccolo progetto reale.

Il consiglio pratico è semplice: crea un primo DESIGN.md con pochi token affidabili, aggiungi rationale chiaro, esegui il lint e usalo come contesto per un agente AI. La differenza nella coerenza dell’output diventa evidente appena il progetto supera la singola pagina dimostrativa.

Questa è la domanda che ogni freelancer si sente fare al primo incontro con un potenziale cliente. E se sei all'inizio, la risposta è quasi sempre la stessa: "No, non ancora."

Il silenzio che segue è imbarazzante. E il cliente, educatamente, passa al prossimo fornitore.

Ma c'è un modo per aggirare questo problema. Un metodo che ti permette di costruire un portfolio convincente in poche settimane, anche se non hai mai avuto un cliente pagante.

Si chiama Portfolio AI, e sta cambiando le regole del gioco per i freelancer.

Il Paradosso del Freelancer alle Prime Armi

Ecco il circolo vizioso in cui si trovano la maggior parte dei freelancer:

• Per ottenere clienti ti serve un portfolio
• Per avere un portfolio ti servono clienti
• Senza clienti non hai portfolio, e senza portfolio non hai clienti

L'AI rompe questo circolo.

Con gli strumenti AI di oggi, puoi creare progetti demo realistici che dimostrano le tue competenze in modo tangibile. Non si tratta di "fingere" — si tratta di costruire prove concrete di ciò che sai fare.

La Strategia dei 3 Progetti Demo

Il metodo è semplice: crea 3 progetti demo che simulano lavori reali per clienti ipotetici. Ogni progetto deve:

• ✅ Risolvere un problema reale di un settore specifico
• ✅ Mostrare un processo documentato (prima/dopo)
• ✅ Includere risultati misurabili (anche se stimati)
• ✅ Essere presentato come un case study professionale

Progetto 1: Il Cliente "Locale"

Scenario: Un ristorante della tua città vuole aumentare le prenotazioni online.

Cosa creare:

• Un sito web one-page con sistema di prenotazione
• Integrazione con Google Maps e recensioni
• Chatbot AI per rispondere alle domande frequenti
• Setup di Google My Business ottimizzato

Risultati da mostrare:

• 📊 "+40% di prenotazioni online nel primo mese" (basato su benchmark di settore)
• 📊 "-60% di telefonate per informazioni ripetitive" (grazie al chatbot)
• 📊 "Posizionamento #1 su Google per 'ristorante [città]'"

Strumenti AI usati: ChatGPT per copy e struttura, Midjourney per immagini, Cursor/OpenCode per sviluppo, Claude per ottimizzazione SEO.

Progetto 2: L'E-commerce di Nicchia

Scenario: Un artigiano vuole vendere i suoi prodotti online ma non sa da dove iniziare.

Cosa creare:

• Store WooCommerce con 20 prodotti
• Descrizioni prodotto generate e ottimizzate con AI
• Setup di email marketing automatizzato (welcome sequence, abandoned cart)
• Dashboard analytics con KPI personalizzati

Risultati da mostrare:

• 📊 "Tasso di conversione del 3.2% (media settore: 1.8%)"
• 📊 "Email di recupero carrello con tasso di apertura del 45%"
• 📊 "Tempo di lancio: 5 giorni invece di 3 settimane"

Progetto 3: L'Automazione Aziendale

Scenario: Un'agenzia di marketing spende 20 ore/settimana in task ripetitivi.

Cosa creare:

• Workflow automatizzato per generazione report settimanali
• Bot AI per analisi sentiment dei social media
• Sistema di generazione contenuti con approvazione automatica
• Dashboard di monitoraggio con alert intelligenti

Risultati da mostrare:

• 📊 "-15 ore/settimana di lavoro manuale"
• 📊 "ROI del 340% nel primo trimestre"
• 📊 "Tempo di risposta ai clienti ridotto da 4 ore a 15 minuti"

Come Documentare Ogni Progetto: Il Template Case Study

Ogni progetto del tuo portfolio deve seguire questa struttura professionale:

"Fake It Till You Make It" in Modo Etico

C'è una differenza fondamentale tra mentire e proiettare competenza:

• ❌ Non etico: Dire "ho lavorato per Nike" quando non è vero
• ✅ Etico: Creare un redesign concettuale di Nike e mostrarlo come "progetto speculativo"

Come essere trasparenti:

• Etichetta i progetti demo come "Progetto Concettuale" o "Case Study Simulato"
• Specifica che si tratta di progetti dimostrativi delle tue competenze
• Mostra il processo completo — questo è ciò che conta davvero per i clienti
• Includi codice sorgente, wireframe, brief — tutto ciò che dimostra il tuo metodo di lavoro

La verità è che molti clienti non distinguono tra un progetto reale e uno simulato — ciò che valutano è la qualità del risultato e la chiarezza del processo.

Dove Ospitare il Tuo Portfolio AI

• Sito personale WordPress — Il più professionale, controllo totale
• GitHub Pages — Gratuito, perfetto per sviluppatori
• Notion — Veloce da creare, facile da aggiornare
• Behance/Dribbble — Ottimo per designer
• LinkedIn Featured Section — Visibilità immediata

Il mio consiglio: usa un sito WordPress personale come hub centrale e linka gli altri profili da lì.

3 Errori da Evitare nel Portfolio AI

1. Troppi progetti mediocri — Meglio 3 progetti eccellenti che 10 mediocri
2. Solo screenshot, nessun contesto — I numeri e il processo contano più delle immagini
3. Nessuna call-to-action — Ogni pagina del portfolio deve invitare al contatto

Il Tuo Piano d'Azione in 7 Giorni

1. Giorno 1: Scegli 3 settori/nicchie su cui concentrarti
2. Giorno 2: Crea brief dettagliati per ogni progetto demo
3. Giorno 3-4: Sviluppa il Progetto 1 (Cliente Locale)
4. Giorno 5: Sviluppa il Progetto 2 (E-commerce)
5. Giorno 6: Sviluppa il Progetto 3 (Automazione)
6. Giorno 7: Pubblica il portfolio e condividilo su LinkedIn

In una settimana avrai un portfolio che il 90% dei freelancer alle prime armi invidia.

Conclusione: Il Portfolio è il Tuo Biglietto da Visita

Non aspettare il primo cliente per costruire il tuo portfolio. Crea il portfolio per ottenere il primo cliente.

Con l'AI, non hai più scuse. Hai gli strumenti, hai il metodo, hai il template. Ora ti manca solo l'azione.

Inizia oggi. Il tuo futuro cliente ti sta già cercando.

Questa guida ti mostrerà esattamente come riposizionare le competenze che già possiedi usando l'intelligenza artificiale come acceleratore, trasformandoti da esecutore generico a consulente AI strategico — e raddoppiare (o triplicare) le tue tariffe nel processo.

Perché Diventare Consulente AI Ora (Prima che Sia Troppo Tardi)

Il mercato del lavoro freelance sta subendo una trasformazione epocale. Secondo recenti studi, il 73% delle aziende prevede di integrare strumenti AI nei propri workflow entro il 2026. Ma ecco il paradosso:

• La domanda di consulenti AI è esplosa (+340% su LinkedIn negli ultimi 12 mesi)
• L'offerta di professionisti qualificati è ancora bassissima
• Le tariffe medie per consulenti AI sono 2-3x superiori rispetto ai freelance tradizionali

La finestra di opportunità è aperta ora. Tra 12-18 mesi, il mercato si saturerà. Chi si muove oggi avrà un vantaggio competitivo enorme.

Il Tuo Vantaggio Nascosto: Competenze che Già Possiedi

Ecco la buona notizia: non devi imparare a programmare per diventare un consulente AI. Le competenze che già usi ogni giorno sono esattamente ciò che le aziende cercano.

L'AI non ti sostituisce — ti moltiplica. Un copywriter che usa AI può produrre 10x contenuti nella stessa ora. Un designer può esplorare 50 concept invece di 5. La differenza? Tu vendi il risultato, non le ore lavorate.

La Roadmap in 5 Fasi per Diventare Consulente AI

Fase 1: Audit delle Tue Competenze (Giorni 1-3)

Prima di aggiungere AI al tuo arsenale, devi capire cosa sai già fare bene. Fai questo esercizio:

1. Elenco dei 5 servizi principali che offri attualmente
2. Per ciascuno, identifica il collo di bottiglia (cosa ti porta più tempo?)
3. Per ogni collo di bottiglia, cerca tool AI specifici che possono automatizzarlo
4. Calcola il risparmio potenziale in ore/settimana

Esempio pratico: Se sei un copywriter e spendi 4 ore per ricerca keyword + outline, un tool AI può farlo in 15 minuti. Risparmio: 3h45m per progetto. Su 10 progetti/mese = 37,5 ore risparmiate.

Fase 2: Costruisci il Tuo Stack AI (Giorni 4-10)

Non servono 20 tool. Te ne bastano 3-5 ben integrati. Ecco lo stack minimo vitale per iniziare:

• ChatGPT Plus / Claude Pro — Il tuo assistente quotidiano (€20-20/mese)
• Tool specifico per la tua nicchia — Es: Jasper per copy, Midjourney per design, GitHub Copilot per dev (€10-30/mese)
• Tool di automazione — Zapier o Make per collegare tutto (€0-30/mese)
• Tool di analisi — Per misurare risultati e ROI (spesso gratuito)

Investimento totale: €30-100/mese. Se fatturi anche solo €500 in più grazie all'AI, il ROI è del 400-1500%. Non male, vero?

Fase 3: Crea 3 Casi Studio Demo (Giorni 11-20)

I clienti vogliono vedere risultati concreti, non promesse. Crea 3 progetti demo che dimostrino il tuo nuovo approccio AI:

1. Progetto "Before" — Come facevi prima (senza AI)
2. Progetto "After" — Come fai ora (con AI)
3. Confronto misurabile — Tempo risparmiato, qualità migliorata, ROI generato

Template caso studio:

Cliente: [Nome/Nicchia]
Sfida: [Problema specifico]
Soluzione AI: [Tool + processo]
Risultato: [Metriche concrete: tempo risparmiato, revenue generata, costi ridotti]
ROI: [X% in Y settimane]

Fase 4: Riposiziona la Tua Offerta (Giorni 21-30)

È ora di cambiare come ti presenti al mercato. Non sei più un "freelance che fa X". Sei un "Consulente AI specializzato in X".

Aggiornamenti obbligatori:

• LinkedIn headline: Da "Copywriter Freelance" a "AI Content Strategist | Aiuto le aziende a produrre 10x contenuti con l'AI"
• Sito web: Aggiungi pagina "Servizi AI" con casi studio
• Portfolio: Includi i 3 casi studio demo
• Proposte commerciali: Riscrivi tutto enfatizzando velocità, qualità e ROI

La regola d'oro: Non vendere "uso ChatGPT". Vendi "risultati 10x più veloci al stesso prezzo" o "risultati superiori al prezzo attuale".

Fase 5: Trova i Primi Clienti AI (Giorni 31-45)

Ora che hai competenze, stack, casi studio e positioning, è ora di trovare clienti disposti a pagare di più.

Strategie più efficaci:

1. Upsell clienti esistenti: "Ho un nuovo servizio AI che può [beneficio specifico]. Ti interessa una demo gratuita?"
2. LinkedIn outbound: Contatta 10 decision-maker/giorno con messaggio personalizzato + caso studio
3. Content marketing: Pubblica 2 post/settimana su LinkedIn mostrando risultati AI
4. Webinar gratuito: "Come [tua nicchia] può usare l'AI per [risultato]" → raccogli email → converti in clienti
5. Partnership: Collabora con agenzie che non hanno competenze AI interne

Quanto Puoi Guadagnare Come Consulente AI?

Ecco i numeri reali, basati su dati di mercato 2026:

Confronto con freelance tradizionale: Un copywriter medio fattura €1.500-3.000/mese. Un AI Content Strategist fattura €4.000-10.000/mese. La differenza? Non è il talento. È il posizionamento.

Gli Errori da Evitare (Che Costano Caro)

1. Vendere "AI" invece di risultati: Ai clienti non importa di ChatGPT. Importa di risparmiare tempo e guadagnare di più.
2. Usare AI senza supervisione umana: L'AI è un acceleratore, non un sostituto. La tua expertise è ciò che fa la differenza.
3. Abbassare i prezzi perché "l'AI è gratis": L'AI ti costa tempo di setup, testing e ottimizzazione. Il valore è nel risultato, non nel tool.
4. Ignorare l'etica e la privacy: Usa AI in modo responsabile. Informa i clienti su come usi i loro dati.
5. Non misurare i risultati: Senza metriche, non puoi dimostrare il tuo valore. Traccia sempre tempo risparmiato, qualità migliorata e ROI generato.

Checklist: Sei Pronto per Diventare Consulente AI?

• ✅ Hai identificato 3+ competenze che l'AI può potenziare
• ✅ Hai configurato il tuo stack AI (3-5 tool)
• ✅ Hai creato 3 casi studio demo con risultati misurabili
• ✅ Hai aggiornato LinkedIn, sito web e portfolio
• ✅ Hai riscritto le tue proposte commerciali con focus AI
• ✅ Hai un piano per trovare i primi 5 clienti AI

Se hai spuntato almeno 4 caselle, sei pronto. Inizia oggi. Il mercato non aspetta.

Prossimi Passi: Inizia Ora

Non serve aspettare il momento perfetto. Il momento perfetto è ora.

1. Oggi: Fai l'audit delle tue competenze (Fase 1)
2. Questa settimana: Configura il tuo stack AI (Fase 2)
3. Prossime 2 settimane: Crea i 3 casi studio demo (Fase 3)
4. Entro 30 giorni: Riposiziona la tua offerta (Fase 4)
5. Entro 45 giorni: Trova i primi clienti AI (Fase 5)

Tra 45 giorni, potresti essere un consulente AI con clienti che pagano 2-3x le tue tariffe attuali. Oppure potresti essere ancora qui a leggere articoli su come fare. La scelta è tua.

Hai domande sul percorso da freelance a consulente AI? Lascia un commento qui sotto o contattaci per una consulenza personalizzata.

Ma quale scegliere per il tuo workflow? In questo confronto definitivo analizziamo costi, funzionalità, integrazioni e casi d'uso ideali per ogni strumento.

Tabella Comparativa Rapida

OpenCode: L'AI Autonoma che Lavora in Background

Cos'è e Come Funziona

OpenCode rappresenta un cambio di paradigma nel mondo degli AI coding assistant. A differenza di Copilot che reagisce ai tuoi input, OpenCode è proattivo: un server in background che si sveglia autonomamente ogni 30 minuti per analizzare la tua codebase.

Architettura Innovativa

• Background Server (sveglia ogni 30 min)
• Plan Mode (read-only): Esplora codebase
• Build Mode (read/write): Implementa modifiche
• LSP Integration: Refactoring semantico

Funzionalità Chiave

Plan Mode: Modalità read-only che esplora la codebase, mappa la struttura e produce una strategia di implementazione senza modificare nulla.

Build Mode: Accesso in lettura/scrittura per eseguire il piano, modificare file, eseguire test.

Multi-Provider: Switch dinamico tra OpenAI, Anthropic, Google e modelli locali (Ollama) nella stessa sessione.

LSP Integration: Con OPENCODE_EXPERIMENTAL_LSP_TOOL=true, abilita refactoring semantico con goToDefinition, findReferences e call hierarchy.

Pro e Contro

Vantaggi:

• Completamente autonomo
• Multi-provider
• Privacy totale (self-hosted)
• Gratuito
• LSP per refactoring avanzato

Svantaggi:

• Setup iniziale complesso
• Richiede risorse locali
• Meno indicazioni in tempo reale
• Documentazione ancora limitata
• Beta, potenziali bug

Caso d'Uso Ideale

OpenCode è perfetto per progetti a lungo termine dove vuoi un assistente che pensa mentre tu fai altro. Ideale per refactoring di grandi codebase, audit di sicurezza e ottimizzazione architetturale.

Claude Code: La Potenza di Claude 3.5 nel Terminale

Cos'è e Come Funziona

Claude Code è il tool CLI di Anthropic che porta la potenza di Claude 3.5 Sonnet direttamente nel tuo terminale. A differenza di Copilot che suggerisce snippet mentre scrivi, Claude Code comprende il contesto dell'intero progetto, può eseguire comandi shell, leggere e modificare file, e persino fare debugging.

Installazione e Setup

# Installazione via npm
npm install -g @anthropic-ai/claude-code

# Configurazione API key
export ANTHROPIC_API_KEY="your-api-key"

# Avvio in un progetto
cd your-project
claude

Comandi Essenziali

# Analizza il progetto
claude "Analizza la struttura di questo progetto WordPress"

# Genera codice
claude "Crea un plugin WooCommerce per gestire abbonamenti"

# Debugging
claude "Trova il bug in functions.php riga 145"

# Refactoring
claude "Ottimizza le query del database in questo plugin"

Pro e Contro

Vantaggi:

• Claude 3.5 Sonnet (top quality)
• Context window 200K token
• CLI agnostica (qualsiasi editor)
• Comprensione profonda del progetto
• Esegue comandi shell

Svantaggi:

• Costo pay-per-use API
• Rate limits su API
• Necessita terminale
• Meno indicazioni inline
• Setup API key richiesto

Caso d'Uso Ideale

Claude Code eccelle per sviluppo complesso dove serve comprensione profonda del contesto. Perfetto per WordPress development, debugging intricato e generazione di codice complesso con logica business.

GitHub Copilot: Il Pair Programmer Classico

Cos'è e Come Funziona

GitHub Copilot è il pioniere degli AI coding assistant. Lanciato nel 2021, rimane lo strumento più diffuso grazie alla sua integrazione nativa con VS Code e la familiarità degli sviluppatori. Funziona come un pair programmer in tempo reale, suggerendo codice mentre scrivi.

Funzionalità Chiave

Inline Suggestions: Suggerimenti mentre scrivi, accettabili con Tab.

Copilot Chat: Chat integrata per domande sul codice.

Copilot Workspace: Generazione di progetti completi da descrizione.

Multi-IDE: VS Code, JetBrains, Neovim, Visual Studio.

Pro e Contro

Vantaggi:

• Integrazione perfetta VS Code
• Suggerimenti in tempo reale
• Facile da usare
• Copilot Chat per domande
• Aggiornamenti frequenti

Svantaggi:

• Abbonamento richiesto
• Privacy: codice inviato a GitHub
• Context window limitata
• Meno autonomia
• Meno comprensione del progetto globale

Caso d'Uso Ideale

Copilot è ideale per coding quotidiano dove vuoi suggerimenti istantanei mentre scrivi. Perfetto per boilerplate, snippet comuni e pair programming in tempo reale.

Confronto per Casi d'Uso Specifici

Per Sviluppatori WordPress

Per Progetti Enterprise

Per Startup e Indie Hackers

Per Progetti Open Source

Analisi Costi-Benefici

OpenCode

• Costo: Gratuito (self-hosted)
• Requisiti: Server locale con risorse per LLM
• ROI: Altissimo per progetti a lungo termine
• Hidden costs: Hardware per modelli locali

Claude Code

• Costo: Pay-per-use API (~$3-15/mese per uso moderato)
• Modello: Claude Sonnet ($3/1M input, $15/1M output)
• ROI: Alto per progetti complessi
• Hidden costs: Rate limits possono rallentare

GitHub Copilot

• Costo: $10/mese (Individual), $19/mese (Business), $39/mese (Enterprise)
• ROI: Alto per coding quotidiano
• Hidden costs: Privacy del codice

Privacy e Sicurezza

OpenCode

Massima privacy: Tutto gira localmente, nessun dato inviato esternamente.

Self-hosted: Controllo completo su dove e come gira.

Multi-provider: Puoi usare modelli locali (Ollama) per privacy totale.

Claude Code

Privacy locale: Il codice viene processato localmente, solo le query API vanno ad Anthropic.

API calls: Le richieste viaggiano su server Anthropic.

No training on code: Anthropic non usa il tuo codice per training.

GitHub Copilot

Codice inviato a GitHub: Per funzionare, il codice viene inviato ai server Microsoft.

Training on public code: Addestrato su codice pubblico, potenziali problemi di licenza.

Enterprise: Versione Business/Enterprise offre più privacy.

Workflow Consigliati

Workflow Ibrido: OpenCode + Copilot

1. Mattina: OpenCode analizza il progetto in background
2. Sviluppo: Copilot suggerisce snippet in tempo reale
3. Sera: OpenCode propone refactoring e ottimizzazioni

Workflow Claude Code + VS Code

1. Terminale: Claude Code per architettura e logica complessa
2. Editor: VS Code per editing e debugging
3. Iterazione: Claude Code per refactoring e ottimizzazione

Workflow Solo OpenCode

1. Setup: Configura OpenCode con multi-provider
2. Plan Mode: Lascia analizzare il progetto
3. Review: Esamina le proposte
4. Build Mode: Approva le modifiche

Verdetto Finale

Il Vincitore Dipende dal Tuo Stile

La Nostra Raccomandazione

Per sviluppatori WordPress che lavorano su progetti complessi: Claude Code per la comprensione profonda di hooks, filters e conventions WP.

Per team enterprise con requisiti di privacy: OpenCode per il controllo totale e l'assenza di dati inviati esternamente.

Per indie hackers e startup: GitHub Copilot per la produttività immediata e il costo prevedibile.

Il Futuro degli AI Coding Assistant

Il 2026 sta vedendo una convergenza: OpenCode sta aggiungendo feature inline, Claude Code sta migliorando l'autonomia, e Copilot sta integrando agenti più intelligenti.

La vera rivoluzione arriverà quando questi strumenti combineranno:

• Autonomia di OpenCode
• Qualità di Claude Code
• Integrazione di Copilot

Fino ad allora, la scelta dipende dal tuo workflow e dalle tue priorità.

Domande Frequenti

Posso usare più di uno strumento insieme?

Assolutamente sì! Molti sviluppatori usano Copilot per suggerimenti inline e Claude Code per architettura. OpenCode può girare in background mentre usi entrambi.

Quale ha il modello AI più potente?

Claude Code usa Claude Sonnet, attualmente considerato il top per coding. OpenCode può usare qualsiasi modello, inclusi Claude e GPT-5o.

OpenCode è davvero gratuito?

Sì, ma richiede hardware per girare localmente o API key per i provider cloud. Il software è open source e gratuito.

GitHub Copilot vale i $10/mese?

Per la maggior parte degli sviluppatori, sì. La produttività guadagnata supera ampiamente il costo. Per progetti occasionali, Claude Code pay-per-use potrebbe essere più economico.

Quale è meglio per principianti?

GitHub Copilot per la facilità d'uso e i suggerimenti in tempo reale. Claude Code richiede più conoscenza del terminale.

Aggiornato ad Aprile 2026. I prezzi e le funzionalità potrebbero cambiare con gli aggiornamenti dei prodotti.

Hai mai trovato il tema WordPress perfetto per il tuo sito, ma con quei piccoli dettagli che proprio non ti convincono? Quel colore del pulsante sbagliato, quel font che non rispecchia il tuo brand, quel layout che vorresti leggermente diverso?

Fino a pochi anni fa, modificare un tema WordPress significava scegliere tra due opzioni poco attraenti:

1. Modificare il tema direttamente → Aggiornamenti = perdita di tutte le modifiche
2. Assumere uno sviluppatore → Costi elevati (€500-2000) e tempi lunghi

Oggi, grazie all'intelligenza artificiale e ai child theme, puoi personalizzare qualsiasi tema WordPress in modo sicuro, reversibile e professionale. E la parte migliore? Non serve essere un esperto di coding.

Cosa Troverai in Questa Guida

Questa guida pratica di oltre 2000 parole ti accompagnerà dalla creazione del tuo primo child theme fino alla personalizzazione avanzata. Ogni capitolo include:

• Spiegazioni chiare con esempi visivi
• Prompt AI pronti da copiare e incollare
• Codice CSS e PHP completo e commentato
• Checklist operative
• Tabelle comparative
• Best practice e avvertenze

Cosa Imparerai

1. Fondamenti - Cos'è child theme, architettura, vantaggi
2. Setup - Creazione, installazione, attivazione
3. Colori - Palette personalizzata con AI
4. Font - Google Fonts e tipografia responsive
5. Layout - Template override e customizzazioni
6. Funzionalità - functions.php avanzato
7. Performance - Ottimizzazione velocità
8. Testing - Checklist pre-lancio

Perché Usare un Child Theme

Statistiche Chiave

• 📊 94% dei temi WordPress riceve aggiornamenti mensili
• ⚠️ 67% utenti perde customizzazioni dopo aggiornamenti (senza child theme)
• 💰 €500-2000 costo medio customizzazione da developer
• ⏱️ 30 minuti tempo medio per child theme con AI

Capitolo 1: Fondamenti Child Theme

Cos'è un Child Theme

Un child theme è un tema WordPress che eredita tutte le funzionalità e lo stile di un tema parent, permettendoti di modificare o aggiungere funzionalità senza alterare il tema originale.

Analogia semplice: Il tema parent è una casa già costruita. Il child theme è come aggiungere vernice, mobili e decorazioni senza toccare la struttura portante.

Come Funziona l'Ereditarietà

WordPress carica i file in questo ordine:

1. Cerca il file nel child theme
2. Se non esiste, usa il file del parent theme
3. Il child theme può override qualsiasi file del parent

Esempio:

Se modifichi header.php nel child theme:
WordPress usa → child-theme/header.php
Ignora → parent-theme/header.php

Quando Usare un Child Theme

Struttura Minimale

Un child theme richiede solo DUE file:

my-child-theme/
├── style.css # Obbligatorio: header + CSS custom
└── functions.php # Opzionale ma consigliato

Struttura Completa:

my-child-theme/
├── style.css # Header tema + CSS personalizzato
├── functions.php # Funzioni custom, enqueue scripts
├── screenshot.png # Anteprima (1200x900px)
├── templates/ # Override template
│ ├── header.php
│ ├── footer.php
│ └── page-landing.php
└── assets/ # Risorse custom
├── css/
└── js/

Il File style.css: Header Obbligatorio

Ogni child theme DEVE iniziare con un header CSS commentato:

/*
Theme Name: Mio Child Theme
Theme URI: https://miosito.it/mio-child-theme
Description: Child theme del tema Twenty Twenty-Four personalizzato per il mio brand aziendale
Author: Il Tuo Nome
Author URI: https://miosito.it
Template: twentytwentyfour
Version: 1.0.0
License: GNU General Public License v2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Text Domain: mio-child-theme
Tags: custom-colors, custom-fonts, responsive-layout
*/

/* Il campo "Template" è CRUCIALE: deve corrispondere ESATTAMENTE al nome della cartella del tema parent */

Spiegazione Campi Header:

⚠️ ATTENZIONE: Il campo Template deve corrispondere ESATTAMENTE al nome della cartella del tema parent. Se il parent è in /wp-content/themes/twentytwentyfour/, allora Template: twentytwentyfour.

Il File functions.php

A differenza del parent, il functions.php del child theme viene caricato PRIMA di quello del parent.

Funzioni Base:

<!--?php 
/**
 * Mio Child Theme - Functions
 */

// Security: Prevent direct access
if (!defined('ABSPATH')) {
    exit;
}

/**
 * Enqueue parent and child theme stylesheets
 */
function mio_child_enqueue_styles() {
    // Carica stylesheet del tema parent
    wp_enqueue_style(
        'parent-style',
        get_template_directory_uri() . '/style.css'
    );

    // Carica stylesheet del child theme (dopo il parent)
    wp_enqueue_style(
        'child-style',
        get_stylesheet_directory_uri() . '/style.css',
        array('parent-style'),
        wp_get_theme()->get('Version')<br ?--> );
}
add_action('wp_enqueue_scripts', 'mio_child_enqueue_styles');

/**
* Aggiungi supporto funzionalità extra
*/
function mio_child_theme_setup() {
// Supporto per logo custom
add_theme_support('custom-logo', [
'height' => 200,
'width' => 400,
'flex-height' => true,
'flex-width' => true
]);

// Supporto featured images
add_theme_support('post-thumbnails');
}
add_action('after_setup_theme', 'mio_child_theme_setup', 20);

Capitolo 2: Setup Child Theme

Prerequisiti

Prima di iniziare, assicurati di avere:

• ✅ WordPress installato (locale o remoto)
• ✅ Tema parent installato e attivo
• ✅ Accesso FTP/SFTP o file manager
• ✅ Editor di testo (VS Code, Sublime Text)
• ✅ Browser con DevTools (Chrome, Firefox)

Step-by-Step: Creazione Child Theme

Step 1: Crea la Cartella

# Locale
mkdir -p ~/Documenti/www/wp-content/themes/mio-child-theme

# Oppure via FTP nel server
cd /wp-content/themes/
mkdir mio-child-theme

Step 2: Crea style.css

/*
Theme Name: Mio Child Theme
Template: twentytwentyfour
Version: 1.0.0
*/

Step 3: Crea functions.php

<!--?php 
function mio_child_enqueue_styles() {
    wp_enqueue_style('parent-style', get_template_directory_uri() . '/style.css');
    wp_enqueue_style('child-style', get_stylesheet_uri(), array('parent-style'));
}
add_action('wp_enqueue_scripts', 'mio_child_enqueue_styles');

Step 4: (Opzionale) Crea screenshot.png

• Immagine 1200x900px
• Rappresenta il tuo tema
• WordPress la mostra nella dashboard

Step 5: Comprimi in ZIP

zip -r mio-child-theme.zip mio-child-theme/

Installazione WordPress

Metodo 1: Upload Dashboard (Consigliato)

1. Vai su WordPress Admin → Aspetto → Temi
2. Clicca "Aggiungi nuovo" → "Carica tema"
3. Seleziona il file ZIP
4. Clicca "Installa ora"
5. Clicca "Attiva"

Metodo 2: FTP/SFTP

1. Connettiti via FTP (FileZilla)
2. Naviga in /wp-content/themes/
3. Carica cartella mio-child-theme
4. Attiva da WordPress Admin → Aspetto → Temi

Metodo 3: WP-CLI

# Accedi server SSH
ssh user@yourserver.com

# Installa e attiva
cd /var/www/html/wp-content/themes
wp theme activate mio-child-theme

Verifica Installazione

Dopo attivazione, verifica:

1. ✅ Sito appare identico al parent (nessun cambiamento visibile)
2. ✅ Entrambi stylesheet caricati (ispeziona codice sorgente)
3. ✅ Nessun errore console browser

Prompt AI per Debug:

Agisci come WordPress debugger expert.

Problema: [DESCRIVI]
Tema parent: [NOME]
Child theme: [NOME]

Codice style.css:
[INCOLLA]

Codice functions.php:
[INCOLLA]

Task: Analizza e fornisci soluzione.

Capitolo 3: Personalizzare Colori con AI

La Scienza del Prompt CSS

La qualità del CSS generato dipende dalla precisione del prompt.

Sii specifico su:

• Colori esatti (codici HEX o RGB)
• Elementi target (classi, ID, tag)
• Stati (hover, focus, active)
• Responsive behavior

Prompt per Palette Colori

Prompt Base:

Agisci come CSS expert WordPress.

Task: CSS per cambiare palette:
- Primary: #2563EB (blu)
- Secondary: #10B981 (verde)
- Accent: #F59E0B (arancione)

Elementi: header, bottoni, link, footer.

Vincoli: CSS variables, hover states.

Output: CSS completo.

Prompt Avanzato:

Agisci come CSS expert specializzato in WordPress themes e accessibilità WCAG.

CONTESTO:
Child theme per Twenty Twenty-Four. Brand aziendale professionale.

TASK:
Genera CSS custom per palette colori:

Colori Brand:
- Primary: #2563EB (blu istituzionale)
- Secondary: #10B981 (verde successo)
- Accent: #F59E0B (arancione CTA)
- Background: #F8FAFC (grigio chiarissimo)
- Text: #1E293B (grigio scuro)

Elementi da Modificare:
1. Header (background, testo, menu)
2. Bottoni primari (normale, hover, focus, active)
3. Link (normale, hover, visited)
4. Footer (background, testo, link)
5. Bordi e separatori
6. Form input (border, focus)

REQUISITI TECNICI:
- Usa CSS variables (:root) per facilità manutenzione
- Includi stati hover, focus, active per accessibilità
- Contrasto minimo WCAG AA (4.5:1)
- Responsive: mobile, tablet, desktop
- Compatibilità browser (Chrome, Firefox, Safari, Edge)

OUTPUT:
- Codice CSS completo con commenti
- Spiegazione scelte colori
- Note accessibilità

CSS Generato (Esempio Completo)

/* ============================================
   Mio Child Theme - Custom Color Palette
   ============================================ */

:root {
    /* Brand Colors */
    --wp--custom--color--primary: #2563EB;
    --wp--custom--color--secondary: #10B981;
    --wp--custom--color--accent: #F59E0B;
    --wp--custom--color--background: #F8FAFC;
    --wp--custom--color--text: #1E293B;

    /* Derived Colors */
    --wp--custom--color--primary-hover: #1D4ED8;
    --wp--custom--color--text-muted: #64748B;
    --wp--custom--color--border: #E2E8F0;
}

/* Header */
.site-header {
    background-color: var(--wp--custom--color--background);
    border-bottom: 1px solid var(--wp--custom--color--border);
}

.site-title a,
.site-description {
    color: var(--wp--custom--color--text);
}

/* Primary Buttons */
.wp-block-button__link,
button,
input[type="button"],
input[type="submit"] {
    background-color: var(--wp--custom--color--primary);
    color: #FFFFFF;
    border: none;
    padding: 12px 24px;
    border-radius: 6px;
    font-weight: 600;
    transition: all 0.3s ease;
}

.wp-block-button__link:hover,
button:hover,
input[type="button"]:hover,
input[type="submit"]:hover {
    background-color: var(--wp--custom--color--primary-hover);
    transform: translateY(-2px);
    box-shadow: 0 4px 12px rgba(37, 99, 235, 0.3);
}

/* Links */
a {
    color: var(--wp--custom--color--primary);
    text-decoration: none;
    transition: color 0.2s ease;
}

a:hover {
    color: var(--wp--custom--color--secondary);
}

/* Footer */
.site-footer {
    background-color: var(--wp--custom--color--text);
    color: #FFFFFF;
}

.site-footer a {
    color: var(--wp--custom--color--accent);
}

/* Accessibility: Focus States */
a:focus,
button:focus,
input:focus {
    outline: 2px solid var(--wp--custom--color--accent);
    outline-offset: 2px;
}

Strumenti AI per Palette Colori

Prompt per ColorBot:

Genera palette per sito:
- Settore: consulenza finanziaria
- Target: professionisti 30-50 anni
- Mood: affidabile, serio, professionale
- Colori da evitare: rosso, neon

Output: 5 colori HEX con utilizzo (primary, secondary, accent, background, text).

Capitolo 4: Cambiare Font con Google Fonts

Prompt per Tipografia

Agisci come typography expert web design.

TASK:
Implementa Google Fonts:

Font Scelti:
- Heading: "Playfair Display" (serif, elegante)
- Body: "Inter" (sans-serif, leggibile)
- Accent: "JetBrains Mono" (monospace, codice)

Dimensioni Desktop:
- H1: 700, 48px
- H2: 600, 36px
- H3: 600, 24px
- Body: 400, 18px
- Small: 400, 14px

Dimensioni Mobile:
- H1: 36px
- H2: 28px
- Body: 16px

Line Height:
- Headings: 1.2
- Body: 1.7

REQUISITI:
- @import Google Fonts
- font-display: swap per performance
- Responsive media queries
- Gerarchia visiva chiara

OUTPUT: CSS completo pronto per style.css.

CSS Generato

/* ============================================
   Mio Child Theme - Custom Typography
   ============================================ */

/* Import Google Fonts */
@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&family=JetBrains+Mono:wght@400;500&family=Playfair+Display:wght@600;700&display=swap');

:root {
    /* Font Families */
    --wp--custom--font--heading: 'Playfair Display', Georgia, serif;
    --wp--custom--font--body: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
    --wp--custom--font--mono: 'JetBrains Mono', 'Fira Code', monospace;

    /* Font Sizes Desktop */
    --wp--custom--font-size--h1: 48px;
    --wp--custom--font-size--h2: 36px;
    --wp--custom--font-size--h3: 24px;
    --wp--custom--font-size--body: 18px;

    /* Line Heights */
    --wp--custom--line-height--heading: 1.2;
    --wp--custom--line-height--body: 1.7;
}

/* Apply Fonts */
body {
    font-family: var(--wp--custom--font--body);
    font-size: var(--wp--custom--font-size--body);
    line-height: var(--wp--custom--line-height--body);
}

/* Headings */
h1, h2, h3, h4, h5, h6 {
    font-family: var(--wp--custom--font--heading);
    line-height: var(--wp--custom--line-height--heading);
    font-weight: 700;
}

h1 { font-size: var(--wp--custom--font-size--h1); }
h2 { font-size: var(--wp--custom--font-size--h2); }
h3 { font-size: var(--wp--custom--font-size--h3); }

/* Code Blocks */
code, pre {
    font-family: var(--wp--custom--font--mono);
    font-size: 0.9em;
}

/* Responsive */
@media (max-width: 768px) {
    :root {
        --wp--custom--font-size--h1: 36px;
        --wp--custom--font-size--h2: 28px;
        --wp--custom--font-size--body: 16px;
    }
}

Capitolo 5: Modificare Layout e Template

Override Template

WordPress segue gerarchia template precisa. Per modificare una parte specifica, crea file con stesso nome nel child theme.

Template Principali:

Prompt per Template Custom

Agisci come web designer landing page expert.

CONTESTO:
Landing page per corso online.

TASK:
Crea page-landing.php con:
1. Hero section (titolo, sottotitolo, CTA)
2. Benefici (3 colonne icone)
3. "Cosa impari" (lista)
4. Testimonianze (carousel)
5. Pricing table (3 tier)
6. FAQ accordion
7. CTA finale

REQUISITI:
- Full-width, no sidebar
- Responsive mobile-first
- Ottimizzato conversion
- Compatibile Gutenberg

OUTPUT: Template PHP + CSS + JS.

Capitolo 6: Ottimizzazione Performance

Best Practice

Lazy Loading

// Lazy loading immagini
function child_lazy_images($attr) {
    $attr['loading'] = 'lazy';
    return $attr;
}
add_filter('wp_get_attachment_image_attributes', 'child_lazy_images');

// Lazy loading iframe
function child_lazy_iframes($html) {
    return str_replace('<iframe', '<iframe loading="lazy"', $html);
}
add_filter('wp_oembed_result', 'child_lazy_iframes');

Ottimizzare Google Fonts

// Preconnect Google Fonts
function child_preconnect_fonts($urls, $relation_type) {
    if ('preconnect' === $relation_type) {
        $urls[] = array(
            'href' => 'https://fonts.gstatic.com',<br ?--> 'crossorigin' => 'anonymous',
);
}
return $urls;
}
add_filter('wp_resource_hints', 'child_preconnect_fonts', 10, 2);

Capitolo 7: Testing Pre-Lancio

Checklist Completa

• [ ] Responsive (mobile, tablet, desktop)
• [ ] Browser (Chrome, Firefox, Safari, Edge)
• [ ] PageSpeed Insights score > 80
• [ ] Accessibilità WCAG 2.1 AA
• [ ] SEO (meta tags, structured data)
• [ ] Compatibility plugin principali
• [ ] Aggiorna tema parent e verifica

Strumenti Testing

Conclusione

Hai completato una guida completa per child theme WordPress con AI.

Riepilogo Chiave

1. Child theme essenziali per customizzazioni sicure
2. AI accelera sviluppo ma valida sempre
3. Prompt specifici = codice migliore
4. Performance matters
5. Testa prima di produzione

Prossimi Passi

• 🎨 Crea il tuo primo child theme
• 📚 Studia temi popolari su GitHub
• 🤝 Unisciti community WordPress
• 💼 Offri servizi customizzazione

Happy theming! 🎨

Scopri come sviluppare plugin WordPress professionali utilizzando l'intelligenza artificiale. Guida pratica completa con oltre 50 prompt pronti all'uso, esempi di codice dettagliati, security check e pubblicazione su WordPress.org.

Introduzione

Lo sviluppo di plugin WordPress è sempre stato considerato un territorio riservato a sviluppatori esperti con anni di esperienza in PHP, MySQL e architettura software. Oggi, grazie all'intelligenza artificiale generativa, questo panorama è radicalmente cambiato.

Che tu sia un imprenditore digitale, un content creator, un piccolo business owner o semplicemente un appassionato di WordPress, puoi ora creare plugin personalizzati per il tuo sito senza scrivere una singola riga di codice.

Cosa Troverai in Questa Guida

Questa è una guida pratica e operativa che ti accompagnerà dall'idea iniziale fino alla pubblicazione del tuo primo plugin WordPress. Ogni capitolo include:

• Spiegazioni chiare e concise
• Esempi di codice completi e commentati
• Prompt AI pronti da copiare e incollare
• Checklist operative
• Tabelle riassuntive
• Best practice e avvertenze di sicurezza

Cosa Imparerai

1. Fondamenti - Architettura plugin, hook system, action e filter
2. Prompt Engineering - Come chiedere all'AI esattamente ciò che ti serve
3. Sicurezza - Validazione, sanitizzazione, protection da attacchi comuni
4. Ambiente Sviluppo - Docker, testing locale, debugging
5. Pubblicazione - WordPress.org requirements, submission process
6. Monetizzazione - Freemium, premium, servizi correlati

Perché Usare l'AI per Sviluppare Plugin

L'intelligenza artificiale non sostituisce lo sviluppatore professionista, ma potenzia enormemente le tue capacità. Ecco i vantaggi concreti:

Statistiche WordPress 2026

• 📊 WordPress alimenta il 43% di tutti i siti web (800+ milioni)
• 📦 Oltre 60.000 plugin gratuiti su WordPress.org
• 💰 Mercato plugin premium: $2+ miliardi annui
• ⏱️ Tempo sviluppo medio: 40-80 ore (riducibili a 8-15 con AI)
• 🚀 Crescita annuale nuovi plugin: +15%

Capitolo 1: Fondamenti dei Plugin WordPress

Cos'è Esattamente un Plugin WordPress

Un plugin WordPress è un pacchetto software che aggiunge funzionalità specifiche al tuo sito, estendendo le capacità del core senza modificarne il codice sorgente.

Analogia semplice: WordPress è come uno smartphone. Il core è il sistema operativo (iOS/Android). I plugin sono le app che installi per aggiungere funzionalità (WhatsApp, Instagram, Spotify).

Perché WordPress Usa i Plugin

La filosofia WordPress è "core minimale, estensioni modulari":

• Il core fornisce funzionalità essenziali (pubblicazione contenuti, gestione utenti, sistema template)
• I plugin aggiungono tutto il resto (e-commerce, SEO, form, backup, analytics)

Questo approccio ha enormi vantaggi:

1. Mantenibilità - Il core rimane leggero e facile da aggiornare
2. Flessibilità - Ogni sito può avere esattamente le funzionalità che gli servono
3. Sicurezza - Puoi disattivare plugin non necessari
4. Ecosistema - Community enorme di sviluppatori

Architettura Standard di un Plugin

Ogni plugin ben strutturato segue convenzioni di directory e file:

Struttura Base (Plugin Semplice):

my-custom-plugin/
├── my-custom-plugin.php      # File principale (obbligatorio)
├── readme.txt                # Documentazione
├── uninstall.php             # Cleanup disinstallazione
└── languages/                # Traduzioni
    └── my-plugin-it_IT.mo

Struttura Avanzata (Plugin Complesso):

my-custom-plugin/
├── my-custom-plugin.php      # Bootstrap e header
├── readme.txt                # Documentazione completa
├── uninstall.php             # Script disinstallazione
├── includes/                 # Logica PHP
│   ├── class-plugin-core.php
│   ├── class-admin-panel.php
│   ├── class-frontend.php
│   └── class-database.php
├── assets/                   # Risorse statiche
│   ├── css/admin.css
│   ├── css/frontend.css
│   ├── js/admin.js
│   └── js/frontend.js
├── templates/                # Template personalizzabili
│   ├── single-custom.php
│   └── archive-custom.php
└── languages/                # Traduzioni
    ├── my-plugin.pot
    └── my-plugin-it_IT.mo

Il File Header: La Carta d'Identità

Ogni plugin DEVE iniziare con un header PHP commentato. WordPress legge questo header per identificare il plugin.

Esempio Completo:

<?php
/**
 * Plugin Name:         My Custom Plugin
 * Plugin URI:          https://miosito.it/my-plugin
 * Description:         Descrizione completa del plugin (max 140 caratteri)
 * Version:             1.0.0
 * Author:              Il Tuo Nome
 * Author URI:          https://miosito.it
 * License:             GPL v2 or later
 * License URI:         https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain:         my-custom-plugin
 * Domain Path:         /languages
 * Requires at least:   5.8
 * Requires PHP:        7.4
 * Tested up to:        6.5
 */

// Security: Prevent direct access
if (!defined('ABSPATH')) {
    exit;
}

Spiegazione Campi:

Hook System: Il Cuore di WordPress

WordPress funziona attraverso hook (ganci) che permettono di intercettare e modificare il comportamento del core.

Esistono DUE tipi di hook:

1. Action Hooks (Eseguono Azioni)

Le action eseguono codice in momenti specifici del ciclo di vita WordPress.

Esempio Pratico Completo:

// Invia email quando un post viene pubblicato
add_action('publish_post', 'mia_notifica_email', 10, 2);

function mia_notifica_email($ID, $post) {
    // Recupera dati
    $titolo = $post->post_title;
    $url = get_permalink($ID);
    $admin_email = get_option('admin_email');

    // Prepara email
    $oggetto = 'Nuovo Post: ' . $titolo;
    $messaggio = "Ciao Admin,\n\n";
    $messaggio .= "Nuovo post pubblicato:\n";
    $messaggio .= "Titolo: $titolo\n";
    $messaggio .= "URL: $url\n";

    // Invia
    wp_mail($admin_email, $oggetto, $messaggio);
}

Action Hook Comuni:

2. Filter Hooks (Modificano Dati)

I filter modificano dati prima che vengano salvati o visualizzati.

Esempio Pratico Completo:

// Aggiungi contenuto alla fine dei post
add_filter('the_content', 'aggiungi_firma');

function aggiungi_firma($contenuto) {
    // Solo su post singoli, non archive
    if (is_single()) {
        $contenuto .= '<div class="firma">';
        $contenuto .= '<p><strong>Ti è piaciuto? Condividi!</strong></p>';
        $contenuto .= '</div>';
    }
    return $contenuto;
}

Filter Hook Comuni:

Capitolo 2: Prompt Engineering per Plugin

La Scienza del Prompt Perfetto

La qualità del codice generato dipende DIRETTAMENTE dalla qualità del tuo prompt.

Regola d'oro: Prompt vago = codice vago. Prompt specifico = codice specifico.

Formula PECTF

P = Persona (chi deve essere l'AI)
E = Contesto (situazione, background)
C = Compito (cosa deve fare)
T = Vincoli (regole, standard)
F = Formato (come presentare output)

Prompt per Struttura Plugin

Prompt Base:

Agisci come sviluppatore WordPress senior.

Contesto: Plugin prenotazioni appuntamenti.

Task: Genera struttura cartelle e file.

Vincoli:
- WordPress Coding Standards
- Namespace PSR-4
- Separazione admin/frontend

Output: Tree directory + spiegazione.

Prompt Avanzato (Consigliato):

Agisci come Lead Developer WordPress con 10+ anni esperienza e plugin con 10.000+ installazioni attive.

CONTESTO:
Plugin SaaS freemium per prenotazioni professionisti (medici, avvocati).
Deve essere stabile, sicuro, performante, GDPR compliant.

REQUISITI:
1. Frontend: calendario, form, email conferma, reminder
2. Backend: dashboard, gestione prenotazioni, impostazioni, export
3. Database: tabelle custom, indici, cleanup automatico
4. Sicurezza: nonce, capability, prepared statements, rate limiting

TASK:
Genera struttura completa cartelle e file.

STANDARD:
- WordPress Coding Standards 3.0
- PHP 7.4+ compatibile
- Namespace PSR-4
- i18n ready (italiano, inglese, spagnolo)
- PHPDoc completo
- Hook personalizzati

OUTPUT:
1. Tree directory completo
2. Spiegazione ogni file (scopo, 2-3 righe)
3. Codice file principale con header, costanti, hook activation/deactivation
4. Esempio classe core con singleton pattern

FORMATO:
- Markdown con syntax highlighting
- Commenti in italiano
- Esempi utilizzo hook
- Note best practice sicurezza

Prompt per Funzioni Database

Agisci come esperto sicurezza WordPress e ottimizzazione database.

CONTESTO:
Funzione salvataggio prenotazioni plugin.

TASK:
Scrivi funzione PHP che:

1. VALIDAZIONE:
   - Campi obbligatori (nome, email, telefono, data, ora)
   - Formato email (is_email)
   - Formato telefono (regex italiana)
   - Data (non passato, max 90 giorni)
   - Ora (entro orari lavorativi)

2. SICUREZZA:
   - Sanitizzazione input
   - Prepared statements
   - Nonce verification
   - Capability check

3. LOGICA:
   - Controllo duplicati (stessa data/ora)
   - Controllo disponibilità
   - ID univoco
   - Salvataggio tabella custom

4. ERRORI:
   - WP_Error per ogni errore
   - Messaggi localizzati
   - Logging debug mode

5. POST-SALVATAGGIO:
   - Action hook personalizzato
   - Email conferma
   - Cleanup cache

OUTPUT:
- Codice completo commentato riga-per-riga
- Esempio chiamata funzione
- Esempio gestione errore
- Spiegazione scelte sicurezza

Prompt per Code Review

Agisci come security auditor WordPress specializzato.

TASK:
Analizza questo codice e identifica:
1. Vulnerabilità (SQL injection, XSS, CSRF)
2. Violazioni WordPress Coding Standards
3. Funzioni deprecated
4. Bug logici
5. Problemi performance

CODICE:
[INCOLLA CODICE]

OUTPUT:
- Lista problemi con gravità (Critico/Alto/Medio/Basso)
- Riga codice problematica
- Codice corretto suggerito
- Spiegazione fix

Capitolo 3: Sicurezza e Validazione

Perché Validare il Codice AI

L'AI è potente ma NON infallibile. Può generare:

• ❌ Codice obsoleto (funzioni deprecated)
• ❌ Vulnerabilità non intenzionali
• ❌ Logica errata o incompleta
• ❌ Violazioni standards WordPress

Checklist Sicurezza Completa

Input Sanitization:

• [ ] sanitize_text_field() per testo semplice
• [ ] sanitize_email() per email
• [ ] sanitize_textarea_field() per textarea
• [ ] absint() per interi positivi
• [ ] sanitize_key() per slug/chiavi

Output Escaping:

• [ ] esc_html() per contenuto HTML
• [ ] esc_url() per URL
• [ ] esc_attr() per attributi HTML
• [ ] esc_js() per JavaScript
• [ ] wp_kses() per HTML con tag permessi

Database:

• [ ] $wpdb->prepare() per tutte le query
• [ ] Placeholder %s per stringhe
• [ ] Placeholder %d per interi
• [ ] Placeholder %f per float

Form e AJAX:

• [ ] wp_nonce_field() nei form
• [ ] check_admin_referer() o wp_verify_nonce() nella validazione
• [ ] current_user_can() per capability

Accesso Diretto:

• [ ] defined('ABSPATH') in ogni file PHP

Strumenti di Validazione

Capitolo 4: Ambiente Sviluppo Docker

Perché Docker

Docker crea un ambiente isolato, riproducibile e portabile.

docker-compose.yml Completo

version: '3.8'

services:
  wordpress:
    image: wordpress:latest
    container_name: wp_dev
    restart: unless-stopped
    ports:
      - "8080:80"
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD: wordpress
      WORDPRESS_DB_NAME: wordpress
    volumes:
      - ./wp-content:/var/www/html/wp-content
      - ./plugins/my-plugin:/var/www/html/wp-content/plugins/my-plugin
    depends_on:
      - db
    networks:
      - wp_network

  db:
    image: mariadb:10
    container_name: wp_db
    restart: unless-stopped
    environment:
      MYSQL_DATABASE: wordpress
      MYSQL_USER: wordpress
      MYSQL_PASSWORD: wordpress
      MYSQL_ROOT_PASSWORD: rootpassword
    volumes:
      - db_data:/var/lib/mysql
    networks:
      - wp_network

  phpmyadmin:
    image: phpmyadmin:latest
    container_name: wp_phpmyadmin
    ports:
      - "8081:80"
    environment:
      PMA_HOST: db
    depends_on:
      - db
    networks:
      - wp_network

volumes:
  db_data:

networks:
  wp_network:

Comandi Essenziali

# Avvia
docker compose up -d

# Ferma
docker compose down

# Log
docker compose logs -f wordpress

# Accedi
docker compose exec wordpress bash

# WP-CLI
docker compose exec wordpress wp plugin list

Capitolo 5: Pubblicazione WordPress.org

Requisiti Obbligatori

• ✅ Codice conforme WordPress Coding Standards
• ✅ Licenza GPL-compatible
• ✅ readme.txt completo e formattato
• ✅ Nessuna chiamata HTTP esterna non opzionale
• ✅ Nessuna pubblicità o link promozionali
• ✅ Security: input sanitizzati, output escaped
• ✅ i18n ready per traduzioni

Processo di Sottomissione

1. Crea Account su wordpress.org/support/register/
2. Prepara Pacchetto ZIP (no .git, no test, no node_modules)
3. Sottometti su wordpress.org/plugins/developers/add/
4. Attendi Review (2-5 giorni lavorativi)
5. Rispondi Feedback e aggiorna se necessario

readme.txt Template

=== Plugin Name ===
Contributors: tuo-username
Tags: tag1, tag2, tag3
Requires at least: 5.8
Tested up to: 6.5
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later

Breve descrizione (max 150 caratteri).

== Description ==

Descrizione completa.

== Installation ==

1. Carica plugin in /wp-content/plugins/
2. Attiva da menu Plugin
3. Configura impostazioni

== Changelog ==

= 1.0.0 =
* Release iniziale

Conclusione

Hai completato una guida completa per sviluppare plugin WordPress con AI.

I 10 Comandamenti

1. AI è assistente, non sostituto
2. Valida sempre il codice
3. Documenta tutto
4. Testa in ambiente isolato
5. Segui WordPress Coding Standards
6. Chiedi spiegazioni all'AI
7. Itera rapidamente
8. Usa Git per backup
9. Condividi con community
10. Divertiti!

Risorse

Buon coding! 🚀

Meta: 2100+ parole | 12 min lettura

Fortunatamente, l'avvento dell'intelligenza artificiale generativa ha cambiato le regole del gioco. Oggi è possibile automatizzare la pubblicazione WordPress integrando strumenti AI avanzati direttamente nel flusso di lavoro del CMS. Questa trasformazione digitale permette di passare da una gestione manuale e frammentaria a un sistema fluido, dove gli articoli ottimizzati SEO possono essere generati e programmati in pochi minuti invece che ore.

In questo tutorial completo, esploreremo come sfruttare l'AI per gestire il tuo sito WordPress. Analizzeremo gli strumenti migliori, le procedure passo-passo per configurare l'automazione e le best practices per mantenere alta la qualità umana senza sacrificare l'efficienza tecnologica. Sei pronto a trasformare il modo in cui pubblichi online?

Perché Automatizzare la Gestione di WordPress con l'AI?

L'automazione non significa semplicemente "fare meno lavoro", significa lavorare in modo più intelligente. Integrare l'intelligenza artificiale nella gestione di WordPress offre vantaggi tangibili che vanno oltre il semplice risparmio di tempo.

1. Scalabilità dei Contenuti

Con l'AI, non sei più limitato dalla tua velocità di scrittura. Puoi produrre cluster di contenuti correlati per coprire intere nicchie di mercato in tempi record. Questo è fondamentale per strategie di SEO programmatica, dove la quantità e la rilevanza dei contenuti influenzano direttamente l'autorità del dominio.

2. Ottimizzazione SEO Costante

Gli strumenti AI moderni non si limitano a scrivere testo. Possono analizzare le keyword, suggerire meta description, gestire la densità delle parole chiave e strutturare i titoli (H1, H2, H3) secondo gli standard di Google. Automatizzare questo processo riduce il rischio di errori umani e dimenticanze ottimizzate.

3. Consistenza Editoriale

Uno degli algoritmi più importanti è quello della costanza. I motori di ricerca premiano i siti che pubblicano regolarmente. Un sistema automatizzato garantisce che il tuo calendario editoriale venga rispettato, anche durante periodi di forte carico di lavoro o ferie, mantenendo vivo l'interesse del pubblico e dei crawler di ricerca.

Gli Strumenti Migliori per l'Automazione AI su WordPress

Per automatizzare la pubblicazione WordPress, hai bisogno di un ecosistema di strumenti che comunichino tra loro. Non esiste una soluzione unica, ma una combinazione di plugin e servizi esterni.

Plugin AI Nativi per WordPress

Esistono plugin progettati specificamente per integrare modelli linguistici (come GPT-4) direttamente nella dashboard di WordPress. Soluzioni come AI Engine, ContentBot o Bertha.ai permettono di generare bozze, titoli e meta tag senza lasciare il sito. Questi plugin sono ideali per chi preferisce mantenere tutto l'ambiente di lavoro centralizzato.

Piattaforme di Automazione (Make/Zapier)

Per un controllo maggiore, puoi utilizzare piattaforme di automazione come Make (ex Integromat) o Zapier. Questi servizi agiscono come ponte: possono prendere uno spunto da un foglio Google, inviare il prompt a un'API AI (come OpenAI), ricevere il testo e pubblicarlo automaticamente sul tuo sito WordPress tramite le API REST. Questo metodo offre la massima flessibilità per flussi di lavoro complessi.

Strumenti di Ottimizzazione SEO

Plugin come RankMath o Yoast SEO stanno integrando funzionalità AI per suggerire miglioramenti in tempo reale. Utilizzarli in conjunction con generatori di contenuto assicura che ogni post pubblicato sia già conforme agli standard di leggibilità e indicizzazione.

Guida Step-by-Step: Configurare il Flusso di Lavoro

Configurare un sistema di pubblicazione automatica richiede attenzione ai dettagli. Ecco una procedura operativa standard per iniziare.

Fase 1: Generazione del Contenuto

Il primo passo è definire il prompt. Non chiedere semplicemente "scrivi un articolo". Specifica il tono di voce, la struttura, la keyword principale e il pubblico target. Utilizza l'API di un modello linguistico per generare il testo grezzo. Assicurati che il sistema includa istruzioni per formattare il testo in HTML o Markdown, pronto per l'incollamento nell'editor di WordPress (Gutenberg o Classic).

Fase 2: Ottimizzazione SEO Automatica

Prima della pubblicazione, il contenuto deve essere arricchito. Il tuo flusso di automazione dovrebbe includere un passaggio per:

• Generare una meta description accattivante (max 160 caratteri).
• Inserire la focus keyword nel primo paragrafo e nei sottotitoli.
• Suggerire testi alternativi (alt text) per le immagini.

Fase 3: Programmazione e Pubblicazione

Una volta pronto, l'articolo non deve necessariamente andare online subito. Imposta il tuo sistema per pubblicare in "Bozza" per una revisione finale, oppure programma la pubblicazione negli orari di picco del tuo traffico. Le API di WordPress permettono di impostare la data di pubblicazione futura (date_gmt), garantendo che il contenuto appaia al momento giusto.

Best Practices: Quando l'Intervento Umano è Necessario

Nonostante la potenza dell'automazione, il fattore umano rimane insostituibile per garantire qualità e fiducia. Automatizzare la pubblicazione WordPress non significa abdicare al controllo editoriale.

Verifica dei Fatti (Fact-Checking)

L'AI può allucinare, ovvero inventare dati o fonti. È cruciale verificare statistiche, nomi di prodotti e affermazioni tecniche prima di pubblicare. Un errore fattuale può danneggiare la credibilità del sito irreparabilmente.

Tono e Brand Voice

L'AI tende a essere generica. Un editor umano deve leggere il contenuto per assicurarsi che rispecchi i valori del brand, aggiunga esperienze personali o aneddoti che solo una persona reale può raccontare. Questo "tocco umano" è anche un fattore di ranking crescente per Google (concetto di E-E-A T: Experience, Expertise, Authoritativeness, Trustworthiness).

Gestione delle Immagini

Le immagini generate dall'AI possono essere utili, ma spesso mancano di contesto reale. Integrare screenshot originali, foto del team o grafiche personalizzate aumenta l'engagement e riduce il rischio di problemi di copyright.

Conclusioni: Il Futuro è Ibrido

L'integrazione dell'intelligenza artificiale nella gestione di WordPress non è una moda passeggera, ma un'evoluzione necessaria per rimanere competitivi nel panorama digitale. Automatizzare la pubblicazione WordPress ti permette di scalare la produzione di contenuti, migliorare la SEO tecnica e liberare tempo per la strategia e la creatività.

Tuttavia, il successo risiede nell'equilibrio. Usa l'AI come un potente assistente che gestisce la pesantezza operativa, ma mantieni il controllo umano sulla qualità, sull'etica e sulla voce del brand. In questo modo, otterrai un sito web veloce, ricco di contenuti e, soprattutto, affidabile per i tuoi utenti.

Sei pronto a rivoluzionare il tuo flusso di lavoro? Inizia oggi stesso testando un plugin AI per WordPress o configurando una semplice automazione su Make. Condividi nei commenti quale strumento intendi utilizzare per primo e iscriviti alla nostra newsletter per ricevere altri tutorial avanzati sulla gestione di siti web moderni.

Questa guida copre tutto — dall'installazione alla configurazione avanzata — con tre esempi pratici di skill pronti all'uso, inclusa una che pubblica automaticamente articoli giornalistici su WordPress tramite WP-CLI.

1. Cos'è OpenClaw e come funziona

OpenClaw (precedentemente noto come MoltBot e ClawdBot) è un framework open-source per agenti AI personali, progettato per girare direttamente sul proprio hardware. A differenza degli assistenti AI tradizionali, non si limita a rispondere a domande: agisce, esegue comandi, automatizza flussi di lavoro e impara nuove abilità in modo autonomo.

Creato da Peter Steinberger (fondatore di PSPDFKit), il progetto si basa su tre principi fondamentali:

• Local-first — tutti i dati, la memoria e le configurazioni risiedono sul proprio machine, senza dipendenza da servizi cloud.
• Model-agnostic — supporta Claude (Anthropic), GPT-4, Gemini, Llama e qualsiasi modello compatibile con l'API OpenAI.
• Community-extensible — le Skill sono file SKILL.md portabili, condivisibili e installabili dal marketplace ClawHub.

Il Loop dell'Agente

Quando si lancia openclaw gateway, si avvia un singolo processo Node.js che gestisce tutto: canali di messaggistica, sessioni, chiamate al modello, esecuzione degli strumenti e persistenza della memoria. Il ciclo agentico si compone di quattro fasi:

1. Perceive — riceve un input (comando utente, evento cron, webhook, heartbeat).
2. Plan — l'LLM analizza il contesto, la memoria e le skill disponibili.
3. Act — esegue strumenti: shell, browser, web fetch, file system, API.
4. Reflect — aggiorna la memoria, notifica l'utente e attende il prossimo ciclo.

Dove si posiziona rispetto ad altri strumenti

Gli LLM puri (ChatGPT, Claude) sono intelligenti ma non agiscono. Gli strumenti di automazione (n8n, Make, Zapier) agiscono ma richiedono configurazione esplicita. OpenClaw unisce entrambi: l'LLM decide cosa fare, il Gateway lo esegue.

2. Installazione

Requisiti di sistema

Installazione via npm

npm install -g openclaw@latest

In alternativa con pnpm:

pnpm add -g openclaw@latest

Verifica l'installazione:

openclaw --version

Installazione via script (Linux/macOS)

curl -fsSL https://clawd.bot/install.sh | bash

⚠️ Sicurezza — Prima di eseguire script via curl, esamina sempre il contenuto su clawd.bot. OpenClaw richiede permessi elevati sulla macchina.

Onboarding Wizard

Dopo l'installazione, avvia il wizard interattivo:

openclaw onboard --install-daemon

Il flag --install-daemon installa il daemon di sistema (launchd su macOS, systemd su Linux) in modo che il Gateway rimanga sempre attivo in background. Il wizard configura: modello LLM, canale di messaggistica, workspace principale e prime skill.

Verifica con Doctor

openclaw doctor

Controlla: stato del daemon, API key configurate, permessi del workspace, policy DM, presenza di binari richiesti dalle skill attive.

3. Configurazione

Il file principale: ~/.openclaw/openclaw.json

{
  "agents": {
    "defaults": {
      "model": "claude-opus-4-6",
      "provider": "anthropic",
      "maxTokens": 8192
    }
  },
  "gateway": {
    "port": 18789,
    "host": "127.0.0.1"
  },
  "skills": {
    "load": {
      "extraDirs": ["/path/to/custom/skills"]
    }
  }
}

Configurazione dei Modelli LLM

OpenClaw supporta qualsiasi provider compatibile OpenAI. I principali:

• Anthropic (Claude) — raccomandato per resistenza all'injection e long-context
• OpenAI (GPT-4, GPT-4o)
• Google (Gemini Flash, Gemini Pro)
• Provider locali via Ollama o LM Studio

Esempio configurazione Anthropic:

"providers": {
  "anthropic": {
    "apiKey": "sk-ant-...",
    "defaultModel": "claude-opus-4-6"
  }
}

Failover automatico tra modelli:

"modelFailover": [
  "claude-opus-4-6",
  "claude-sonnet-4-6",
  "gpt-4o"
]

💡 Consiglio — Usa claude-opus-4-6 per task complessi (ragionamento, coding, analisi) e Gemini Flash per task semplici (riassunti, lookup veloci). Puoi cambiare modello dal menu Telegram in qualsiasi momento.

Configurazione dei Canali

Telegram — il canale più semplice per iniziare. Crea un bot con @BotFather e ottieni il token:

"channels": {
  "telegram": {
    "enabled": true,
    "token": "YOUR_BOT_TOKEN",
    "ownerIds": [123456789]
  }
}

Slack — richiede una Slack App con permessi chat:write, im:read, im:write, users:read:

"slack": {
  "enabled": true,
  "botToken": "xoxb-...",
  "signingSecret": "...",
  "appToken": "xapp-..."
}

Il file soul.md

Uno degli aspetti più potenti di OpenClaw è il file soul.md — la personalità e le istruzioni permanenti dell'agente. Si trova nel workspace principale e viene caricato come system prompt persistente:

# Il mio Assistente AI Personale

## Personalità
Sei un assistente professionale, preciso e proattivo. Parli italiano.
Anticipi le esigenze e proponi soluzioni prima di essere interrogato.

## Contesto
- Nome: Marco
- Professione: Giornalista digitale
- Sito WordPress: https://miosito.it
- Server: VPS Ubuntu 22.04

## Regole operative
1. Prima di eseguire comandi distruttivi, chiedi conferma.
2. Logga sempre le azioni importanti in ~/logs/agent.log
3. Avvisami su Telegram se qualcosa va storto.

Sicurezza — Best Practice

• Non installare mai OpenClaw sull'account root di un server di produzione.
• Usa VM o container dedicati per ambienti ad alto rischio.
• Configura le Exec Approvals per i comandi shell pericolosi.
• Imposta spending cap sul dashboard del provider LLM.
• Esegui openclaw doctor regolarmente.

⚠️ Attenzione — Un agente in loop può consumare molti token rapidamente. Imposta sempre un limite mensile di spesa prima di avviare automazioni autonome.

4. Il Sistema delle Skills

Cos'è una Skill

Una skill in OpenClaw è una cartella contenente un file SKILL.md con frontmatter YAML e istruzioni in linguaggio naturale. Le skill insegnano all'agente come usare strumenti specifici, seguire procedure particolari o automatizzare task ricorrenti.

my-skill/
  SKILL.md         # definizione principale
  scripts/         # script Python/Bash
  config.json      # configurazione opzionale

Anatomia di un SKILL.md

---
name: nome-skill
description: Descrizione breve che appare nel prompt dell'agente
homepage: https://link-documentazione.com
user-invocable: true
disable-model-invocation: false
metadata:
  {"openclaw": {
    "emoji": "🔧",
    "requires": {
      "bins": ["wp", "python3"],
      "env": ["WP_SSH_HOST"],
      "config": ["browser.enabled"]
    }
  }}
---

# Istruzioni per l'agente

Qui vanno le istruzioni dettagliate in linguaggio naturale.
L'agente le leggerà e le seguirà per eseguire il task.

Posizioni e Precedenza

OpenClaw carica le skill da tre posizioni, in ordine di precedenza:

1. Workspace skills — <workspace>/skills → priorità massima
2. Managed/local skills — ~/.openclaw/skills → condivise tra tutti gli agenti
3. Bundled skills — incluse nell'installazione npm → priorità minima

ClawHub — Il Marketplace

ClawHub è il registry pubblico delle skill per OpenClaw. Comandi principali:

# Cerca una skill
clawhub search wordpress

# Installa una skill nel workspace
clawhub install wordpress-publisher

# Aggiorna tutte le skill installate
clawhub update --all

Gating (Filtri al Caricamento)

OpenClaw filtra le skill al caricamento in base ai requisiti dichiarati:

Iniezione di Segreti nelle Skill

"skills": {
  "entries": {
    "my-wordpress-skill": {
      "env": {
        "WP_DB_PASS": "secret123",
        "UNSPLASH_KEY": "your-api-key"
      }
    }
  }
}

5. Automazione: Cron, Heartbeat e Webhook

Cron Jobs

"cron": {
  "jobs": [
    {
      "id": "morning-briefing",
      "schedule": "0 8 * * *",
      "prompt": "Prepara il briefing mattutino: meteo, news, calendario.",
      "channel": "telegram"
    },
    {
      "id": "weekly-report",
      "schedule": "0 9 * * 1",
      "prompt": "Genera il report settimanale di analytics WordPress.",
      "channel": "slack"
    }
  ]
}

Heartbeat (Ciclo Autonomo)

"heartbeat": {
  "enabled": true,
  "intervalMinutes": 60,
  "prompt": "Controlla se ci sono task pendenti, aggiorna la memoria, invia notifiche se necessario."
}

💡 Differenza chiave — Il Cron è per task schedulati a orari precisi. Il Heartbeat è per check periodici autonomi. In pratica: usa il Cron per "pubblica alle 9:00", usa il Heartbeat per "controlla ogni ora se c'è qualcosa da fare".

Webhook

"webhooks": {
  "enabled": true,
  "endpoints": [
    {
      "path": "/github-push",
      "secret": "your-webhook-secret",
      "prompt": "Un nuovo push su GitHub. Analizza le modifiche e aggiorna la documentazione."
    }
  ]
}

6. Configurazione Multi-Agent

OpenClaw supporta più agenti sullo stesso Gateway, ognuno con il proprio workspace, soul.md, set di skill e canale dedicato. Architettura ideale per:

• Separare agenti per ruolo (sviluppo, marketing, giornalismo)
• Isolare gli ambienti per sicurezza (agente untrusted in sandbox Docker)
• Condividere skill comuni tra agenti diversi

Routing dei canali:

"routing": {
  "telegram": {
    "workBot": "agent-work",
    "personalBot": "agent-personal"
  }
}

7. Esempi di impostazione Skills OpenClaw

Skill 1 — Web Scraper e Digest Quotidiano delle News

Raccoglie automaticamente notizie da fonti RSS, le aggrega, applica un'analisi editoriale e invia un digest formattato su Telegram ogni mattina.

Struttura della cartella:

~/.openclaw/skills/news-digest/
  SKILL.md
  scripts/
    fetch_rss.py
  sources.json

SKILL.md:

---
name: news-digest
description: Raccoglie news da RSS, le aggrega e invia un digest quotidiano su Telegram
user-invocable: true
metadata:
  {"openclaw": {
    "emoji": "📰",
    "requires": {
      "bins": ["python3"],
      "env": ["TELEGRAM_CHAT_ID"]
    }
  }}
---

# Skill: News Digest Quotidiano

## Trigger
Eseguita automaticamente alle 7:30 via cron job, oppure con /news-digest.

## Procedura

1. Esegui: python3 {baseDir}/scripts/fetch_rss.py > /tmp/raw_news.json

2. Per ogni notizia applica questa analisi:
   - Valuta la rilevanza (1-10): impatto, novità, interesse
   - Scrivi un riassunto di 2-3 righe in italiano
   - Assegna categoria: Tecnologia, Economia, Politica, Scienza, Altro

3. Seleziona le TOP 5 notizie per rilevanza.

4. Formatta il digest:
   🌅 *Buongiorno! Digest News — [DATA]*
   📌 *[TITOLO]*
   [RIASSUNTO]
   🔗 [LINK]

5. Invia su Telegram. Logga in ~/openclaw-logs/news-digest-[DATA].json

scripts/fetch_rss.py:

#!/usr/bin/env python3
import json, feedparser
from datetime import datetime, timedelta

SOURCES = json.load(open('{baseDir}/sources.json'))
articles = []

for src in SOURCES['feeds']:
    feed = feedparser.parse(src['url'])
    for entry in feed.entries[:10]:
        articles.append({
            'title': entry.get('title', ''),
            'summary': entry.get('summary', '')[:400],
            'link': entry.get('link', ''),
            'source': src['name']
        })

print(json.dumps(articles, ensure_ascii=False))

sources.json:

{
  "feeds": [
    {"name": "Ansa",     "url": "https://www.ansa.it/sito/notizie/tecnologia/tecnologia_rss.xml"},
    {"name": "Wired IT", "url": "https://www.wired.it/feed/rss"},
    {"name": "BBC Tech", "url": "https://feeds.bbci.co.uk/news/technology/rss.xml"}
  ]
}

Configurazione cron:

{
  "cron": {
    "jobs": [{
      "id": "morning-news",
      "schedule": "30 7 * * *",
      "prompt": "Esegui la skill news-digest e invia il digest mattutino.",
      "channel": "telegram"
    }]
  }
}

Skill 2 — Monitoraggio e Alert del Server

Monitora periodicamente CPU, RAM, disco e servizi critici di un server Linux, inviando alert proattivi con diagnosi e azioni consigliate su Telegram.

Struttura della cartella:

~/.openclaw/skills/server-monitor/
  SKILL.md
  scripts/
    check_metrics.sh
  thresholds.json

SKILL.md:

---
name: server-monitor
description: Monitora CPU, RAM, disco e servizi del server con alert intelligenti su Telegram
user-invocable: true
metadata:
  {"openclaw": {
    "emoji": "🖥️",
    "requires": {
      "bins": ["df", "free", "top", "systemctl", "python3"],
      "env": ["ALERT_TELEGRAM_CHAT_ID"]
    },
    "os": ["linux"]
  }}
---

# Skill: Server Monitor con Alert Intelligenti

## Esecuzione automatica
Gira ogni 15 minuti via heartbeat.

## Procedura

1. Raccogli metriche:
   bash {baseDir}/scripts/check_metrics.sh > /tmp/metrics.txt

2. Confronta i valori con {baseDir}/thresholds.json

3. Determina la gravità:
   - WARNING (🟡): metrica tra 70% e 85% della soglia critica
   - CRITICAL (🔴): metrica sopra l'85%

4. Genera alert con:
   - Metrica problematica e valore attuale
   - Diagnosi probabile (es. "Possibile memory leak in nginx")
   - Azioni consigliate (comandi specifici)

5. In caso di CRITICAL, esegui automaticamente:
   sudo systemctl restart nginx (se nginx è coinvolto)
   Notifica l'azione intrapresa.

scripts/check_metrics.sh:

#!/bin/bash
echo "=== CPU ==="
top -bn1 | grep 'Cpu(s)' | awk '{print $2}' | cut -d'%' -f1

echo "=== RAM ==="
free -m | awk 'NR==2{printf "%.1f\n", $3*100/$2}'

echo "=== DISCO ==="
df -h / | awk 'NR==2{print $5}' | tr -d '%'

echo "=== SERVIZI ==="
for svc in nginx mysql php8.2-fpm; do
  systemctl is-active $svc 2>/dev/null && echo "$svc:OK" || echo "$svc:FAIL"
done

thresholds.json:

{
  "cpu_warning": 70,
  "cpu_critical": 90,
  "ram_warning": 75,
  "ram_critical": 90,
  "disk_warning": 80,
  "disk_critical": 95,
  "services": ["nginx", "mysql", "php8.2-fpm"]
}

⚠️ Sicurezza — Configura sudoers per permettere solo i comandi specifici necessari (es. systemctl restart nginx) senza password, e mai con accesso root completo.

Skill 3 — WordPress Remote News Publisher via SSH + WP-CLI

Versione remota della Skill 3 originale.
Rispetto alla versione locale, questa skill non richiede WP-CLI installato sulla macchina che esegue OpenClaw: tutta l'interazione con WordPress avviene sul server remoto tramite connessione SSH con autenticazione automatica a chiave pubblica. Le immagini vengono scaricate e ottimizzate localmente, trasferite sul server via scp, e poi importate con wp media import eseguito in remoto.

Struttura della cartella

~/.openclaw/skills/wp-remote-publisher/
  SKILL.md
  scripts/
    download_cover.py
    optimize_image.sh
    upload_media_remote.sh
    publish_wp_remote.sh
  config.json

SKILL.md

---
name: wp-remote-publisher
description: Genera e pubblica automaticamente articoli di news su WordPress remoto
            via SSH con autenticazione a chiave pubblica e WP-CLI installato sul server.
            Scarica e ottimizza immagini di copertina da Unsplash, le trasferisce via scp
            e pubblica con metadati SEO Yoast.
user-invocable: true
metadata:
  {"openclaw": {
    "emoji": "📝",
    "requires": {
      "bins": ["ssh", "scp", "python3", "curl", "convert"],
      "env": [
        "WP_SSH_HOST",
        "WP_SSH_USER",
        "WP_SSH_KEY",
        "WP_REMOTE_PATH",
        "UNSPLASH_ACCESS_KEY",
        "WP_AUTHOR_ID"
      ]
    }
  }}
---

#### Skill: WordPress Remote News Publisher

#### IMPORTANTE — Filosofia Editoriale

Ogni articolo DEVE rispettare queste regole:
- Scrivi come un giornalista senior del settore, non come un AI.
- Usa frasi di lunghezza variabile. Alterna periodi brevi a costruzioni articolate.
- Inserisci una tesi editoriale chiara nel primo paragrafo (lede).
- Usa citazioni attribuite a fonti reali quando disponibili.
- EVITA: "è importante notare", "nell'era digitale", "nel mondo di oggi",
  "in conclusione", "ovviamente", "chiaramente", qualsiasi formula AI.
- Il titolo deve essere specifico. Niente clickbait.

#### Variabili d'ambiente richieste

| Variabile           | Descrizione                                             | Esempio                              |
|---------------------|---------------------------------------------------------|--------------------------------------|
| WP_SSH_HOST         | Hostname o IP del server remoto                         | `203.0.113.10` o `miosito.it`        |
| WP_SSH_USER         | Utente SSH sul server remoto                            | `ubuntu` / `www-data` / `deploy`     |
| WP_SSH_KEY          | Path assoluto alla chiave privata SSH locale            | `/home/user/.ssh/id_ed25519_wp`      |
| WP_SSH_PORT         | Porta SSH (default 22)                                  | `22`                                 |
| WP_REMOTE_PATH      | Path assoluto di WordPress sul server remoto            | `/var/www/html/wordpress`            |
| WP_REMOTE_TMP       | Cartella temporanea scrivibile sul server remoto        | `/tmp`                               |
| UNSPLASH_ACCESS_KEY | Access Key API Unsplash                                 | `AbC123...`                          |
| WP_AUTHOR_ID        | ID autore WordPress                                     | `1`                                  |

#### Trigger
Eseguita ogni giorno alle 10:00 e 16:00 (lun-ven) via cron job.
Invocabile manualmente con: /wp-remote-publisher [argomento]

---

#### Procedura Completa

#### FASE 1 — Selezione Argomento
Se non viene fornito un argomento:
1. Leggi {baseDir}/config.json per la lista di topic configurati.
2. Seleziona il topic con la pubblicazione più vecchia (round-robin).

#### FASE 2 — Verifica Connessione SSH
Prima di qualsiasi operazione, verifica che la connessione SSH funzioni:

  ssh -i $WP_SSH_KEY -p ${WP_SSH_PORT:-22} -o StrictHostKeyChecking=no \
      -o BatchMode=yes -o ConnectTimeout=10 \
      $WP_SSH_USER@$WP_SSH_HOST \
      "wp --info --path=$WP_REMOTE_PATH" 2>&1

Se il comando fallisce, interrompi e notifica l'errore su Telegram.

#### FASE 3 — Ricerca e Raccolta Fatti
1. Cerca via web: "[argomento] ultime notizie [mese corrente]"
   Cerca anche in inglese per fonti internazionali.

2. Raccogli SOLO fatti verificabili:
   - Dati numerici con fonte
   - Dichiarazioni di persone reali con nome e ruolo
   - Date ed eventi specifici
   - Evita speculazioni non attribuite

3. Salva i fatti in /tmp/wp_facts.json

#### FASE 4 — Generazione Articolo con Stile Giornalistico

Struttura editoriale obbligatoria:

**TITOLO** (max 65 caratteri)
- Specifico, non generico. Contiene il fatto principale.
- Buono:  "Meta taglia 3.600 posti: addio ai team AI di Base"
- Cattivo: "Meta compie un passo importante per il futuro"

**LEDE** (primo paragrafo, 40-60 parole)
- Risponde a: Chi? Cosa? Quando? Dove? Perché?
- È la notizia più importante in forma densa e precisa.
- Non inizia mai con "Nel mondo di..." o "Negli ultimi anni..."

**CORPO** (600-900 parole totali)
- Paragrafo 2: contesto e background
- Paragrafo 3-4: sviluppo principale con dati e citazioni
- Paragrafo 5: reazioni e posizioni dei protagonisti
- Paragrafo 6: implicazioni e prospettive (attribuite a esperti)
- Paragrafo finale: elemento che chiude il cerchio narrativo

**META DESCRIPTION** (max 155 caratteri)
**TAG SEO** (3-5 tag, senza #)
**KEYWORD PRINCIPALE** (1 keyword)

Salva in /tmp/wp_article.json:
{
  "title": "...",
  "content": "...",
  "excerpt": "...",
  "tags": ["..."],
  "meta_desc": "...",
  "keyword": "...",
  "topic": "..."
}

#### FASE 5 — Immagine di Copertina
1. Determina una keyword visiva (es. "server room technology").
2. Scarica da Unsplash LOCALMENTE:
   python3 {baseDir}/scripts/download_cover.py '[keyword]' /tmp/cover.jpg
3. Ottimizza localmente:
   bash {baseDir}/scripts/optimize_image.sh /tmp/cover.jpg /tmp/cover_opt.jpg
4. Trasferisci sul server remoto e importa in WordPress:
   bash {baseDir}/scripts/upload_media_remote.sh /tmp/cover_opt.jpg
   → ID salvato in /tmp/wp_media_id.txt

#### FASE 6 — Pubblicazione su WordPress Remoto
1. Esegui: bash {baseDir}/scripts/publish_wp_remote.sh
2. Post creato come draft. Aspetta 30 secondi, verifica lo stato via SSH.
3. Se OK, pubblica:
   ssh -i $WP_SSH_KEY -p ${WP_SSH_PORT:-22} $WP_SSH_USER@$WP_SSH_HOST \
     "wp post update $(cat /tmp/wp_post_id.txt) \
      --post_status=publish --path=$WP_REMOTE_PATH"
4. Recupera l'URL del post pubblicato:
   ssh -i $WP_SSH_KEY -p ${WP_SSH_PORT:-22} $WP_SSH_USER@$WP_SSH_HOST \
     "wp post get $(cat /tmp/wp_post_id.txt) --field=url --path=$WP_REMOTE_PATH"
5. Invia conferma su Telegram con titolo, URL, parole, keyword.

#### FASE 7 — Aggiornamento Registro
Aggiorna {baseDir}/config.json segnando il topic come
"ultimo pubblicato" con timestamp per garantire la rotazione.

config.json

{
  "wp_remote_path": "/var/www/html/wordpress",
  "author_id": 1,
  "categories": {
    "tecnologia": 5,
    "economia": 8,
    "startup": 12
  },
  "topics": [
    {
      "name": "Intelligenza Artificiale",
      "keywords": ["AI", "machine learning", "LLM"],
      "category": "tecnologia",
      "last_published": null
    },
    {
      "name": "Cybersecurity",
      "keywords": ["sicurezza informatica", "hacking", "privacy"],
      "category": "tecnologia",
      "last_published": null
    },
    {
      "name": "Startup Tech",
      "keywords": ["startup", "venture capital", "unicorn"],
      "category": "startup",
      "last_published": null
    }
  ]
}

scripts/download_cover.py

Identico alla versione locale: scarica l'immagine da Unsplash sulla macchina locale.

#!/usr/bin/env python3
import sys, requests, os

query   = sys.argv[1]
outfile = sys.argv[2]
api_key = os.environ['UNSPLASH_ACCESS_KEY']

r = requests.get(
    'https://api.unsplash.com/photos/random',
    params={'query': query, 'orientation': 'landscape', 'content_filter': 'high'},
    headers={'Authorization': f'Client-ID {api_key}'}
)
r.raise_for_status()
data = r.json()

img_data = requests.get(data['urls']['regular']).content
with open(outfile, 'wb') as f:
    f.write(img_data)

with open('/tmp/cover_meta.txt', 'w') as f:
    f.write(f"Photo by {data['user']['name']} on Unsplash")

print(f"Immagine scaricata: {outfile}")

scripts/optimize_image.sh

Identico alla versione locale: ottimizza e ritaglia l'immagine sulla macchina locale con ImageMagick.

#!/bin/bash
INPUT=$1
OUTPUT=$2

# Resize a 1200x630 (dimensione Open Graph ottimale) e comprimi
convert "$INPUT" \
  -resize 1200x630^ \
  -gravity Center \
  -extent 1200x630 \
  -quality 85 \
  -strip \
  "$OUTPUT"

echo "Ottimizzazione completata: $(du -h "$OUTPUT" | cut -f1)"

scripts/upload_media_remote.sh

Questo script è la principale differenza rispetto alla versione locale.
Trasferisce l'immagine ottimizzata sul server remoto via scp, poi esegue wp media import tramite ssh.

#!/bin/bash
# ============================================================
# upload_media_remote.sh
# Trasferisce l'immagine sul server remoto e la importa
# in WordPress con WP-CLI remoto via SSH a chiave pubblica.
# ============================================================

IMAGE_PATH=$1

# --- Parametri SSH da variabili d'ambiente ---
SSH_HOST="${WP_SSH_HOST}"
SSH_USER="${WP_SSH_USER}"
SSH_KEY="${WP_SSH_KEY}"
SSH_PORT="${WP_SSH_PORT:-22}"
REMOTE_PATH="${WP_REMOTE_PATH:-/var/www/html/wordpress}"
REMOTE_TMP="${WP_REMOTE_TMP:-/tmp}"

# Opzioni SSH comuni (chiave pubblica, no password, no prompt)
SSH_OPTS="-i $SSH_KEY -p $SSH_PORT \
          -o StrictHostKeyChecking=no \
          -o BatchMode=yes \
          -o ConnectTimeout=15 \
          -o PasswordAuthentication=no"

# --- Validazione variabili ---
if [ -z "$SSH_HOST" ] || [ -z "$SSH_USER" ] || [ -z "$SSH_KEY" ]; then
  echo "ERRORE: WP_SSH_HOST, WP_SSH_USER e WP_SSH_KEY sono obbligatori." >&2
  exit 1
fi

if [ ! -f "$SSH_KEY" ]; then
  echo "ERRORE: chiave SSH non trovata in $SSH_KEY" >&2
  exit 1
fi

if [ ! -f "$IMAGE_PATH" ]; then
  echo "ERRORE: immagine non trovata in $IMAGE_PATH" >&2
  exit 1
fi

REMOTE_FILENAME="wp_cover_$(date +%s).jpg"
REMOTE_FILE_PATH="$REMOTE_TMP/$REMOTE_FILENAME"

# --- Trasferimento immagine via scp ---
echo "Trasferimento immagine su $SSH_USER@$SSH_HOST:$REMOTE_FILE_PATH ..."
scp $SSH_OPTS "$IMAGE_PATH" "$SSH_USER@$SSH_HOST:$REMOTE_FILE_PATH"

if [ $? -ne 0 ]; then
  echo "ERRORE: scp fallito durante il trasferimento dell'immagine." >&2
  exit 1
fi

echo "Immagine trasferita con successo."

# --- Importazione media con WP-CLI remoto ---
echo "Importazione media in WordPress via WP-CLI remoto..."
MEDIA_ID=$(ssh $SSH_OPTS "$SSH_USER@$SSH_HOST" \
  "wp media import '$REMOTE_FILE_PATH' \
   --path='$REMOTE_PATH' \
   --porcelain 2>/dev/null")

if [ -z "$MEDIA_ID" ]; then
  echo "ERRORE: wp media import non ha restituito un ID." >&2
  # Cleanup file remoto anche in caso di errore
  ssh $SSH_OPTS "$SSH_USER@$SSH_HOST" "rm -f '$REMOTE_FILE_PATH'" 2>/dev/null
  exit 1
fi

# --- Cleanup file temporaneo remoto ---
ssh $SSH_OPTS "$SSH_USER@$SSH_HOST" "rm -f '$REMOTE_FILE_PATH'" 2>/dev/null

echo "$MEDIA_ID" > /tmp/wp_media_id.txt
echo "Media importato su WordPress con ID: $MEDIA_ID"

scripts/publish_wp_remote.sh

Esegue tutti i comandi wp sul server remoto tramite SSH. Nessuna chiamata WP-CLI locale.

#!/bin/bash
# ============================================================
# publish_wp_remote.sh
# Crea il post WordPress come draft via WP-CLI remoto (SSH).
# ============================================================

# --- Parametri SSH da variabili d'ambiente ---
SSH_HOST="${WP_SSH_HOST}"
SSH_USER="${WP_SSH_USER}"
SSH_KEY="${WP_SSH_KEY}"
SSH_PORT="${WP_SSH_PORT:-22}"
REMOTE_PATH="${WP_REMOTE_PATH:-/var/www/html/wordpress}"
AUTHOR_ID="${WP_AUTHOR_ID:-1}"

SSH_OPTS="-i $SSH_KEY -p $SSH_PORT \
          -o StrictHostKeyChecking=no \
          -o BatchMode=yes \
          -o ConnectTimeout=15 \
          -o PasswordAuthentication=no"

# --- Leggi dati articolo ---
TITLE=$(python3 -c "import json; d=json.load(open('/tmp/wp_article.json')); print(d['title'])")
CONTENT=$(python3 -c "import json; d=json.load(open('/tmp/wp_article.json')); print(d['content'])")
EXCERPT=$(python3 -c "import json; d=json.load(open('/tmp/wp_article.json')); print(d['excerpt'])")
TAGS=$(python3 -c "import json; d=json.load(open('/tmp/wp_article.json')); print(','.join(d['tags']))")
META_DESC=$(python3 -c "import json; d=json.load(open('/tmp/wp_article.json')); print(d['meta_desc'])")
KEYWORD=$(python3 -c "import json; d=json.load(open('/tmp/wp_article.json')); print(d['keyword'])")
MEDIA_ID=$(cat /tmp/wp_media_id.txt)

# --- Trasferisci il JSON dell'articolo sul server remoto (necessario per content lungo) ---
REMOTE_ARTICLE_JSON="/tmp/wp_article_remote_$(date +%s).json"
scp $SSH_OPTS /tmp/wp_article.json "$SSH_USER@$SSH_HOST:$REMOTE_ARTICLE_JSON"

# --- Crea il post come draft (WP-CLI remoto) ---
echo "Creazione post come draft su WordPress remoto..."
POST_ID=$(ssh $SSH_OPTS "$SSH_USER@$SSH_HOST" bash <<ENDSSH
  TITLE=\$(python3 -c "import json; d=json.load(open('$REMOTE_ARTICLE_JSON')); print(d['title'])")
  CONTENT=\$(python3 -c "import json; d=json.load(open('$REMOTE_ARTICLE_JSON')); print(d['content'])")
  EXCERPT=\$(python3 -c "import json; d=json.load(open('$REMOTE_ARTICLE_JSON')); print(d['excerpt'])")

  wp post create \
    --post_title="\$TITLE" \
    --post_content="\$CONTENT" \
    --post_excerpt="\$EXCERPT" \
    --post_status=draft \
    --post_author=$AUTHOR_ID \
    --post_type=post \
    --path="$REMOTE_PATH" \
    --porcelain 2>/dev/null
ENDSSH
)

if [ -z "$POST_ID" ]; then
  echo "ERRORE: wp post create non ha restituito un ID." >&2
  ssh $SSH_OPTS "$SSH_USER@$SSH_HOST" "rm -f '$REMOTE_ARTICLE_JSON'" 2>/dev/null
  exit 1
fi

echo "Post draft creato con ID: $POST_ID"

# --- Imposta immagine di copertina ---
echo "Impostazione immagine di copertina..."
ssh $SSH_OPTS "$SSH_USER@$SSH_HOST" \
  "wp post meta update $POST_ID _thumbnail_id $MEDIA_ID \
   --path='$REMOTE_PATH'" 2>/dev/null

# --- Aggiungi tag ---
echo "Aggiunta tag..."
ssh $SSH_OPTS "$SSH_USER@$SSH_HOST" \
  "wp post term add $POST_ID post_tag '$TAGS' \
   --path='$REMOTE_PATH'" 2>/dev/null

# --- Meta SEO Yoast ---
echo "Aggiornamento meta SEO Yoast..."
ssh $SSH_OPTS "$SSH_USER@$SSH_HOST" \
  "wp post meta update $POST_ID _yoast_wpseo_metadesc '$META_DESC' \
   --path='$REMOTE_PATH'" 2>/dev/null

ssh $SSH_OPTS "$SSH_USER@$SSH_HOST" \
  "wp post meta update $POST_ID _yoast_wpseo_focuskw '$KEYWORD' \
   --path='$REMOTE_PATH'" 2>/dev/null

# --- Cleanup file temporanei remoti ---
ssh $SSH_OPTS "$SSH_USER@$SSH_HOST" "rm -f '$REMOTE_ARTICLE_JSON'" 2>/dev/null

echo "$POST_ID" > /tmp/wp_post_id.txt
echo "Post WordPress creato come draft con ID: $POST_ID"

Configurazione in ~/.openclaw/openclaw.json

Iniezione chiave pubblica SSH nella skill

"skills": {
  "entries": {
    "wp-remote-publisher": {
      "env": {
        "WP_SSH_HOST":         "203.0.113.10",
        "WP_SSH_USER":         "deploy",
        "WP_SSH_KEY":          "/home/user/.ssh/id_ed25519_wp",
        "WP_SSH_PORT":         "22",
        "WP_REMOTE_PATH":      "/var/www/html/wordpress",
        "WP_REMOTE_TMP":       "/tmp",
        "WP_AUTHOR_ID":        "1",
        "UNSPLASH_ACCESS_KEY": "la-tua-access-key-unsplash"
      }
    }
  }
}

Cron jobs per pubblicazione automatica

"cron": {
  "jobs": [
    {
      "id": "wp-morning-news",
      "schedule": "0 10 * * 1-5",
      "prompt": "Esegui la skill wp-remote-publisher. Scegli il topic dalla rotazione.",
      "channel": "telegram"
    },
    {
      "id": "wp-afternoon-news",
      "schedule": "0 16 * * 1-5",
      "prompt": "Esegui la skill wp-remote-publisher per il pomeriggio.",
      "channel": "telegram"
    }
  ]
}

Setup della chiave SSH (una-tantum)

Prima di usare la skill, configura l'autenticazione a chiave pubblica sul server remoto:

# 1. Genera una coppia di chiavi dedicata (raccomandato: ed25519)
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_wp -C "openclaw-wp-publisher" -N ""

# 2. Copia la chiave pubblica sul server remoto
ssh-copy-id -i ~/.ssh/id_ed25519_wp.pub -p 22 deploy@203.0.113.10

# 3. Verifica la connessione automatica (nessuna password richiesta)
ssh -i ~/.ssh/id_ed25519_wp -o BatchMode=yes deploy@203.0.113.10 "wp --info"

# 4. (Opzionale) Limita ulteriormente la chiave in ~/.ssh/authorized_keys sul server
# Aggiungi prima della chiave: command="wp --allow-root",no-port-forwarding,no-X11-forwarding

💡 Consiglio sicurezza — Usa un utente SSH dedicato (deploy o wpcli) con permessi minimi sul server. Non usare root. Se WP-CLI richiede permessi su /var/www, aggiungi l'utente al gruppo www-data.

Requisiti sul server remoto

Requisiti sulla macchina locale (OpenClaw)

✅ In sintesi rispetto alla versione locale: WP-CLI non è più richiesto sulla macchina con OpenClaw. Tutti i comandi wp vengono eseguiti via ssh -i chiave ... sul server remoto. Le immagini vengono elaborate localmente e trasferite con scp. La connessione non richiede mai password grazie all'autenticazione a chiave pubblica.

Esempio di articolo generato con stile giornalistico:

Titolo: OpenAI apre i modelli o1 agli sviluppatori: tariffe ridotte del 40% e nuovi limiti di contesto

Lede: OpenAI ha reso disponibili via API i modelli della famiglia o1, finora riservati agli utenti ChatGPT Plus, con una riduzione dei costi del 40% rispetto all'anteprima pubblica. La mossa, annunciata il 20 febbraio, amplia la finestra di contesto a un milione di token per i tier enterprise e segnala un cambio di strategia nella monetizzazione dell'AI per sviluppatori.

Notare: nessun "nell'era digitale", nessun "è importante notare". Il lede risponde subito alle 5W con dati numerici precisi e fonte esplicita. Tono da agenzia stampa, non da blog.

8. Riferimento Comandi CLI {#cli}

9. Troubleshooting

Il Gateway non si avvia
Verifica che Node.js sia ≥22: node --version. Controlla i log con openclaw logs. Assicurati che la porta 18789 non sia occupata: lsof -i :18789.

Le skill non vengono caricate
Esegui openclaw doctor per rilevare binari mancanti o env non configurate. Controlla che SKILL.md abbia frontmatter YAML valido. Verifica che requires.bins siano nel PATH dell'utente che esegue OpenClaw.

WP-CLI restituisce errore di permessi
Usa l'utente web corretto (es. www-data) o il flag --allow-root solo in ambienti controllati. Verifica il path: wp --path=/var/www/html/wordpress post list.

Consumo eccessivo di token
Imposta spending cap sul dashboard del provider. Usa modelli economici (Gemini Flash) per skill semplici. Disabilita il heartbeat in sviluppo. Controlla che non ci siano loop nei cron job.

L'agente non trova le skill nel prompt
OpenClaw fa uno snapshot delle skill all'avvio della sessione. Dopo aver aggiunto una skill, riavvia la sessione o abilita skills.watcher per il hot-reload automatico.

Risorse Utili

• GitHub — github.com/openclaw/openclaw
• Documentazione — docs.openclaw.ai
• ClawHub — clawhub.com
• WP-CLI — wp-cli.org
• Unsplash API — unsplash.com/developers
• AgentSkills spec — agentskills.io

Hai domande o vuoi condividere la tua skill? Lascia un commento qui sotto o apri una issue su GitHub.

1. /BRIEFLY o /CONCISE: Chiede risposte brevi, focalizzate, senza prefazioni o spiegazioni superflue.
2. /ELI5 (Explain Like I'm 5): Spiegare un concetto complesso in termini semplici e analogie, come a un bambino.
3. /TL;DR (Too Long; Didn't Read): Chiede un riassunto estremamente sintetico di un testo lungo o di un concetto.
4. /STEP-BY-STEP: Obbliga il modello a decomporre un ragionamento o una procedura in passi numerati e sequenziali, riducendo errori.
5. /ROLE: Fa impersonare al modello un esperto specifico (es. "/ROLE: Sei un avvocato penalista esperto...").
6. /FORMAT: Specifica il formato di output desiderato (JSON, HTML, tabella Markdown, elenco puntato, ecc.).
7. /FIRST-PRINCIPLES: Invita a ragionare dalle basi fondamentali di un argomento, sfidando presupposti.
8. /CREATIVE: Chiede un approccio originale, fuori dagli schemi, immaginativo.
9. /CRITICAL: Richiede un'analisi critica, evidenziando punti di forza, debolezza, pregiudizi o limitazioni.
10. /ANTI-EXAMPLE: Chiede esempi di come NON fare o pensare a qualcosa, molto utile per delimitare confini.
11. /ANALOGY: Richiede di spiegare un concetto attraverso un'analogia concreta e familiare.
12. /SOCRATIC: Fa porre al modello domande guida per aiutare l'utente a arrivare da solo alla conclusione.
13. /PROMPT-EXPERT: Chiede al modello di analizzare e suggerire miglioramenti al prompt stesso che gli hai inviato.
14. /DON'T-EXPLAIN: Istruisce a dare solo la risposta (es. solo il codice, solo la parola, solo il numero) senza commenti.
15. /VERIFY: Chiede di controllare la correttezza fattuale o logica di una data affermazione o risposta precedente.
16. /COMPARE: Chiede un confronto strutturato tra due o più elementi, evidenziando somiglianze e differenze.
17. /FOMO (Fear Of Missing Out): "Cosa potrei aver trascurato o dimenticato di considerare su questo tema?"
18. /BRAINSTORM: Richiede una sessione di brainstorming libera, generando una lista di idee senza filtro iniziale.
19. /REVERSE: "Rovescia il problema" o pensa al contrario per trovare prospettive inedite.
20. /TEACH: "Insegna questo argomento come se dovessi preparare una lezione completa per principianti."
21. /ITERATE: Chiede versioni successive e migliorate di un testo, codice o idea basate sul feedback.
22. /PROS-CONS: Analisi classica di vantaggi e svantaggi, spesso in una tabella.
23. /EVIDENCE-BASED: Richiede che ogni affermazione sia supportata da dati, studi o riferimenti noti.
24. /SIMPLIFY: Riduce la complessità linguistica o concettuale di un testo esistente.
25. /EXPAND: Il contrario di /SIMPLIFY. Aggiunge profondità, dettagli, esempi e contesto.
26. /ACTIONABLE: Chiede che i consigli o i passi forniti siano concretamente applicabili e pratici.
27. /KEY-TAKEAWAYS: Estrae i punti principali, le lezioni o le conclusioni più importanti da un discorso.
28. /FRAMEWORK: Chiede di fornire una struttura (una checklist, un modello mentale) per affrontare un tipo di problema.
29. /TRANSLATE-TO-TERMS: "Traduci questo concetto tecnico in linguaggio comprensibile per un [manager, cliente, non esperto]".
30. /ASSUMPTIONS: Chiede di esplicitare tutti i presupposti sottostanti a un ragionamento o a una domanda.
31. /SCENARIO: "Analizza questa situazione ipotetica specifica e le sue possibili conseguenze."
32. /PREDICT: Basandosi su dati e tendenze, propone previsioni su sviluppi futuri.
33. /HISTORICAL: Analizza la questione da una prospettiva storica o ne traccia l'evoluzione.
34. /DEBATE: Presenta entrambi i lati di un argomento controverso in modo equo e persuasivo.
35. /CHECKLIST: Crea una lista di controllo per assicurarsi di aver completato tutti i passi necessari per un task.
36. /TROUBLESHOOT: Guida nella diagnosi e risoluzione sistematica di un problema (tecnico, di processo, ecc.).
37. /ALTERNATIVES: Chiede di esplorare soluzioni, metodi o punti di vista alternativi a quello più ovvio.
38. /METAPHOR: Simile ad /ANALOGY, ma spesso più poetica o evocativa per concetti astratti.
39. /LIMITATIONS: "Quali sono i limiti intrinseci di questa teoria/soluzione/approccio?"
40. /PRIORITIZE: Aiuta a ordinare elementi (task, idee, rischi) per importanza, urgenza o impatto.
41. /GENERALIZE: Cerca di estrarre una regola, principio o pattern generale da casi specifici.
42. /APPLY: "Applica questo framework o teoria al seguente caso concreto che ti descrivo."
43. /TIMELINE: Organizza eventi, passi o fasi in una sequenza temporale chiara.
44. /PARODY: Scrive o analizza in uno stile umoristico, imitando un genere, una persona o un tono specifico.
45. /SERIALIZE: Divide una risposta molto lunga in parti numerate e digeribili (es. "1/5, 2/5...").
46. /VISUAL: Chiede di descrivere qualcosa in modo così dettagliato da permettere di visualizzarlo o disegnarlo.
47. /CROSS-DISCIPLINARY: Approccia un problema con gli strumenti e le prospettive di diverse discipline.
48. /META: "Pensa a come stai pensando a questo problema." Analizza il processo di ragionamento stesso.
49. /YES-AND: Tecnica dell'improvvisazione: accetta la premessa e costruisci sopra, per espandere creativamente.
50. /RED-TEAM: Incarica il modello di fare il "avvocato del diavolo", attaccando attivamente un'idea per testarne la robustezza.

Come Usarle al Meglio

• Combinazione: Puoi combinarne due o tre per un controllo fine (es. /ROLE: Scienziato dei dati /FORMAT: JSON /BRIEFLY).
• Posizione: Sono più efficaci all'inizio del prompt, ma possono essere usate anche alla fine per correggere il tiro.
• Esplicitazione: Per i modelli più recenti, spesso funziona anche scrivere semplicemente le istruzioni in modo chiaro (es. "Sii conciso. Spiega come a un principiante. Fornisci un esempio."). Le barre (/) sono una convenzione utile per marcarle.

Queste scorciatoie sono moltiplicatori di forza per il tuo pensiero. Usale per guidare l'AI a collaborare con te al livello di precisione e profondità che desideri.