Guida all'utilizzo

GEO Optimizer include tre script, ciascuno mirato a un aspetto diverso della visibilità nella ricerca AI. Questa guida illustra l'utilizzo pratico di ognuno.

geo_audit.py -- Audit del sito

Lo script di audit analizza l'URL di un sito web e produce un punteggio di conformità GEO da 0 a 100, suddiviso in cinque dimensioni.

Utilizzo base (output testuale)

cd ~/geo-optimizer-skill
./geo scripts/geo_audit.py --url https://example.com

Output JSON (integrazione CI/CD)

./geo scripts/geo_audit.py --url https://example.com --format json

Modalità verbose

Per il debug o un'analisi più approfondita, abilita l'output verbose per visualizzare i dati grezzi di ogni controllo:

./geo scripts/geo_audit.py --url https://example.com --verbose

Salvataggio su file

./geo scripts/geo_audit.py --url https://example.com --format json --output report.json

Esempio di output testuale

============================================================
  GEO AUDIT REPORT
  URL: https://example.com
============================================================

  ROBOTS.TXT                              18 / 20
  ------------------------------------------------
  [PASS] robots.txt found
  [PASS] OAI-SearchBot allowed
  [PASS] ClaudeBot allowed
  [PASS] PerplexityBot allowed
  [WARN] GPTBot not explicitly mentioned

  LLMS.TXT                                14 / 20
  ------------------------------------------------
  [PASS] /llms.txt found (1,247 words)
  [PASS] Contains H1 heading
  [PASS] Contains 4 sections
  [WARN] Only 2 external links (recommend 5+)

  JSON-LD SCHEMA                          20 / 25
  ------------------------------------------------
  [PASS] WebSite schema detected
  [PASS] FAQPage schema detected
  [FAIL] No WebApplication schema found

  META TAGS                               18 / 20
  ------------------------------------------------
  [PASS] Title tag present (58 chars)
  [PASS] Meta description present (147 chars)
  [PASS] Canonical URL set
  [WARN] Missing og:image tag

  CONTENT QUALITY                         12 / 15
  ------------------------------------------------
  [PASS] H1 heading present
  [PASS] Contains 8 statistical references
  [WARN] No external citation links found

  ============================================================
  TOTAL SCORE                             82 / 100
  BAND: Good
  ============================================================

  RECOMMENDATIONS:
  1. Add WebApplication JSON-LD schema
  2. Add external citation links to content
  3. Include og:image meta tag
  4. Explicitly allow GPTBot in robots.txt

Dettaglio del punteggio

Sezione	Punti max	Cosa verifica
robots.txt	20	Bot di citazione AI (15 pt) + bot generici (5 pt)
llms.txt	20	Presenza del file (10), intestazione H1 (3), sezioni (4), link (3)
JSON-LD Schema	25	WebSite (10), FAQPage (10), WebApplication (5)
Meta Tags	20	Title (5), description (8), canonical (3), Open Graph (4)
Qualità dei contenuti	15	H1 (4), statistiche/dati (6), link a citazioni esterne (5)

Fasce di punteggio:

Punteggio	Fascia	Significato
91--100	Eccellente	Completamente ottimizzato per la citazione AI
71--90	Buono	Solide fondamenta, lacune minori
41--70	Base	Elementi chiave presenti, lavoro significativo necessario
0--40	Critico	Infrastruttura principale mancante

generate_llms_txt.py -- Generatore LLMs.txt

Il file /llms.txt è un indice leggibile dalle macchine del tuo sito web, progettato per aiutare i crawler AI a comprendere la struttura del sito. Pensalo come una sitemap in formato leggibile, pensata specificamente per i modelli linguistici di grandi dimensioni.

Utilizzo base

./geo scripts/generate_llms_txt.py --base-url https://example.com

Questo rileva automaticamente la tua sitemap (controlla /robots.txt, poi /sitemap.xml, poi /sitemap-index.xml) e restituisce il contenuto del file llms.txt generato su stdout.

Salvataggio su file

./geo scripts/generate_llms_txt.py --base-url https://example.com --output llms.txt

Con informazioni personalizzate del sito

./geo scripts/generate_llms_txt.py \
  --base-url https://example.com \
  --site-name "Example Corp" \
  --description "Enterprise solutions for data analytics" \
  --output llms.txt

Recupero dei titoli delle pagine

Per impostazione predefinita, gli URL vengono elencati con il loro percorso come etichetta. Usa --fetch-titles per recuperare i titoli effettivi delle pagine tramite HTTP:

./geo scripts/generate_llms_txt.py \
  --base-url https://example.com \
  --fetch-titles \
  --output llms.txt

Nota sulle prestazioni

Il flag --fetch-titles effettua una richiesta HTTP per ogni URL nella tua sitemap. Per siti di grandi dimensioni, l'operazione potrebbe richiedere tempo. Usa --max-per-section per limitare gli URL per categoria.

Specificare la sitemap manualmente

Se il rilevamento automatico fallisce o vuoi puntare a una sitemap specifica:

./geo scripts/generate_llms_txt.py \
  --base-url https://example.com \
  --sitemap https://example.com/custom-sitemap.xml \
  --output llms.txt

Limitare gli URL per sezione

./geo scripts/generate_llms_txt.py \
  --base-url https://example.com \
  --max-per-section 10 \
  --output llms.txt

Tutti i flag

Flag	Obbligatorio	Default	Descrizione
`--base-url`	Sì	--	URL radice del sito web
`--output`	No	stdout	Percorso del file di output
`--sitemap`	No	auto-detect	URL della sitemap manuale
`--site-name`	No	--	Nome personalizzato per l'intestazione
`--description`	No	--	Descrizione del sito (mostrata come blockquote)
`--fetch-titles`	No	off	Recupera i titoli effettivi delle pagine via HTTP
`--max-per-section`	No	20	Numero massimo di URL per categoria

Come funziona

Scoperta della sitemap -- controlla /robots.txt per le direttive Sitemap:, poi prova i percorsi comuni
Estrazione degli URL -- analizza le sitemap XML, inclusi gli indici di sitemap (fino a 10 sotto-sitemap)
Filtraggio -- rimuove pagine di amministrazione, download di file, paginazione e altri URL non di contenuto
Categorizzazione -- raggruppa gli URL per pattern del percorso (Blog, Documentazione, Strumenti, ecc.)
Output -- genera markdown strutturato con elenchi di URL categorizzati

Esempio di output

# Example Corp

> Enterprise solutions for data analytics

## Tools
- [Data Explorer](https://example.com/tools/data-explorer)
- [Query Builder](https://example.com/tools/query-builder)

## Documentation
- [Getting Started](https://example.com/docs/getting-started)
- [API Reference](https://example.com/docs/api-reference)
- [Configuration](https://example.com/docs/configuration)

## Blog
- [Announcing v2.0](https://example.com/blog/announcing-v2)
- [Performance Tips](https://example.com/blog/performance-tips)

schema_injector.py -- Strumenti per schema JSON-LD

Questo script genera, valida, analizza e inietta dati strutturati JSON-LD nei file HTML. I dati strutturati aiutano i motori di ricerca AI a comprendere il tipo di contenuto, l'autore e il contesto.

Analizzare gli schema esistenti

Verifica quali schema JSON-LD contiene già un file HTML:

./geo scripts/schema_injector.py --file index.html --analyze

Con output completo dello schema:

./geo scripts/schema_injector.py --file index.html --analyze --verbose

Generare uno schema (stdout)

Genera uno schema JSON-LD senza modificare alcun file:

./geo scripts/schema_injector.py \
  --type website \
  --name "Example Corp" \
  --url https://example.com \
  --description "Enterprise data analytics platform"

Iniettare uno schema nell'HTML

Inietta uno schema direttamente nel <head> di un file HTML:

./geo scripts/schema_injector.py \
  --file index.html \
  --inject \
  --type website \
  --name "Example Corp" \
  --url https://example.com \
  --description "Enterprise data analytics platform"

Backup dei file

Per impostazione predefinita, l'iniettore crea un backup .bak del file originale. Usa --no-backup per saltare questo passaggio.

Tipi di schema supportati

Tipo	Schema	Caso d'uso
`website`	WebSite	Homepage, punto di ingresso principale del sito
`webapp`	WebApplication	Strumenti SaaS, utility web
`faq`	FAQPage	Sezioni FAQ, contenuti di domande e risposte
`article`	Article	Post del blog, articoli di notizie
`organization`	Organization	Informazioni sull'azienda
`breadcrumb`	BreadcrumbList	Gerarchia di navigazione

Schema FAQ con estrazione automatica

Estrai il contenuto FAQ direttamente dalle intestazioni e dai paragrafi HTML:

./geo scripts/schema_injector.py \
  --file faq.html \
  --inject \
  --type faq \
  --auto-extract

Oppure fornisci i dati FAQ da un file JSON:

./geo scripts/schema_injector.py \
  --file faq.html \
  --inject \
  --type faq \
  --faq-file questions.json

Il formato del file JSON:

[
  {
    "question": "What is GEO?",
    "answer": "Generative Engine Optimization is the practice of optimizing content for AI search engines."
  },
  {
    "question": "Does it work with ChatGPT?",
    "answer": "Yes, GEO techniques improve visibility across ChatGPT, Perplexity, Claude, and Gemini."
  }
]

Integrazione con Astro

Genera uno snippet compatibile con Astro per incorporare JSON-LD:

./geo scripts/schema_injector.py \
  --type website \
  --name "Example Corp" \
  --url https://example.com \
  --astro

Questo produce un blocco <script type="application/ld+json"> pronto da incollare nel <head> di un layout Astro:

---
// Nel tuo layout Astro
---
<html>
  <head>
    <script type="application/ld+json" set:html={JSON.stringify({
      "@context": "https://schema.org",
      "@type": "WebSite",
      "name": "Example Corp",
      "url": "https://example.com",
      "description": "Enterprise data analytics platform"
    })} />
  </head>
  <body>
    <slot />
  </body>
</html>

Tutti i flag

Flag	Descrizione
`--file`	File HTML da analizzare o modificare
`--analyze`	Analizza gli schema esistenti (sola lettura)
`--inject`	Inietta lo schema generato nel file
`--type`	Tipo di schema: `website`, `webapp`, `faq`, `article`, `organization`, `breadcrumb`
`--name`	Nome del sito o dell'applicazione
`--url`	URL del sito
`--description`	Testo descrittivo
`--author`	Nome dell'autore
`--logo-url`	URL dell'immagine del logo
`--faq-file`	File JSON con le voci FAQ
`--auto-extract`	Rileva automaticamente il contenuto FAQ dall'HTML
`--astro`	Output snippet compatibile con Astro
`--no-backup`	Salta la creazione del backup `.bak`
`--no-validate`	Salta la validazione dello schema prima dell'iniezione
`--verbose`	Mostra il JSON completo dello schema durante l'analisi

Prossimo: Configurazione -- configura i file di contesto AI per la tua piattaforma preferita.

geo_audit.py -- Audit del sito​

Utilizzo base (output testuale)​

Output JSON (integrazione CI/CD)​

Modalità verbose​

Salvataggio su file​

Esempio di output testuale​

Dettaglio del punteggio​

generate_llms_txt.py -- Generatore LLMs.txt​

Utilizzo base​

Salvataggio su file​

Con informazioni personalizzate del sito​

Recupero dei titoli delle pagine​

Specificare la sitemap manualmente​

Limitare gli URL per sezione​

Tutti i flag​

Come funziona​

Esempio di output​

schema_injector.py -- Strumenti per schema JSON-LD​

Analizzare gli schema esistenti​

Generare uno schema (stdout)​

Iniettare uno schema nell'HTML​

Tipi di schema supportati​

Schema FAQ con estrazione automatica​

Integrazione con Astro​

Tutti i flag​

geo_audit.py -- Audit del sito

Utilizzo base (output testuale)

Output JSON (integrazione CI/CD)

Modalità verbose

Salvataggio su file

Esempio di output testuale

Dettaglio del punteggio

generate_llms_txt.py -- Generatore LLMs.txt

Utilizzo base

Salvataggio su file

Con informazioni personalizzate del sito

Recupero dei titoli delle pagine

Specificare la sitemap manualmente

Limitare gli URL per sezione

Tutti i flag

Come funziona

Esempio di output

schema_injector.py -- Strumenti per schema JSON-LD

Analizzare gli schema esistenti

Generare uno schema (stdout)

Iniettare uno schema nell'HTML

Tipi di schema supportati

Schema FAQ con estrazione automatica

Integrazione con Astro

Tutti i flag