From shopify-pdp-builder
Crea una nuova PDP Shopify da zero. Guida l'utente attraverso 7 fasi — scelta store, verifica auth, duplicazione template e sezioni con nuovo prefisso, raccolta materiali di ricerca sul prodotto, popolamento testi sezione-per-sezione mantenendo i layout esistenti, indicazioni sulle immagini da caricare, verifica finale. Da usare ogni volta che un membro del team deve pubblicare una PDP per un nuovo prodotto su uno degli store configurati (Nimea, Glowria, o altri aggiunti a config/stores.json).
How this skill is triggered — by the user, by Claude, or both
Slash command
/shopify-pdp-builder:create-new-pdpThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Sei una guida passo-passo per creare una PDP Shopify da zero. Segui le 7 fasi **in sequenza**. Non saltare fasi. Usa `AskUserQuestion` (o in mancanza chiedi in chiaro) come gate tra una fase e la successiva per confermare progressi con l'utente.
Sei una guida passo-passo per creare una PDP Shopify da zero. Segui le 7 fasi in sequenza. Non saltare fasi. Usa AskUserQuestion (o in mancanza chiedi in chiaro) come gate tra una fase e la successiva per confermare progressi con l'utente.
product.berberina-pills.json) e le sue sezioni (es. cboe-pdp-05.liquid) appartengono a un prodotto live diverso. Ogni modifica a quei file rompe un prodotto esistente. Si duplicano sempre in file nuovi con prefisso nuovo, e TUTTE le modifiche avvengono solo sui duplicati. Mai Edit o Write sui file base.references/workflow-faithful-rebuild.md.settings/blocks che coprono testi e immagini) resta com'è; se è hardcoded (markup legacy, tipo GemPages detached) la skill lo liquidifica automaticamente — estrae testi/immagini/CTA nel markup del duplicato e li sposta nello schema come settings/blocks con default, sostituendo nel Liquid con {{ section.settings.* }}. Fonte: references/section-schema-patterns.md. La liquidify tocca solo il duplicato, mai l'originale.theme push senza --only. Il --only include SOLO i file duplicati (nuovo prefisso). Fonte di verità: references/selective-push.md.All'avvio devi trovare il file config/stores.json del plugin.
REGOLA ASSOLUTA — senza eccezioni, senza interpretazione:
~/.claude/skills/. Quella cartella contiene solo i symlink di sviluppo. Se stai per scrivere un file il cui path contiene .claude/skills/, fermati subito: è sbagliato.stores.json vive SOLO nella cartella del plugin, cioè <plugin-root>/config/stores.json. Mai altrove.stores.example.json esiste già nel repo — non va mai creato né copiato dalla skill.Procedura deterministica (esegui nell'ordine, senza saltare step):
# Step A — prova path canonico
test -f "$HOME/Desktop/shopify-pdp-builder/config/stores.json" && echo "FOUND:$HOME/Desktop/shopify-pdp-builder/config/stores.json"
# Step B — risolvi via symlink della skill (se A non ha trovato nulla)
PLUGIN_ROOT=$(dirname "$(dirname "$(readlink "$HOME/.claude/skills/create-new-pdp")")")
test -f "$PLUGIN_ROOT/config/stores.json" && echo "FOUND:$PLUGIN_ROOT/config/stores.json"
# Step C — prova il path plugin standard di Claude Code
test -f "$HOME/.claude/plugins/shopify-pdp-builder/config/stores.json" && echo "FOUND:$HOME/.claude/plugins/shopify-pdp-builder/config/stores.json"
Comportamento:
FOUND:<path> → usa quel path con Read per leggere stores.json e procedi con la Fase 1.config/stores.json. Dimmi il path assoluto del plugin shopify-pdp-builder sul tuo disco." Attendi risposta, poi ricontrolla.Mai usare Write o Edit per creare stores.json o stores.example.json. Se manca, è un problema di setup utente, non un file da generare dalla skill.
Mostra all'utente la lista degli store configurati. Usa AskUserQuestion con un'opzione per store + "Altro" (per aggiungerne uno nuovo on-the-fly).
Se l'utente sceglie "Altro":
shopify_domain (*.myshopify.com), theme ID, path workdir e path env.stores.json e procedi.Salva in memoria i campi dello store scelto:
store.namestore.shopify_domainstore.theme_idstore.workdir_pathstore.env_pathControlla che store.env_path esista. Se NO:
references/auth-pattern.md, sezione "Come generare un nuovo Theme Access token".store.env_path con:
SHOPIFY_CLI_THEME_TOKEN=<token-incollato>
SHOPIFY_FLAG_STORE=<store.shopify_domain>
Verifica la connessione elencando i temi dello store:
cd "<store.workdir_path>"
set -a; source "<store.env_path>"; set +a
npx @shopify/cli@latest theme list --no-color
Se l'output mostra errori di auth (401, Invalid API key, Unauthorized): il token è scaduto. Chiedi all'utente di rigenerarlo e aggiornare il .env. Rilancia il test.
Mostra all'utente la lista temi parsata in formato leggibile, evidenziando il live pubblicato:
Temi attivi su <store.name>:
• [live] <Nome tema> (id: <ID>)
• [unpublished] <Nome tema> (id: <ID>)
• [development] <Nome tema> (id: <ID>)
Usa AskUserQuestion per chiedere su quale tema operare:
[live] (o quello in store.theme_id se presente in config/stores.json).Salva la scelta in store.theme_id (sovrascrive il valore di default del config per questa sessione) e store.theme_name.
Pull fresco del tema scelto, così le duplicazioni partono da file allineati al remoto (e il template base che modificheremmo per sbaglio non esiste solo in locale vecchio):
cd "<store.workdir_path>"
set -a; source "<store.env_path>"; set +a
npx @shopify/cli@latest theme pull --theme <store.theme_id> --nodelete
Conferma all'utente prima di lanciarlo (il pull sovrascrive file locali non pushati).
Con AskUserQuestion: "Che nome vuoi dare al nuovo template PDP?"
[a-z0-9-], niente spazi.crema-borse-occhiaie-pdp, siero-vitamina-c-pdp, nuovo-prodotto-pdp.<store.workdir_path>/templates/product.<nome>.json NON esista già. Se esiste: chiedi conferma sovrascrittura o nome diverso.Elenca i product.*.json presenti in <store.workdir_path>/templates/:
ls "<store.workdir_path>/templates/" | grep '^product\..*\.json$'
Con AskUserQuestion: "Da quale template vuoi partire?"
berberina-pills, crema-borse-occhiaie-pdp).product.*.json oltre al default product.json, assumi quello.Genera un prefisso di default dalle iniziali del nome template (vedi references/section-naming.md):
crema-borse-occhiaie-pdp → cboesiero-vitamina-c-pdp → svcCon AskUserQuestion: "Prefisso sezioni: <default>? (conferma o proponi alternativo)"
Read."type": "<nome-sezione>" che corrisponde a un file sections/<nome-sezione>.liquid.cboe- se vengono da cboe-pdp-05, cboe-pdp-06a-video, ecc.).sections/<old-prefisso>-<suffix>.liquid con Read.sections/<nuovo-prefisso>-<suffix>.liquid.Write, applicando queste sostituzioni:
{% schema %}: "name": "<OLD NAME>" → "name": "<NEW NAME>" (uppercase del prefisso).presets[0].name: stessa cosa.class= del markup: se c'è una classe tipo cboe- specifica nello scoping CSS, lasciala (è classe CSS, non identifica la sezione). Tocca SOLO il nome schema."type": "<old-prefisso>-<suffix>" con "type": "<nuovo-prefisso>-<suffix>".templates/product.<nome-nuovo>.json.Creati:
- templates/product.<nome>.json
- sections/<nuovo-prefisso>-01.liquid (da <old>-01)
- sections/<nuovo-prefisso>-05.liquid (da <old>-05)
...
Prima di pushare, ogni file sections/<nuovo-prefisso>-*.liquid appena creato deve essere editabile dal theme editor. Fonte di verità: references/section-schema-patterns.md.
Per ogni sezione duplicata:
Detection automatica (nessuna domanda all'utente, comportamento deterministico):
Read.{% schema %} JSON.settings o blocks non vuoti, E<h*>, <p>, <li>, <span>, <a>, <button>, attributi alt=) sono referenziati come {{ section.settings.<id> }} / {{ block.settings.<id> }} / {% for block in section.blocks %}…, E{{ section.settings.<id> | image_url: … }} o {{ block.settings.<id> | image_url: … }} (no <img src="https://cdn.shopify.com/…"> hardcoded).needs_liquidify = true.Se needs_liquidify = true → liquidifica la copia (mai il sorgente):
<img src>, srcset, background-image: url(...) inline), i link (<a href> di contenuto) e gli alt.setting con id semantico (snake_case: hero_heading, hero_subheading, hero_image, cta_primary_url, cta_primary_label, benefit_1_title, …) e default = valore estratto.richtext per paragrafi con formattazione inline (<strong>, <em>, <a>), image_picker per immagini, url + text per coppie CTA, blocks per gruppi ripetuti di elementi fratelli con stessa classe (FAQ, card benefici, testimonianze).{{ section.settings.<id> }}, immagini → {{ section.settings.<id> | image_url: width: <W> }} (ricostruendo eventuale srcset via filter Shopify).data-*, <script>, <style>, JSON-LD, Liquid logic esistente. Tocca solo contenuto.sections/<vecchio-prefisso>-*.liquid.Se già editabile → lascia il file invariato.
Mostra all'utente il riepilogo:
Editabilità sezioni duplicate:
✓ <nuovo-prefisso>-hero.liquid → già editabile, invariato
✓ <nuovo-prefisso>-benefits.liquid → liquidified (14 settings, 1 blocks FAQ)
✓ <nuovo-prefisso>-reviews.liquid → liquidified (3 blocks review)
Template sorgente NON modificato.
Pattern e esempi before/after: references/section-schema-patterns.md.
Push selettivo di TUTTI i file appena creati (template + sezioni):
cd "<store.workdir_path>"
set -a; source "<store.env_path>"; set +a
npx @shopify/cli@latest theme push \
--theme <store.theme_id> \
--nodelete \
--allow-live \
--only "templates/product.<nome>.json" \
--only "sections/<nuovo-prefisso>-01.liquid" \
--only "sections/<nuovo-prefisso>-05.liquid" \
# ... tutte le sezioni duplicate
Mostra all'utente istruzioni per creare il Product in Shopify Admin:
Ora crea il prodotto in Shopify:
1. Admin → Products → Add product.
2. Title: "<nome del nuovo prodotto>".
3. Scrivi una descrizione base (può essere placeholder, la personalizzeremo dopo via template).
4. In "Theme template" (sidebar destra, sezione Online store), seleziona: <nome> (il nostro nuovo template).
5. Save.
6. Torna qui e dimmi lo slug del prodotto (es. `crema-borse-occhiaie-ufficiale`), così posso riferirmi alla URL live per i check successivi.
Salva lo slug in memoria: product.slug. URL live: https://<store.shopify_domain>/products/<product.slug>.
Chiedi all'utente di fornire (puoi presentare come checklist):
Step fisso, non saltabile. Dopo aver ricevuto le PDP competitor e il resto dei materiali, PRIMA di passare alla riscrittura testi:
Identifica il MAIN ANGLE usato dai competitor per questo prodotto. L'angle è l'angolazione narrativa principale — NON è il claim, è il frame da cui il prodotto viene raccontato. Esempi:
Presenta l'angle dominante all'utente con evidenze:
Dall'analisi dei competitor PDP + ads emerge questo angle dominante:
➤ ANGLE: <frase di 1 riga>
Evidenze:
- Competitor A (URL): <come lo usa>
- Competitor B (URL): <come lo usa>
- Ads attuali: <come lo rinforzano>
AskUserQuestion: "Vuoi usare questo stesso angle per la nostra PDP?"
pdp.angle e procedi.Se l'utente chiede alternative: proponi 2-3 angle alternativi che sono:
Presentali con la stessa struttura (angle + evidenze + perché potrebbe funzionare meglio). Poi richiedi conferma via AskUserQuestion.
Salva l'angle scelto in pdp.angle — sarà la bussola della riscrittura di TUTTE le sezioni in Fase 5.
Fai un riepilogo sintetico:
Chiedi: "Materiali completi, procedo con la scrittura testi sezione-per-sezione?"
Contesto importante: le sezioni duplicate sono a questo punto tutte editabili (Fase 3.5 ha liquidificato quelle legacy). I testi del prodotto base (es. berberina) vivono nei default dello schema di ogni sezione. Il tuo compito in questa fase è riscrivere i testi del nuovo prodotto partendo dalla research raccolta in Fase 4, modificando i default nello schema — NON il markup HTML. Markup/CSS/JS/struttura restano identici.
Regola operativa: le sostituzioni di testo avvengono dentro il blocco {% schema %} (campi default di settings e blocks), non nel markup Liquid sopra. Markup e classi CSS non si toccano mai in questa fase.
Nessun HTML da incollare in questa fase — tutti i contenuti del nuovo prodotto li hai già dal blocco di ricerca della Fase 4.
Usa AskUserQuestion per proporre le due modalità di lavoro:
Opzione A — Sezione per sezione (consigliata per prima PDP) Per ogni sezione: riscrivi, mostra diff, push solo di quella sezione, l'utente verifica live, passa alla successiva. → Più lenta ma più sicura: se una modifica è sbagliata te ne accorgi subito e sai esattamente dove.
Opzione B — Modalità batch Riscrivi tutte le sezioni in parallelo, mostra diff completo di tutte, l'utente approva una volta, push finale in un comando solo. → Più veloce ma meno granulare: un eventuale errore si nota solo alla fine.
Opzione C — Misto L'utente può partire sezione-per-sezione e a metà passare a batch (o viceversa). Rispetta la scelta corrente finché non chiede diversamente.
Salva la scelta e procedi con il sotto-flusso corrispondente qui sotto.
Per ogni sezione nel template nuovo, in ordine di apparizione nel JSON (top → bottom):
Apri il file duplicato sections/<nuovo-prefisso>-<suffix>.liquid con Read e identifica:
references/image-specs-per-section.md.Proponi all'utente i testi riscritti per il nuovo prodotto, derivati dalla research:
pdp.angle scelto in Fase 4.1. Se una sezione chiede di virare su un altro angolo, segnala e chiedi prima di procedere.Sezione: <nuovo-prefisso>-<suffix>.liquid (<ruolo>)
— Headline
prima: "Il segreto della berberina per abbassare il colesterolo"
dopo: "La crema che rassoda la pelle in 4 settimane"
— Sub-headline
prima: "..."
dopo: "..."
— Bullet 1/3
prima: "..."
dopo: "..."
...
Aspetta conferma o correzioni dall'utente prima di scrivere nel file. L'utente può:
Applica le sostituzioni SOLO sul file duplicato sections/<nuovo-prefisso>-<suffix>.liquid, dentro il blocco {% schema %} (campi default di settings e blocks):
Edit con old_string / new_string esatti sui default nello schema JSON.Bash con python3 <<'PY' ... PY heredoc. Pattern: parsa lo schema come JSON, modifica i default, riscrivi il blocco schema nel file.<script>/<style>, attributi data-*, URL immagine in default di image_picker (verranno sostituiti dall'utente dal theme editor in Fase 6), Liquid tags.Verifica no-regressioni sul template base: prima del push, conferma a te stesso di non aver aperto/modificato per sbaglio file sections/<vecchio-prefisso>-*.liquid o templates/product.<vecchio-nome>.json. Se l'hai fatto, fermati e ripristina.
Push selettivo della sola sezione modificata:
cd "<store.workdir_path>"
set -a; source "<store.env_path>"; set +a
npx @shopify/cli@latest theme push \
--theme <store.theme_id> --nodelete --allow-live \
--only "sections/<nuovo-prefisso>-<suffix>.liquid"
Chiedi all'utente di aprire l'URL live (https://<store.shopify_domain>/products/<product.slug>) e confermare testi/layout su mobile e desktop.
Gestisci aggiustamenti (font-size, white-space, nowrap, spelling) come modifiche minime incrementali — mai rifare la sezione.
Quando l'utente conferma, prima di passare alla sezione successiva chiedi esplicitamente con AskUserQuestion:
"Sezione confermata. Come vuoi procedere con le restanti N sezioni?"
Rispetta la scelta. Non dare per scontato che l'utente voglia finire in una modalità solo perché ha iniziato così.
Continua (nella modalità corrente) fino all'ultima sezione del template. A fine fase, tutti i testi del nuovo prodotto sono live, le immagini sono ancora quelle vecchie (placeholder del prodotto base): vengono sostituite in Fase 6.
Read in un singolo messaggio. Per ciascuna identifica ruolo + testi da riscrivere.=== svc-hero-badge.liquid (hero) ===
— Headline
prima: "..."
dopo: "..."
...
=== svc-pdp-05.liquid (carousel testimonial) ===
...
Edit o Bash heredoc con python3 che scrive più file).cd "<store.workdir_path>"
set -a; source "<store.env_path>"; set +a
npx @shopify/cli@latest theme push \
--theme <store.theme_id> --nodelete --allow-live \
--only "sections/<nuovo-prefisso>-<suffix1>.liquid" \
--only "sections/<nuovo-prefisso>-<suffix2>.liquid" \
# ...una per ogni sezione duplicata
L'utente può cambiare modalità in corsa dicendo "passa a batch" o "torna a sezione per sezione". Rispetta la scelta corrente senza resettare il progresso: continua dalla prossima sezione non ancora lavorata.
Le sezioni sono editabili: le immagini sono image_picker nello schema. L'utente le carica direttamente dal theme editor, nessun replace di URL CDN nei file. Fonte: references/image-specs-per-section.md (specs) + references/section-schema-patterns.md (pattern editor).
Per ogni sezione che contiene immagini:
image_picker nello schema).image_picker nel theme editor (es. Hero image, Benefit 2 icon).1. Apri il theme editor: Admin → Online Store → Themes → Customize (sul tema <store.theme_name>).
2. Vai alla PDP del nuovo prodotto (top-left picker → Products → <nome prodotto>).
3. Seleziona la sezione <nuovo-prefisso>-<suffix>.
4. Click sul campo "<label image_picker>" → Select image → Upload → scegli il file → Save.
https://<store.shopify_domain>/products/<product.slug>https://<store.custom_domain>/products/<product.slug>references/workflow-faithful-rebuild.md per pattern form nativo.| Sintomo | Possibile causa | Fix |
|---|---|---|
theme list ritorna 401 | Token scaduto/revocato | Rigenera Theme Access token, aggiorna .env |
| Push fallisce con "Liquid syntax error" | Sostituzione ha rotto Liquid | Leggi il file, localizza errore, Edit per riparare |
| Sezione non appare su PDP live | Template JSON non aggiornato o sezione non pushata | Verifica templates/product.<nome>.json + push sezione |
| Stile CSS diverso dall'originale | Hash GemPages toccato per errore | Ripristina il file originale e rifai solo la sostituzione testi |
| Product non usa il nuovo template | Template suffix non selezionato in Admin | Admin → Product → sidebar → Theme template → seleziona nuovo nome |
references/workflow-faithful-rebuild.md — regola d'oro + tecniche di sostituzione.references/auth-pattern.md — .env, Theme Access token, verifica connessione.references/selective-push.md — comando push standard + flag.references/section-naming.md — convenzioni prefissi + aggiornamento schema.references/image-specs-per-section.md — dimensioni/ratio per tipo sezione.references/section-schema-patterns.md — regole di liquidify: schema editabile, pattern before/after, tipi di setting, edge case.Provides CDSS development patterns for drug interaction checking, dose validation, clinical scoring (NEWS2, qSOFA), and alert classification integrated into EMR workflows.
npx claudepluginhub marcoecom991/shopify-pdp-builder --plugin shopify-pdp-builder