commit 6ac766172c332b918cc632682147355a7427cc09 Author: AgentePotente Date: Mon Mar 9 12:23:58 2026 +0100 Initial release: agency_v3_1-skills-suite v1.0 - 12 AgentSkills generate da agency_v3_1 framework - 17 references centralizzate - Script INSTALL.sh per installazione automatica - README.md con documentazione completa Skills incluse: - agency-orchestrator (coordinamento + QA) - agency-strategy (positioning, messaging) - agency-research (competitive intelligence) - agency-creative-director (direzione visiva) - agency-design-system (tokens, components) - agency-ux-copy (sitemap, copy) - agency-seo (SEO tecnico) - agency-social (social strategy) - agency-youtube (YouTube strategy) - agency-visual-generator (asset visuali) - agency-analytics (report KPI) - agency-publisher (publish gate-based) Generated by framework-translator v2.0 Approved by: MarcoB (2026-03-09) diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..8f5b98a --- /dev/null +++ b/.gitignore @@ -0,0 +1,16 @@ +# Logs +*.log + +# OS +.DS_Store +Thumbs.db + +# Editor +.vscode/ +.idea/ +*.swp +*.swo + +# Node (se presente) +node_modules/ +package-lock.json diff --git a/INSTALL.sh b/INSTALL.sh new file mode 100755 index 0000000..6843cff --- /dev/null +++ b/INSTALL.sh @@ -0,0 +1,45 @@ +#!/bin/bash +# Installazione agency_v3_1-skills + +set -e + +SOURCE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +TARGET="$HOME/.openclaw/skills/agency_v3_1-skills" + +echo "🚀 Installing agency_v3_1-skills..." +echo "" + +# Rimuovi installazione precedente se esiste +if [ -d "$TARGET" ]; then + echo "⚠️ Rimozione installazione precedente..." + rm -rf "$TARGET" +fi + +# Crea directory target +mkdir -p "$(dirname "$TARGET")" + +# Copia skills +echo "📦 Copia skills in $TARGET..." +cp -r "$SOURCE" "$TARGET" + +# Verifica symlink +echo "🔗 Verifica symlink..." +for skill_dir in "$TARGET"/*/; do + if [ -d "$skill_dir" ] && [ "$skill_dir" != "$TARGET/references/" ]; then + if [ ! -L "$skill_dir/references" ]; then + echo " Fix symlink: $skill_dir" + rm -rf "$skill_dir/references" + ln -s ../references "$skill_dir/references" + fi + fi +done + +echo "" +echo "✅ Installation complete!" +echo "" +echo "Skills installate in: $TARGET" +echo "" +echo "Skills disponibili:" +ls -1 "$TARGET" | grep -v references | sed 's/^/ - /' +echo "" +echo "Per usare una skill, riferisciti a lei come 'agency_v3_1-skills/'" diff --git a/README.md b/README.md new file mode 100644 index 0000000..9175203 --- /dev/null +++ b/README.md @@ -0,0 +1,151 @@ +# agency_v3_1-skills + +Suite di AgentSkills per Agency AI OS v3.1 — trasformate da framework multi-agente a skills AgentSkills-compatibili. + +## Panoramica + +- **Skills:** 12 +- **References:** 17 +- **Lingua:** English (con note in italiano) +- **Dominio:** Digital Agency / Content Production / Multi-Agent System + +## Installazione + +### Metodo 1: Script Automatico + +```bash +cd /home/noe/.openclaw/workspace/agency_v3_1/test/agency_v3_1_v1/agency_v3_1-skills-suite +./INSTALL.sh +``` + +### Metodo 2: Copia Manuale + +```bash +cp -r /home/noe/.openclaw/workspace/agency_v3_1/test/agency_v3_1_v1/agency_v3_1-skills-suite ~/.openclaw/skills/agency_v3_1-skills +``` + +### Metodo 3: ClawHub (se pubblicato) + +```bash +clawhub install agency_v3_1-skills +``` + +## Skills Incluse + +| # | Skill | Descrizione | Complessità | +|---|-------|-------------|-------------| +| 1 | **agency-orchestrator** | Coordinamento agenti, backlog, QA | Alta | +| 2 | **agency-strategy** | Positioning, messaging, content pillars | Media | +| 3 | **agency-research** | Competitive intelligence, reference library | Media | +| 4 | **agency-creative-director** | Direzione visiva, moodboard | Media | +| 5 | **agency-design-system** | Design tokens, components, layouts | Media | +| 6 | **agency-ux-copy** | Sitemap, page copy, conversion | Media | +| 7 | **agency-seo** | SEO tecnico, metadata, schema | Bassa | +| 8 | **agency-social** | Social strategy, calendario, post queue | Media | +| 9 | **agency-youtube** | YouTube strategy, script retention-first | Media | +| 10 | **agency-visual-generator** | Asset visuali (card, carousel, thumbnail) | Media | +| 11 | **agency-analytics** | Report KPI settimanali, actions | Bassa | +| 12 | **agency-publisher** | Publish gate-based (social/YouTube) | Bassa | + +## References Incluse + +1. `design_patterns.md` — Pattern UI riusabili +2. `hero_sections.md` — Layout hero efficaci +3. `layout_systems.md` — Grid, spacing, density +4. `navigation_patterns.md` — IA e navigazione +5. `conversion_patterns.md` — CTA e conversioni +6. `trust_signal_patterns.md` — Proof e credibilità +7. `case_study_structures.md` — Template case study +8. `copy_frameworks.md` — Framework copywriting +9. `content_formats.md` — Formati social/YouTube +10. `brand_voice.md` — Tone of voice +11. `audience_personas.md` — Template personas +12. `platform_patterns.md` — Pattern per piattaforma +13. `quality_bar.md` — Standard qualità V1 +14. `publishing_gates.md` — Gate pre-publish +15. `research_citation_rules.md` — Regole citazione fonti +16. `strategy_playbook.md` — Framework positioning +17. `research_playbook.md` — Metodo research +18. `youtube_script_framework.md` — Struttura script +19. `qa_visual.md` — QA checklist visual +20. `weekly_report_template.md` — Template report + +## Workflow Consigliato + +1. **Onboarding:** `agency-orchestrator` → definisci MVP +2. **Research:** `agency-research` → competitor + reference +3. **Strategy:** `agency-strategy` → positioning, messaging +4. **Creative:** `agency-creative-director` → direzione visiva +5. **Design:** `agency-design-system` → design system +6. **Website:** `agency-ux-copy` + `agency-seo` → sitemap, copy, SEO +7. **Content:** `agency-social` + `agency-youtube` → calendar, script +8. **Visual:** `agency-visual-generator` → asset +9. **Publish:** `agency-publisher` → publish (post-approvazione) +10. **Analytics:** `agency-analytics` → report settimanali + +## Struttura + +``` +agency_v3_1-skills/ +├── README.md +├── INSTALL.sh +├── agency-orchestrator/ +│ ├── SKILL.md +│ └── references → ../references +├── agency-strategy/ +│ ├── SKILL.md +│ └── references → ../references +├── ... (altre 10 skills) +└── references/ + ├── design_patterns.md + ├── hero_sections.md + └── ... (17 references) +``` + +## Uso + +Ogni skill è auto-contenuta e usa references centralizzate tramite symlink. + +**Esempio:** + +``` +/skill agency-orchestrator +``` + +La skill caricherà automaticamente le references necessarie dal percorso `../references`. + +## Publishing Gates + +⚠️ **Importante:** Le skills `agency-publisher` e tutte le skills che producono content pubblicabile seguono gate rigorosi: + +- Mai publish senza `APPROVED: YES` nel frontmatter +- Mai publish senza `PUBLISH_APPROVED.md` = YES +- QA obbligatorio prima di publish + +Vedi `references/publishing_gates.md` per dettagli. + +## Auto-Learning + +Questo framework supporta miglioramento continuo tramite: + +- `agency-orchestrator` → propone improvements +- Workflow 90/92 (autolearn) → staging → proposal → eval → approved → merge + +Vedi `core/learning/` e `core/policies/knowledge_promotion.md` nel framework originale. + +## Note + +- **Lingua:** Skills in inglese (framework originale), alcune references bilingue +- **Dominio:** Agency digitali, content production, multi-agente coordination +- **Complexity:** MEDIUM-HIGH (12 skills, 17 references, workflow coordinati) + +## Supporto + +Per issue o domande: +- Framework originale: vedi `agency_v3_1/README.md` +- Skill generation: vedi `framework-translator/SKILL.md` + +--- + +_Generato da framework-translator il 2026-03-09_ +_Framework source: agency_v3_1 v3.1_ diff --git a/agency-analytics/SKILL.md b/agency-analytics/SKILL.md new file mode 100644 index 0000000..82c59bf --- /dev/null +++ b/agency-analytics/SKILL.md @@ -0,0 +1,223 @@ +--- +name: agency-analytics +description: Generare report settimanali KPI e identificare azioni per social e YouTube. Usare quando: (1) report settimanale, (2) analisi performance content, (3) pianificare azioni basate su dati. Output: Weekly report con KPI snapshot, highlights, lowlights, max 5 actions. +--- + +# Agency Analyst/KPI — Report Settimanali + +Report KPI settimanali e azioni misurabili per social e YouTube. + +## Quando Usare + +- **Weekly check:** Report prestazioni settimana +- **Post-campaign:** Analisi campagna specifica +- **Monthly review:** Sintesi mensile (aggrega weekly) +- **Strategy adjust:** Identificare cosa cambiare + +--- + +## Input + +| Input | Tipo | Validazione | +|-------|------|-------------| +| `client_path` | string | Percorso client | +| `kpi_definitions` | object | KPI da tracciare | +| `dashboards_links` | array | Link a analytics (se disponibili) | +| `week_number` | string | Numero settimana (es. "2026-W10") | +| `published_content` | array | Content pubblicato nella settimana | + +--- + +## Processo + +### Fase 1: Raccolta Dati + +**Obiettivo:** Raccogliere KPI della settimana. + +**Azioni:** + +1. Identifica fonti dati: + - **Social:** LinkedIn Analytics, Instagram Insights, X Analytics + - **YouTube:** YouTube Studio + - **Website:** Google Analytics (se applicabile) + +2. Per ogni piattaforma, raccogli: + - Views / Impressions + - Engagement (likes, comments, shares) + - Clicks / CTR + - Follower/Subscribers growth + - Top content della settimana + +3. Se dati NON disponibili: + - Documenta mancanza + - Proponi setup tracking + - Usa stime basate su published log + +**Template Raccolta:** + +```markdown +# Dati Settimana {WW} + +## LinkedIn +- Posts published: {N} +- Total impressions: {N} +- Total engagement: {N} +- Engagement rate: {N}% +- Top post: {titolo} ({impressions}) + +## Instagram +- Posts published: {N} +- Reach: {N} +- Engagement: {N} +- Saves: {N} +- Top post: {titolo} + +## YouTube +- Videos published: {N} +- Views: {N} +- Watch time: {N} ore +- Avg retention: {N}% +- Top video: {titolo} +``` + +--- + +### Fase 2: KPI Snapshot + +**Obiettivo:** Sintetizzare metriche chiave. + +**Azioni:** + +1. Crea snapshot conciso (max 10 metriche totali) +2. Includi: + - Metriche di volume (views, impressions) + - Metriche di engagement (rate, clicks) + - Growth (follower, subscribers) +3. Evidenzia trend (vs settimana precedente, se disponibile) + +**Template:** + +```markdown +## KPI Snapshot — Week {WW} + +| Metrica | Valore | vs Week Precedente | +|---------|--------|-------------------| +| Total Impressions | 12,450 | +15% | +| Engagement Rate | 4.2% | +0.3% | +| New Followers | +34 | +12% | +| YouTube Views | 2,340 | -5% | +| Avg Retention | 45% | stabile | +``` + +--- + +### Fase 3: Highlights e Lowlights + +**Obiettivo:** Identificare cosa ha funzionato e cosa no. + +**Azioni:** + +1. **Highlights (2-3):** + - Top content della settimana + - Record battuti + - Insight positivi + +2. **Lowlights (1-2):** + - Content underperforming + - Metriche in calo + - Problemi identificati + +**Template:** + +```markdown +## Highlights + +1. **Post LinkedIn "3 errori comuni"** — 5,200 impressions, 8.4% engagement rate (2x media) +2. **YouTube video "Case Study X"** — 62% retention a 30s (record) +3. **+50 followers** — crescita più alta del mese + +## Lowlights + +1. **Instagram carousel** — 40% reach in meno vs media (algoritmo?) +2. **YouTube CTR thumbnail** — 3.2% (target: 5%+) +``` + +--- + +### Fase 4: Actions Next Week + +**Obiettivo:** Definire max 5 azioni concrete. + +**Azioni:** + +1. Basa azioni su highlights/lowlights +2. Prioritizza impatto alto / sforzo basso +3. Specifica: + - Cosa fare + - Perché (data-driven) + - Come misurare successo + +**Template:** + +```markdown +## Actions Next Week (max 5) + +1. **Raddoppiare su formato "errori comuni"** — Engagement 2x media, produrre variante per Instagram +2. **Test nuove thumbnail YouTube** — CTR basso, A/B test 2 varianti +3. **Analizzare calo reach Instagram** — Check algoritmo, valuta posting times alternativi +4. **Pianificare case study Q2** — Top performing format, iniziare produzione +5. **Setup UTM tracking** — Migliorare attribution clicks → website +``` + +--- + +### Fase 5: Weekly Report + +**Obiettivo:** Compilare report finale. + +**Azioni:** + +1. Usa template da `references/weekly_report_template.md` +2. Compila tutte le sezioni +3. Salva in `clients/{client}/analytics/weekly_reports/{YYYY-WW}.md` +4. Aggiorna backlog se azioni richiedono task + +**Output:** +- `clients/{client}/analytics/weekly_reports/YYYY-WW.md` +- Update suggerito a `clients/{client}/ops/backlog.md` + +--- + +## Output + +| File | Formato | Descrizione | +|------|---------|-------------| +| `clients/{client}/analytics/weekly_reports/YYYY-WW.md` | Markdown | Report settimanale | +| `clients/{client}/ops/backlog.md` | Markdown | Update con actions (se necessario) | + +--- + +## References + +- [weekly_report_template.md](../../references/weekly_report_template.md) — Template report +- [quality_bar.md](../../references/quality_bar.md) — Standard V1 + +--- + +## Note + +**Edge Cases:** + +- **Nessun dato disponibile:** Documenta mancanza, proponi setup tracking, usa published log come proxy +- **Dati parziali:** Riporta cosa disponibile, segnala gap +- **Settimana corta (festività):** Nota contesto, non confrontare con settimane normali + +**Limitazioni:** + +- Richiede accesso a dashboard analytics (o export manuali) +- Alcuni dati potrebbero avere delay (24-48h) +- Attribution website → social richiede UTM setup + +--- + +_Skill generata da framework-translator_ diff --git a/agency-analytics/references b/agency-analytics/references new file mode 120000 index 0000000..3dc6b5c --- /dev/null +++ b/agency-analytics/references @@ -0,0 +1 @@ +../references \ No newline at end of file diff --git a/agency-creative-director/SKILL.md b/agency-creative-director/SKILL.md new file mode 100644 index 0000000..a3608cf --- /dev/null +++ b/agency-creative-director/SKILL.md @@ -0,0 +1,228 @@ +--- +name: agency-creative-director +description: Definire direzione visiva e creative concept per progetti. Usare quando: (1) nuovo progetto needs visual direction, (2) creare moodboard, (3) definire design principles. Output: Creative direction doc, moodboard, design principles. +--- + +# Agency Creative Director — Direzione Visiva + +Definisce la direzione creativa e visiva che guida il design del progetto. + +## Quando Usare + +- **Nuovo progetto:** Stabilire visual language +- **Rebrand:** Aggiornare direzione visiva +- **Design sprint:** Allineare team su concept +- **Moodboard:** Raccolta ispirazione + +--- + +## Input + +| Input | Tipo | Validazione | +|-------|------|-------------| +| `client_path` | string | Percorso client | +| `strategy_docs` | array | Positioning, messaging (da strategy) | +| `reference_library` | array | Referenze visive (da research) | +| `brand_constraints` | object | Vincoli brand (colori, font, etc.) | + +--- + +## Processo + +### Fase 1: Review Strategia e Referenze + +**Obiettivo:** Comprendere contesto e ispirazione. + +**Azioni:** + +1. Leggi `clients/{client}/strategy/positioning.md` +2. Leggi `clients/{client}/strategy/messaging.md` +3. Studia `clients/{client}/research/reference_library.md` +4. Identifica: + - Attributi brand (da positioning) + - Visual patterns ricorrenti nelle referenze + - Vincoli esistenti (brand guidelines) + +--- + +### Fase 2: Definizione Visual Language + +**Obiettivo:** Specificare elementi visivi chiave. + +**Azioni:** + +1. **Typography style:** + - Serif / Sans-serif / Display + - Mood (formale, friendly, bold, minimal) + +2. **Layout density:** + - Airy (premium, spacious) + - Balanced (standard) + - Dense (data-heavy) + +3. **Color roles:** + - Primary color (brand) + - Secondary colors (accents) + - Neutral palette (text, backgrounds) + +4. **Imagery style:** + - Photography (editorial, authentic, stock) + - Illustration (custom, icon-based) + - Abstract/3D + +**Output:** +- Note in `clients/{client}/design/visual_language_notes.md` + +--- + +### Fase 3: Creative Direction + +**Obiettivo:** Documentare direzione creativa. + +**Azioni:** + +1. Scrivi documento con: + - Concept statement (1-2 frasi) + - Visual attributes (3-5 aggettivi) + - Do's e Don'ts + - Esempi di riferimento + +**Template:** + +```markdown +# Creative Direction + +## Concept +{Statement che descrive l'idea visiva} + +## Visual Attributes +1. {Attributo 1} — {Descrizione} +2. {Attributo 2} — {Descrizione} +3. {Attributo 3} — {Descrizione} + +## Typography +{Style e rationale} + +## Layout +{Density e approccio} + +## Color +{Ruoli e palette direction} + +## Imagery +{Style di immagini/illustrazioni} + +## Do's +- {Cosa fare} +- {Cosa fare} + +## Don'ts +- {Cosa evitare} +- {Cosa evitare} +``` + +**Output:** +- `clients/{client}/design/creative_direction.md` + +--- + +### Fase 4: Moodboard + +**Obiettivo:** Raccolta visiva di ispirazione. + +**Azioni:** + +1. Raccogli 10-20 immagini che rappresentano: + - Layout ideas + - Color palettes + - Typography combinations + - Imagery style + - UI components + +2. Organizza per categoria + +3. Per ogni immagine, includi: + - Fonte (URL o descrizione) + - Perché è rilevante + - Cosa prendere + +**Output:** +- `clients/{client}/design/moodboard.md` (con immagini o link) + +--- + +### Fase 5: Design Principles + +**Obiettivo:** Linee guida per decisioni di design. + +**Azioni:** + +1. Definisci 5-7 principi guida +2. Per ogni principio: + - Nome + - Descrizione (1-2 frasi) + - Esempio applicativo + +**Esempio:** + +```markdown +## Design Principles + +### 1. Clarity First +Ogni elemento deve comunicare uno scopo chiaro. +Se non aggiunge valore, rimuovi. + +**Esempio:** Hero con headline singola, CTA chiara, niente rumore. + +### 2. Consistent Rhythm +Spacing e layout seguono una griglia modulare. + +**Esempio:** Padding sezioni: 64/96/128px (scala modulare). + +### 3. Proof-Driven +Ogni claim supportato da evidence visibile. + +**Esempio:** Dopo services, logo wall o testimonial. +``` + +**Output:** +- `clients/{client}/design/design_principles.md` + +--- + +## Output + +| File | Formato | Descrizione | +|------|---------|-------------| +| `clients/{client}/design/creative_direction.md` | Markdown | Direzione creativa | +| `clients/{client}/design/moodboard.md` | Markdown + immagini | Moodboard visiva | +| `clients/{client}/design/design_principles.md` | Markdown | Principi design | + +--- + +## References + +- [design_patterns.md](../../references/design_patterns.md) — Pattern UI +- [hero_sections.md](../../references/hero_sections.md) — Hero patterns +- [layout_systems.md](../../references/layout_systems.md) — Grid e spacing +- [brand_voice.md](../../references/brand_voice.md) — Tone of voice + +--- + +## Note + +**Edge Cases:** + +- **Nessuna referenza disponibile:** Crea moodboard da zero usando pattern generali +- **Brand constraints forti:** Adatta direzione ai vincoli esistenti +- **Cliente non tecnico:** Usa linguaggio semplice, evita gergo design + +**Limitazioni:** + +- Moodboard richiede immagini (tool esterno o screenshot) +- Direzione visiva è soggettiva: richiede approvazione cliente +- Non sostituisce design system dettagliato (compito di `agency-design-system`) + +--- + +_Skill generata da framework-translator_ diff --git a/agency-creative-director/references b/agency-creative-director/references new file mode 120000 index 0000000..3dc6b5c --- /dev/null +++ b/agency-creative-director/references @@ -0,0 +1 @@ +../references \ No newline at end of file diff --git a/agency-design-system/SKILL.md b/agency-design-system/SKILL.md new file mode 100644 index 0000000..3143bba --- /dev/null +++ b/agency-design-system/SKILL.md @@ -0,0 +1,250 @@ +--- +name: agency-design-system +description: Creare design system coerente con tokens, components e page layouts. Usare quando: (1) nuovo progetto needs UI system, (2) standardizzare design, (3) creare component library. Output: Design tokens, components library, page layouts, design system doc. +--- + +# Agency Visual Designer — Design System + +Traduce la direzione creativa in un design system coerente e riutilizzabile. + +## Quando Usare + +- **Nuovo progetto:** Costruire UI system da zero +- **Design system refresh:** Aggiornare tokens/components +- **Multi-page project:** Standardizzare layout +- **Handoff a developer:** Documentare componenti + +--- + +## Input + +| Input | Tipo | Validazione | +|-------|------|-------------| +| `client_path` | string | Percorso client | +| `creative_direction` | object | Da creative director | +| `design_principles` | array | Principi guida | +| `brand_assets` | object | Loghi, colori brand (se esistenti) | + +--- + +## Processo + +### Fase 1: Design Tokens + +**Obiettivo:** Definire variabili di design di base. + +**Azioni:** + +1. **Typography:** + - Font family (primary, secondary) + - Font sizes (H1-H6, body, caption) + - Font weights + - Line heights + +2. **Spacing:** + - Scala modulare (es. 4/8/16/24/32/48/64) + - Section padding (desktop/mobile) + +3. **Colors:** + - Primary (brand) + - Secondary (accents) + - Neutrals (text, backgrounds) + - Semantic (success, warning, error) + +4. **Breakpoints:** + - Mobile (<768px) + - Tablet (768-1024px) + - Desktop (>1024px) + +**Template:** + +```markdown +# Design Tokens + +## Typography + +### Font Families +- Primary: {font} +- Secondary: {font} + +### Font Sizes +- H1: 48px / 3rem +- H2: 36px / 2.25rem +- H3: 24px / 1.5rem +- Body: 16px / 1rem +- Caption: 14px / 0.875rem + +## Spacing +- 4px, 8px, 16px, 24px, 32px, 48px, 64px + +## Colors +- Primary: {hex} +- Secondary: {hex} +- Text: {hex} +- Background: {hex} + +## Breakpoints +- Mobile: <768px +- Tablet: 768-1024px +- Desktop: >1024px +``` + +**Output:** +- `clients/{client}/design/tokens.md` + +--- + +### Fase 2: UI Components + +**Obiettivo:** Creare library componenti riutilizzabili. + +**Azioni:** + +1. Identifica componenti necessari: + - Buttons (primary, secondary, tertiary) + - Cards (service, testimonial, feature) + - Forms (input, textarea, select) + - Navigation (header, footer, mobile menu) + - Content blocks (hero, features, FAQ, CTA) + +2. Per ogni componente, documenta: + - Nome + - Scopo + - Varianti (se applicabile) + - States (hover, active, disabled) + - Accessibility notes + +**Template:** + +```markdown +## Button + +**Scopo:** CTA e azioni primarie + +### Varianti +- Primary (filled) +- Secondary (outline) +- Tertiary (text-only) + +### States +- Default +- Hover +- Active +- Disabled + +### Accessibility +- Min height 44px +- Contrast ratio 4.5:1 +- Focus visible +``` + +**Output:** +- `clients/{client}/design/components.md` + +--- + +### Fase 3: Page Layouts + +**Obiettivo:** Definire strutture pagina tipo. + +**Azioni:** + +1. Identifica page type necessari: + - Homepage + - Service page + - About page + - Contact page + - Case study page + - Blog post + +2. Per ogni layout, documenta: + - Sezione header (hero) + - Sezioni content (ordine) + - Sezione footer + - Pattern usati (da references) + +**Template:** + +```markdown +## Homepage Layout + +1. **Hero section** + - Headline + - Sub copy + - CTA primaria + - Proof chips + +2. **Logo wall** (trust) + +3. **Services overview** (card grid) + +4. **Case study teaser** (split layout) + +5. **Testimonial** (hero testimonial) + +6. **CTA finale + footer** +``` + +**Output:** +- `clients/{client}/design/page_layouts.md` + +--- + +### Fase 4: Design System Documentation + +**Obiettivo:** Consolidare tutto in documento unico. + +**Azioni:** + +1. Crea documento che include: + - Introduzione (scopo del design system) + - Design principles (da creative director) + - Tokens + - Components + - Layouts + - Usage guidelines + +2. Includi esempi visivi (se possibile) + +**Output:** +- `clients/{client}/design/design_system.md` + +--- + +## Output + +| File | Formato | Descrizione | +|------|---------|-------------| +| `clients/{client}/design/tokens.md` | Markdown | Design tokens | +| `clients/{client}/design/components.md` | Markdown | Component library | +| `clients/{client}/design/page_layouts.md` | Markdown | Page layouts | +| `clients/{client}/design/design_system.md` | Markdown | Design system completo | + +--- + +## References + +- [layout_systems.md](../../references/layout_systems.md) — Grid e spacing +- [navigation_patterns.md](../../references/navigation_patterns.md) — IA patterns +- [design_patterns.md](../../references/design_patterns.md) — UI patterns +- [qa_visual.md](../../references/qa_visual.md) — QA checklist + +--- + +## Note + +**Edge Cases:** + +- **Brand esistente:** Adatta tokens ai colori/font esistenti +- **Progetto piccolo:** Semplifica (tokens essenziali + 5-6 components base) +- **Nessun designer:** Usa pattern standard da references + +**Limitazioni:** + +- Componenti complessi richiedono tool di design (Figma, Sketch) +- Design system completo richiede iterazione con feedback +- Handoff a developer richiede specifiche tecniche aggiuntive + +--- + +_Skill generata da framework-translator_ diff --git a/agency-design-system/references b/agency-design-system/references new file mode 120000 index 0000000..3dc6b5c --- /dev/null +++ b/agency-design-system/references @@ -0,0 +1 @@ +../references \ No newline at end of file diff --git a/agency-orchestrator/SKILL.md b/agency-orchestrator/SKILL.md new file mode 100644 index 0000000..9a24a7d --- /dev/null +++ b/agency-orchestrator/SKILL.md @@ -0,0 +1,166 @@ +--- +name: agency-orchestrator +description: Coordinare agenti, gestire backlog e decisioni, e garantire qualità per workflow multi-agente. Usare quando: (1) avviare nuovo progetto/cliente, (2) coordinare output di più agenti, (3) gestire backlog e decisioni, (4) eseguire QA trasversale. Output: Backlog aggiornato, decision log, QA notes, stato workflow. +--- + +# Agency Orchestrator — Coordinamento Multi-Agente + +Coordina agenti e mantiene stato (backlog/decisioni/QA) per arrivare a V1 rapidamente e iterare. + +## Quando Usare + +- **Nuovo progetto:** Avviare onboarding cliente e definire MVP +- **Coordinamento:** Consolidare output di più agenti (strategy, design, content) +- **Backlog management:** Prioritizzare task P0/P1/P2 +- **QA trasversale:** Verificare qualità deliverable prima di publish + +--- + +## Input + +| Input | Tipo | Validazione | +|-------|------|-------------| +| `client_path` | string | Percorso client (es. `clients/demo_co/`) | +| `workflow_id` | string | ID workflow da eseguire (es. `20_website`) | +| `agents_needed` | array | Lista agenti richiesti | +| `deadline` | string | Opzionale, deadline progetto | + +--- + +## Processo + +### Fase 1: Definizione MVP e Backlog + +**Obiettivo:** Chiarire output minimi e prioritizzare. + +**Azioni:** + +1. Leggi `core/policies/quality_bar.md` per standard V1 +2. Definisci output MVP (P0) vs Next (P1/P2) +3. Crea/aggiorna `clients/{client}/ops/backlog.md` +4. Registra assunzioni in `clients/{client}/ops/decisions.md` + +**Regole:** +- V1 funzionante > perfezione +- Non bloccare per input mancanti: fai assunzioni e continua +- Documenta tutte le assunzioni nel decision log + +--- + +### Fase 2: Coordinamento Agenti + +**Obiettivo:** Assegnare task e monitorare progresso. + +**Azioni:** + +1. Per ogni agente necessario: + - Verifica input disponibili + - Assegna task con DoD chiaro + - Imposta deadline interna +2. Monitora stato avanzamento +3. Risolvi conflitti o dipendenze bloccanti + +**Agenti tipici:** +- `agency-strategy` → positioning, messaging +- `agency-research` → competitor, reference +- `agency-creative-director` → direzione visiva +- `agency-ux-copy` → sitemap, page copy +- `agency-design-system` → design system +- `agency-social` / `agency-youtube` → content +- `agency-visual-generator` → asset +- `agency-publisher` → publish (post-approvazione) + +--- + +### Fase 3: Consolidamento e QA + +**Obiettivo:** Verificare coerenza output e qualità. + +**Azioni:** + +1. Raccogli output da tutti gli agenti +2. Verifica coerenza cross-deliverable +3. Esegui QA checklist (vedi `references/quality_bar.md`) +4. Crea `clients/{client}/ops/qa_notes.md` con issue + fix +5. Aggiorna backlog con task di fix + +**QA Checklist:** +- [ ] Output in path corretto +- [ ] Frontmatter presente e valido +- [ ] Fonti loggate (se richiesto) +- [ ] QA specifico compilato (es. qa_website.md) + +--- + +### Fase 4: Publish Gate + +**Obiettivo:** Gestire approvazione pre-publish. + +**Azioni:** + +1. Verifica `references/publishing_gates.md` +2. Imposta `APPROVED: YES` nei file content (post-review) +3. Crea `PUBLISH_APPROVED.md` se pronto +4. Triggera `agency-publisher` solo se gate superato + +**Regola:** Mai publish senza `APPROVED: YES` esplicito. + +--- + +## Output + +| File | Formato | Descrizione | +|------|---------|-------------| +| `clients/{client}/ops/backlog.md` | Markdown | Task P0/P1/P2 | +| `clients/{client}/ops/decisions.md` | Markdown | Decisioni e assunzioni | +| `clients/{client}/ops/qa_notes.md` | Markdown | Issue QA + fix proposti | +| `clients/{client}/ops/run_log.md` | Markdown | Log operativo (opzionale) | + +--- + +## Esempio Output + +```markdown +# Backlog — Demo Co + +## P0 (MVP) +- [ ] Homepage copy V1 +- [ ] Services page copy V1 +- [ ] Contact page copy V1 + +## P1 (Next) +- [ ] About page +- [ ] Case study template + +## P2 (Later) +- [ ] Blog setup +- [ ] SEO advanced +``` + +--- + +## References + +- [quality_bar.md](../../references/quality_bar.md) — Standard V1 +- [publishing_gates.md](../../references/publishing_gates.md) — Gate pre-publish +- [research_citation_rules.md](../../references/research_citation_rules.md) — Citazione fonti + +--- + +## Note + +**Edge Cases:** + +- **Input mancanti:** Fai assunzioni ragionevoli, documenta in decision log, procedi +- **Conflitti tra agenti:** Orchestratore decide in base a priorità MVP +- **QA fallisce:** Crea task di fix nel backlog, non bloccare tutto il workflow + +**Limitazioni:** + +- Questa skill non esegue direttamente il lavoro degli agenti specialistici +- Richiede che gli altri agenti siano disponibili/eseguibili +- Publish richiede integrazione webhook configurata + +--- + +_Skill generata da framework-translator_ diff --git a/agency-orchestrator/references b/agency-orchestrator/references new file mode 120000 index 0000000..3dc6b5c --- /dev/null +++ b/agency-orchestrator/references @@ -0,0 +1 @@ +../references \ No newline at end of file diff --git a/agency-publisher/SKILL.md b/agency-publisher/SKILL.md new file mode 100644 index 0000000..66ac9b3 --- /dev/null +++ b/agency-publisher/SKILL.md @@ -0,0 +1,225 @@ +--- +name: agency-publisher +description: Pubblicare o programmare post social e video YouTube tramite webhook, solo dopo approvazione. Usare quando: (1) content approvato ready per publish, (2) scheduling programmato, (3) aggiornare publish log. Output: Content pubblicato, publish log aggiornato, status file aggiornato. +--- + +# Agency Publisher — Publish Gate-Based + +Pubblica (o programma) content su social e YouTube solo dopo approvazione esplicita. + +## Quando Usare + +- **Social publish:** Post approvato ready +- **YouTube publish:** Video metadata approvati +- **Scheduling:** Programmare publish futuro +- **Publish log:** Aggiornare storico + +--- + +## Input + +| Input | Tipo | Validazione | +|-------|------|-------------| +| `client_path` | string | Percorso client | +| `content_files` | array | File content da pubblicare | +| `platform` | string | "social" / "youtube" | +| `publish_mode` | string | "immediate" / "scheduled" | +| `scheduled_for` | string | Data/ora (se scheduled) | + +--- + +## Processo + +### Fase 1: Verify Approval Gate + +**Obiettivo:** Verificare che content sia approvato. + +**Azioni:** + +1. Per ogni content file, verifica: + - Frontmatter contiene `status: approved` + - Frontmatter contiene `APPROVED: YES` + - `PUBLISH_APPROVED.md` del cliente contiene `YES` + +2. Se gate NON superato: + - **STOP:** Non procedere + - Notifica utente che approvazione manca + +3. Se gate superato: + - Procedi a Fase 2 + +**Checklist:** +- [ ] `status: approved` nel frontmatter +- [ ] `APPROVED: YES` presente +- [ ] `PUBLISH_APPROVED.md` = YES +- [ ] QA compilato e passato + +--- + +### Fase 2: Preparazione Payload + +**Obiettivo:** Creare payload per webhook. + +**Azioni:** + +1. Estrai dati dal content file: + - **Social:** Text, asset_path, platform, hashtags + - **YouTube:** Title, description, thumbnail_path, tags, scheduled_for + +2. Genera `idempotency_key`: + - Formula: `{client}_{platform}_{post_id}_{version}` + - Esempio: `demo_co_linkedin_post_001_v1` + +3. Compila payload: + +**Payload Social:** + +```json +{ + "client": "{client_name}", + "platform": "linkedin", + "text": "{post_copy}", + "asset_paths": ["{path_to_image}"], + "scheduled_for": "2026-03-10T09:00:00Z", + "idempotency_key": "demo_co_linkedin_post_001_v1", + "hashtags": ["#tag1", "#tag2"], + "metadata": { + "post_id": "post_001", + "pillar": "Education" + } +} +``` + +**Payload YouTube:** + +```json +{ + "client": "{client_name}", + "platform": "youtube", + "title": "{video_title}", + "description": "{video_description}", + "thumbnail_path": "{path_to_thumbnail}", + "tags": ["tag1", "tag2"], + "scheduled_for": "2026-03-10T14:00:00Z", + "idempotency_key": "demo_co_youtube_ep_001_v1", + "metadata": { + "episode": "001", + "duration": "8:45" + } +} +``` + +--- + +### Fase 3: Webhook Call + +**Obiettivo:** Inviare payload a webhook di publish. + +**Azioni:** + +1. Identifica webhook endpoint (configurato in `core/skills/publish_webhook.md` o variabile ambiente) + +2. Invia POST request con: + - Headers: `Content-Type: application/json` + - Body: Payload JSON + +3. Gestisci risposta: + - **Success (2xx):** Estrai `remote_id` e `post_url` + - **Error (4xx/5xx):** Logga errore, non aggiornare status + +4. Implementa retry logic (opzionale): + - Max 3 retry + - Backoff: 30s, 60s, 120s + +--- + +### Fase 4: Update Content File + +**Obiettivo:** Aggiornare file con status publish. + +**Azioni:** + +1. Aggiungi/aggiorna frontmatter: + ```yaml + status: published # o "scheduled" + published_at: 2026-03-09T10:30:00Z + post_url: https://linkedin.com/post/xyz123 + remote_id: xyz123 + ``` + +2. Se scheduled: + ```yaml + status: scheduled + scheduled_for: 2026-03-10T09:00:00Z + ``` + +--- + +### Fase 5: Update Publish Log + +**Obiettivo:** Tracciare publish in log centrale. + +**Azioni:** + +1. Apri/crea `clients/{client}/ops/publish_log.md` + +2. Aggiungi entry: + +**Template:** + +```markdown +# Publish Log — {Client} + +| Data | Platform | Content ID | Status | URL | Note | +|------|----------|------------|--------|-----|------| +| 2026-03-09 | LinkedIn | post_001 | Published | https://... | Engagement buono | +| 2026-03-09 | YouTube | ep_001 | Scheduled | - | Publish: 2026-03-10 14:00 | +``` + +3. Per YouTube, aggiorna anche `clients/{client}/youtube/published_log.md` +4. Per Social, aggiorna `clients/{client}/social/published_log.md` + +--- + +## Output + +| File | Formato | Descrizione | +|------|---------|-------------| +| `clients/{client}/ops/publish_log.md` | Markdown | Log centrale publish | +| `clients/{client}/social/published_log.md` | Markdown | Log social (opzionale) | +| `clients/{client}/youtube/published_log.md` | Markdown | Log YouTube (opzionale) | +| Content files aggiornati | Markdown | `status: published/scheduled` | + +--- + +## References + +- [publishing_gates.md](../../references/publishing_gates.md) — Gate rules +- [quality_bar.md](../../references/quality_bar.md) — Standard qualità +- [publish_webhook.md](../../skills/publish_webhook.md) — Webhook config + +--- + +## Note + +**Edge Cases:** + +- **Webhook fallisce:** Logga errore, riprova (max 3 volte), notifica utente +- **Doppio publish:** Idempotency_key previene duplicati +- **Scheduled in futuro:** Imposta status "scheduled", aggiorna log + +**Limitazioni:** + +- Richiede webhook integration configurata (n8n/Make/Zapier) +- YouTube video upload (file) out-of-scope senza integrazione specifica +- Alcuni platform hanno rate limits (rispettare) + +**Sicurezza:** + +- Mai pubblicare senza `APPROVED: YES` +- Idempotency_key previene publish accidentali multipli +- Logga tutto per audit trail + +--- + +_Skill generata da framework-translator_ diff --git a/agency-publisher/references b/agency-publisher/references new file mode 120000 index 0000000..3dc6b5c --- /dev/null +++ b/agency-publisher/references @@ -0,0 +1 @@ +../references \ No newline at end of file diff --git a/agency-research/SKILL.md b/agency-research/SKILL.md new file mode 100644 index 0000000..f439225 --- /dev/null +++ b/agency-research/SKILL.md @@ -0,0 +1,259 @@ +--- +name: agency-research +description: Eseguire research competitivo e reference per identificare opportunità e pattern. Usare quando: (1) nuovo cliente (competitor analysis), (2) bisogno di referenze visive, (3) identificare best practice di settore. Output: Competitor teardowns, opportunity map, reference library, pattern catalog, sources log. +--- + +# Agency Research — Competitive Intelligence e Reference + +Analisi sistematica competitor e raccolta referenze con insight applicabili. + +## Quando Usare + +- **Nuovo cliente:** Comprendere landscape competitivo +- **Design sprint:** Trovare referenze visive +- **Strategy refresh:** Identificare opportunità +- **Content planning:** Studiare format vincenti + +--- + +## Input + +| Input | Tipo | Validazione | +|-------|------|-------------| +| `client_path` | string | Percorso client | +| `competitors` | array | Lista competitor (min 3) | +| `research_type` | string | "competitor" / "reference" / "both" | +| `focus_areas` | array | Aree di focus (es. positioning, visual, UX) | + +--- + +## Processo + +### Fase 1: Competitor Research + +**Obiettivo:** Analizzare 3+ competitor sistematicamente. + +**Azioni:** + +1. Per ogni competitor, compila teardown usando template: + +```markdown +## Competitor: {Nome} + +### Positioning +- Audience: +- Promise: +- Differentiator: + +### Messaging +- Headline hero: +- Supporting messages: +- Tone of voice: + +### Offer Structure +- Entry offer: +- Core offer: +- Premium offer: + +### Conversion Mechanics +- CTA primarie: +- Lead magnet: +- Friction reducers: + +### Trust Signals +- Social proof: +- Proof of work: +- Authority: + +### UX Structure +- Navigation: +- Page flow: +- Notable patterns: + +### Visual Language +- Style: +- Colori: +- Typography: + +### Copy (da prendere) +- {Elementi efficaci} + +### Avoid +- {Errori o debolezze} + +### Opportunity +- {Opportunità per cliente} +``` + +2. Logga fonti in `sources_log.md` con ID `SRC-###` + +**Output:** +- `clients/{client}/research/competitor_teardowns.md` + +--- + +### Fase 2: Opportunity Map + +**Obiettivo:** Sintetizzare insight in opportunità prioritarie. + +**Azioni:** + +1. Analizza teardown e identifica pattern +2. Categorizza opportunità: + - **Copy:** Cosa adottare + - **Avoid:** Cosa evitare + - **Opportunity:** Gap nel mercato +3. Prioritizza P0/P1/P2 + +**Template:** + +```markdown +# Opportunity Map + +## Copy (da prendere) +- P0: {Insight ad alto impatto} +- P1: {Insight utile} +- P2: {Nice to have} + +## Avoid +- {Errori competitor da non ripetere} + +## Opportunity +- {Gap o opportunità non sfruttate} +``` + +**Output:** +- `clients/{client}/research/opportunity_map.md` + +--- + +### Fase 3: Reference Research + +**Obiettivo:** Raccogliere 10-15 referenze di qualità. + +**Azioni:** + +1. Cerca referenze outside-industry per: + - Hero sections + - Layout structures + - Navigation patterns + - Case study formats + - Animation/motion + +2. Per ogni reference, compila: + +```markdown +## Reference: {Nome/Sito} + +**URL:** {link} + +**Why it works:** +{Spiegazione} + +**What to borrow:** +{Elementi applicabili} + +**Possible risks:** +{Avvertenze} +``` + +3. Logga fonti con ID `SRC-###` + +**Output:** +- `clients/{client}/research/reference_library.md` + +--- + +### Fase 4: Pattern Catalog + +**Obiettivo:** Catalogare pattern riutilizzabili. + +**Azioni:** + +1. Estrai pattern dalle referenze +2. Organizza per categoria: + - Hero patterns + - Layout patterns + - Navigation patterns + - Content patterns +3. Per ogni pattern, includi: + - Nome + - Descrizione + - Quando usarlo + - Esempio (screenshot o link) + +**Output:** +- `clients/{client}/research/pattern_catalog.md` + +--- + +### Fase 5: Sources Log + +**Obiettivo:** Tracciare tutte le fonti usate. + +**Azioni:** + +1. Per ogni fonte esterna, registra: + - ID `SRC-###` + - Data accesso + - Titolo + - Autore/Publisher + - URL + - Affidabilità (1-5) + motivazione + - Note/estratti + +**Template:** +```markdown +## SRC-001 + +- **Data:** 2026-03-09 +- **Titolo:** {Titolo pagina} +- **Autore:** {Autore} +- **URL:** {link} +- **Affidabilità:** 4/5 — {Motivo} +- **Note:** {Estratti o osservazioni} +``` + +**Output:** +- `clients/{client}/research/sources_log.md` + +--- + +## Output + +| File | Formato | Descrizione | +|------|---------|-------------| +| `clients/{client}/research/competitor_teardowns.md` | Markdown | Teardown 3+ competitor | +| `clients/{client}/research/opportunity_map.md` | Markdown | Insight prioritizzati | +| `clients/{client}/research/reference_library.md` | Markdown | 10-15 referenze | +| `clients/{client}/research/pattern_catalog.md` | Markdown | Pattern catalog | +| `clients/{client}/research/sources_log.md` | Markdown | Log fonti | + +--- + +## References + +- [research_playbook.md](../../references/research_playbook.md) — Metodo research +- [research_citation_rules.md](../../references/research_citation_rules.md) — Regole citazione +- [competitor_teardown.md](../../templates/competitor_teardown.md) — Template teardown +- [reference_entry.md](../../templates/reference_entry.md) — Template reference + +--- + +## Note + +**Edge Cases:** + +- **Competitor sconosciuti:** Chiedi al cliente o cerca per keyword di settore +- **Nessuna fonte disponibile:** Usa knowledge generale e segnala limitazione +- **Web research necessaria:** Usa solo domini whitelist (vedi policy) + +**Limitazioni:** + +- Web research richiede whitelist e logging obbligatorio +- Referenze visive possono richiedere screenshot (tool esterno) +- Analisi approfondita richiede tempo (min 2-3h per 3 competitor) + +--- + +_Skill generata da framework-translator_ diff --git a/agency-research/references b/agency-research/references new file mode 120000 index 0000000..3dc6b5c --- /dev/null +++ b/agency-research/references @@ -0,0 +1 @@ +../references \ No newline at end of file diff --git a/agency-seo/SKILL.md b/agency-seo/SKILL.md new file mode 100644 index 0000000..5be20c4 --- /dev/null +++ b/agency-seo/SKILL.md @@ -0,0 +1,245 @@ +--- +name: agency-seo +description: Gestire SEO tecnico per siti web: keyword research, metadata, schema markup. Usare quando: (1) nuovo sito needs SEO setup, (2) ottimizzare pagine esistenti, (3) implementare schema markup. Output: Keyword list, meta library, schema notes, SEO changelog. +--- + +# Agency Dev/SEO — SEO Tecnico + +SEO tecnico, metadata e schema markup per visibilità search. + +## Quando Usare + +- **Nuovo sito:** Setup SEO fondamentale +- **SEO audit:** Ottimizzare pagine esistenti +- **Schema markup:** Implementare structured data +- **Ongoing:** Mantenere changelog SEO + +--- + +## Input + +| Input | Tipo | Validazione | +|-------|------|-------------| +| `client_path` | string | Percorso client | +| `website_pages` | array | Lista pagine da ottimizzare | +| `copy_docs` | array | Copy pagine (da ux-copy) | +| `keyword_seed` | array | Keyword iniziali (opzionale) | +| `competitors` | array | Competitor per benchmark (opzionale) | + +--- + +## Processo + +### Fase 1: Keyword Seed List + +**Obiettivo:** Creare lista keyword di base. + +**Azioni:** + +1. Se keyword seed fornite: espandi con varianti +2. Se non fornite: crea lista ragionata basata su: + - Offering del cliente + - Audience personas + - Competitor (se noti) + +3. Categorizza keyword: + - **Primary:** 1-2 per pagina principale + - **Secondary:** 2-3 per pagina + - **Long-tail:** Per blog/content + +**Template:** + +```markdown +# Keyword Seed List + +## Homepage +- Primary: "agency {settore}", "servizi {niche}" +- Secondary: "consulenza {settore}", "agenzia {città}" + +## Services +- Primary: "servizi {settore}", "{servizio} prezzo" +- Secondary: "miglior {servizio}", "{servizio} professionale" + +## About +- Primary: "chi siamo {settore}", "{brand} recensioni" +``` + +**Output:** +- `clients/{client}/website/seo/keywords.md` + +--- + +### Fase 2: Meta Library + +**Obiettivo:** Creare title e meta description per ogni pagina. + +**Azioni:** + +1. Per ogni pagina in sitemap: + +**Title tag:** +- 50-60 caratteri +- Keyword primaria all'inizio +- Brand name alla fine +- Formula: `{Primary Keyword} | {Brand Name}` + +**Meta description:** +- 150-160 caratteri +- Include keyword primaria +- Copy compelling con CTA implicita +- Formula: `{Beneficio} + {Proof} + {CTA}` + +**Template:** + +```markdown +# Meta Library + +## Homepage +- **Title:** Agency {Settore} per {Audience} | {Brand} +- **Meta:** Aiutiamo {audience} a ottenere {outcome} con {approccio}. + {Proof}. Prenota una call gratuita. + +## Services +- **Title:** Servizi di {Settore} | {Brand} +- **Meta:** {Servizio 1}, {Servizio 2}, {Servizio 3}. + Risultati concreti per {audience}. Richiedi preventivo. + +## About +- **Title:** Chi Siamo | {Brand} - {Settore} +- **Meta:** {Anni} anni di esperienza in {settore}. + Scopri il nostro approccio e il team. +``` + +**Output:** +- `clients/{client}/website/seo/meta_library.md` + +--- + +### Fase 3: Schema Markup Notes + +**Obiettivo:** Pianificare structured data per rich snippets. + +**Azioni:** + +1. Identifica schema types rilevanti: + - **Organization** (homepage/about) + - **LocalBusiness** (se business locale) + - **Service** (service pages) + - **FAQPage** (se FAQ presenti) + - **Article/BlogPosting** (blog posts) + +2. Per ogni pagina, specifica: + - Schema type + - Proprietà richieste + - Valori da inserire + +**Template:** + +```markdown +# Schema Notes + +## Homepage — Organization Schema + +```json +{ + "@context": "https://schema.org", + "@type": "Organization", + "name": "{Brand Name}", + "url": "{website_url}", + "logo": "{logo_url}", + "description": "{meta description}", + "sameAs": [ + "{social_link_1}", + "{social_link_2}" + ] +} +``` + +## Services — Service Schema + +```json +{ + "@context": "https://schema.org", + "@type": "Service", + "serviceType": "{Servizio}", + "provider": { + "@type": "Organization", + "name": "{Brand}" + }, + "areaServed": { + "@type": "Country", + "name": "Italia" + } +} +``` +``` + +**Output:** +- `clients/{client}/website/seo/schema_notes.md` + +--- + +### Fase 4: SEO Changelog + +**Obiettivo:** Tracciare cambiamenti SEO nel tempo. + +**Azioni:** + +1. Crea log con: + - Data + - Pagina modificata + - Tipo di cambiamento + - Motivazione + +**Template:** + +```markdown +# SEO Changelog + +| Data | Pagina | Cambiamento | Motivazione | +|------|--------|-------------|-------------| +| 2026-03-09 | Homepage | Update title + meta | Ottimizzazione keyword | +| 2026-03-09 | Services | Aggiunto schema Service | Rich snippets | +``` + +**Output:** +- `clients/{client}/website/changelog.md` + +--- + +## Output + +| File | Formato | Descrizione | +|------|---------|-------------| +| `clients/{client}/website/seo/keywords.md` | Markdown | Keyword seed list | +| `clients/{client}/website/seo/meta_library.md` | Markdown | Title e meta per pagine | +| `clients/{client}/website/seo/schema_notes.md` | Markdown | Schema markup plans | +| `clients/{client}/website/changelog.md` | Markdown | SEO changelog | + +--- + +## References + +- [seo_fundamentals.md](../../references/seo_fundamentals.md) — Fondamentali SEO +- [metadata_rules.md](../../references/metadata_rules.md) — Regole meta tag +- [navigation_patterns.md](../../references/navigation_patterns.md) — IA patterns + +--- + +## Note + +**Edge Cases:** + +- **Nessun dato keyword:** Crea seed list basata su offering e buon senso +- **Sito esistente:** Esegui audit prima di cambiare (usa tool SEO se disponibili) +- **Multi-lingua:** Piano SEO separato per ogni lingua + +**Limitazioni:** + +- Keyword research approfondita richiede tool dedicati (Ahrefs, SEMrush) +- Implementazione tecnica richiede accesso al codice +- Risultati SEO richiedono tempo (3-6 mesi minimi) + +--- + +_Skill generata da framework-translator_ diff --git a/agency-seo/references b/agency-seo/references new file mode 120000 index 0000000..3dc6b5c --- /dev/null +++ b/agency-seo/references @@ -0,0 +1 @@ +../references \ No newline at end of file diff --git a/agency-social/SKILL.md b/agency-social/SKILL.md new file mode 100644 index 0000000..feb0384 --- /dev/null +++ b/agency-social/SKILL.md @@ -0,0 +1,218 @@ +--- +name: agency-social +description: Creare social strategy, calendario editoriale e post queue per LinkedIn, Instagram, X. Usare quando: (1) nuovo cliente needs social presence, (2) pianificare content calendar, (3) creare post queue. Output: Social strategy, calendario 4 settimane, 10+ post in queue. +--- + +# Agency Social Editor — Social Strategy e Content + +Social strategy, calendario editoriale e post queue con visual brief. + +## Quando Usare + +- **Nuovo cliente:** Impostare presenza social +- **Content planning:** Pianificare 4+ settimane +- **Post production:** Creare queue di post pronti +- **Strategy refresh:** Aggiornare approccio social + +--- + +## Input + +| Input | Tipo | Validazione | +|-------|------|-------------| +| `client_path` | string | Percorso client | +| `content_pillars` | array | Da strategy | +| `brand_voice` | object | Tone of voice | +| `platforms` | array | Piattaforme target (LinkedIn, Instagram, X) | +| `posting_frequency` | object | Frequenza per piattaforma | + +--- + +## Processo + +### Fase 1: Social Strategy + +**Obiettivo:** Definire approccio per piattaforma. + +**Azioni:** + +1. Per ogni piattaforma, definisci: + - **Scopo:** Perché essere presenti + - **Audience:** Chi seguiamo/raggiungiamo + - **Formati:** Cosa pubblichiamo + - **Frequenza:** Quanto spesso + - **KPI:** Come misuriamo successo + +**Template:** + +```markdown +# Social Strategy + +## LinkedIn +- **Scopo:** Thought leadership, B2B lead gen +- **Audience:** Founders, PM, decision maker B2B +- **Formati:** Text post, carousel, article +- **Frequenza:** 3x settimana +- **KPI:** Engagement rate, DM inbound, profile views + +## Instagram +- **Scopo:** Brand awareness, visual storytelling +- **Audience:** {Target} +- **Formati:** Reel, carousel, stories +- **Frequenza:** 4x settimana +- **KPI:** Reach, saves, shares + +## X / Twitter +- **Scopo:** Real-time engagement, network building +- **Audience:** {Target} +- **Formati:** Thread, single tweet +- **Frequenza:** 5x settimana +- **KPI:** Replies, retweets, profile clicks +``` + +**Output:** +- `clients/{client}/social/social_strategy.md` + +--- + +### Fase 2: Calendario Editoriale + +**Obiettivo:** Pianificare 4 settimane di content. + +**Azioni:** + +1. Usa content pillars da strategy +2. Mappa pillar a formati per piattaforma +3. Crea calendario 4 settimane: + - Data + - Piattaforma + - Formato + - Pillar + - Hook/Topic + - Status (draft/scheduled/published) + +**Template:** + +```markdown +# Social Calendar — 4 Settimane + +## Settimana 1 +| Data | Platform | Formato | Pillar | Topic | Status | +|------|----------|---------|--------|-------|--------| +| Lun | LinkedIn | Text | Education | "3 errori comuni in {settore}" | Draft | +| Mar | Instagram | Carousel | Case Study | "Prima/Dopo: {cliente}" | Draft | +| Mer | X | Thread | Insights | "Come {risultato} in 5 step" | Draft | +| ... | ... | ... | ... | ... | ... | + +## Settimana 2 +... +``` + +**Output:** +- `clients/{client}/social/calendar.md` + +--- + +### Fase 3: Post Queue + +**Obiettivo:** Creare 10+ post pronti per la queue. + +**Azioni:** + +1. Per ogni post, compila spec: + +**Template Post:** + +```markdown +# Post 001 + +**Platform:** LinkedIn +**Format:** Text post +**Pillar:** Education +**Status:** Draft + +## Content + +**Hook:** +{Prima riga che cattura attenzione} + +**Body:** +{Contenuto principale, 3-5 punti o paragrafi brevi} + +**CTA:** +{Call to action: commenta, DM, link in bio} + +## Visual Brief + +**Tipo:** Nessuno / Immagine singola / Carousel +**Descrizione:** {Cosa mostrare} +**Testo su immagine:** {Copy se applicabile} + +## Metadata + +**Hashtag:** #tag1 #tag2 #tag3 +**Tag:** @{company}, @{person} +**Scheduled:** {Data/ora se programmato} +``` + +2. Crea minimo 10 post (mix di pillar e formati) + +**Output:** +- `clients/{client}/social/posts/post_001.md` ... `post_010.md` + +--- + +### Fase 4: Published Log (Opzionale) + +**Obiettivo:** Tracciare post pubblicati. + +**Azioni:** + +1. Dopo publish, aggiorna log: + - Data publish + - Piattaforma + - Post ID + - Performance (se disponibili) + +**Output:** +- `clients/{client}/social/published_log.md` + +--- + +## Output + +| File | Formato | Descrizione | +|------|---------|-------------| +| `clients/{client}/social/social_strategy.md` | Markdown | Strategy per piattaforma | +| `clients/{client}/social/calendar.md` | Markdown | Calendario 4 settimane | +| `clients/{client}/social/posts/*.md` | Markdown | 10+ post in queue | +| `clients/{client}/social/published_log.md` | Markdown | Log publish (opzionale) | + +--- + +## References + +- [content_formats.md](../../references/content_formats.md) — Formati social +- [platform_patterns.md](../../references/platform_patterns.md) — Pattern per piattaforma +- [brand_voice.md](../../references/brand_voice.md) — Tone of voice +- [social_post_spec.md](../../templates/social_post_spec.md) — Template post + +--- + +## Note + +**Edge Cases:** + +- **Nessun visual asset:** Usa visual brief per `agency-visual-generator` +- **Cliente non fornisce feedback:** Procedi con assunzioni documentate +- **Platform nuove:** Adatta strategy (es. TikTok richiede video) + +**Limitazioni:** + +- Publishing richiede approvazione (vedi `publishing_gates.md`) +- Performance tracking richiede accesso analytics +- Post queue va aggiornata regolarmente + +--- + +_Skill generata da framework-translator_ diff --git a/agency-social/references b/agency-social/references new file mode 120000 index 0000000..3dc6b5c --- /dev/null +++ b/agency-social/references @@ -0,0 +1 @@ +../references \ No newline at end of file diff --git a/agency-strategy/SKILL.md b/agency-strategy/SKILL.md new file mode 100644 index 0000000..b3e5e9e --- /dev/null +++ b/agency-strategy/SKILL.md @@ -0,0 +1,206 @@ +--- +name: agency-strategy +description: Definire positioning, messaging e content pillars per un brand o progetto. Usare quando: (1) nuovo cliente/progetto, (2) refresh strategico, (3) definire content strategy, (4) creare messaging house. Output: Positioning statement, messaging house, content pillars, go-to-market plan. +--- + +# Agency Strategy Lead — Positioning e Messaging + +Definisce la direzione strategica di un brand: positioning, messaging e content pillars. + +## Quando Usare + +- **Nuovo cliente:** Creare strategia da zero +- **Rebrand:** Aggiornare positioning esistente +- **Content strategy:** Definire pilastri content +- **Go-to-market:** Pianificare lancio + +--- + +## Input + +| Input | Tipo | Validazione | +|-------|------|-------------| +| `client_path` | string | Percorso client (es. `clients/demo_co/`) | +| `company_profile` | object | Profilo azienda (da knowledge o input) | +| `audience_data` | object | Dati audience (personas, ICP) | +| `competitor_insights` | array | Insight da research competitor | +| `offerings` | array | Lista offerte/servizi | + +--- + +## Processo + +### Fase 1: Analisi Contesto + +**Obiettivo:** Comprendere azienda, audience e mercato. + +**Azioni:** + +1. Leggi `clients/{client}/knowledge/company_profile.md` +2. Leggi `clients/{client}/knowledge/audience.md` (o crea da template) +3. Leggi `clients/{client}/research/competitor_teardowns.md` (se esiste) +4. Identifica: + - Problema principale che l'azienda risolve + - Audience primaria e secondaria + - Differentiatori vs competitor + +**Output intermedi:** +- Note di analisi in `clients/{client}/strategy/analysis_notes.md` + +--- + +### Fase 2: Positioning + +**Obiettivo:** Definire positioning chiaro e differenziante. + +**Azioni:** + +1. Usa formula da `references/strategy_playbook.md`: + > "For [audience] who want [outcome], we provide [solution] unlike [alternative] because [proof]." + +2. Compila ogni elemento: + - **Audience:** Chi è il target primario? + - **Outcome:** Che risultato vogliono? + - **Solution:** Cosa offri? + - **Alternative:** Quali alternative esistono? + - **Proof:** Perché fidarsi? + +3. Scrivi positioning statement finale (1-2 frasi) + +**Output:** +- `clients/{client}/strategy/positioning.md` + +--- + +### Fase 3: Messaging House + +**Obiettivo:** Strutturare messaggi chiave. + +**Azioni:** + +1. **Core message:** Primary promise del brand (1 frase) +2. **Supporting messages:** 3-5 argomenti chiave +3. **Proof points:** Evidence (numeri, risultati, testimonial) +4. **CTA:** Azione desiderata (contact, signup, purchase) + +**Template:** + +```markdown +# Messaging House + +## Core Message +{Promise principale} + +## Supporting Messages +1. {Argomento 1} +2. {Argomento 2} +3. {Argomento 3} + +## Proof Points +- {Proof 1} +- {Proof 2} +- {Proof 3} + +## CTA +{Azione desiderata} +``` + +**Output:** +- `clients/{client}/strategy/messaging.md` + +--- + +### Fase 4: Content Pillars + +**Obiettivo:** Definire 4-6 topic per content strategy. + +**Azioni:** + +1. Identifica 4-6 pillar rilevanti per audience e offering +2. Per ogni pillar, definisci: + - Nome + - Descrizione (1 frase) + - Format suggeriti (da `references/content_formats.md`) + +**Esempio:** + +| Pillar | Descrizione | Format | +|--------|-------------|--------| +| Education | Insegnare concetti chiave | Tutorial, guide, checklist | +| Insights | Opinioni e trend | Opinion post, teardown | +| Case Studies | Dimostrare risultati | Mini-case, before/after | +| Behind the Scenes | Mostrare processo | Process snippet, team | + +**Output:** +- `clients/{client}/strategy/content_pillars.md` + +--- + +### Fase 5: Go-to-Market Plan (Opzionale) + +**Obiettivo:** Pianificare lancio o refresh. + +**Azioni:** + +1. Definisci fasi (pre-lancio, lancio, post-lancio) +2. Per ogni fase: + - Canali da usare + - Content da produrre + - Timeline +3. Identifica KPI di successo + +**Output:** +- `clients/{client}/strategy/go_to_market.md` + +--- + +## Output + +| File | Formato | Descrizione | +|------|---------|-------------| +| `clients/{client}/strategy/positioning.md` | Markdown | Positioning statement | +| `clients/{client}/strategy/messaging.md` | Markdown | Messaging house | +| `clients/{client}/strategy/content_pillars.md` | Markdown | 4-6 content pillars | +| `clients/{client}/strategy/go_to_market.md` | Markdown | GTM plan (opzionale) | + +--- + +## Esempio Output + +```markdown +# Positioning — Demo Co + +For **founders e PM B2B** che vogliono **comunicare valore in modo chiaro**, +forniamo **strategy, design e content** a differenza di **agency generaliste** +perché **specializzati in clarity-first e conversioni**. +``` + +--- + +## References + +- [strategy_playbook.md](../../references/strategy_playbook.md) — Framework positioning +- [copy_frameworks.md](../../references/copy_frameworks.md) — Framework copy +- [content_formats.md](../../references/content_formats.md) — Formati content +- [audience_personas.md](../../references/audience_personas.md) — Template personas +- [brand_voice.md](../../references/brand_voice.md) — Tone of voice + +--- + +## Note + +**Edge Cases:** + +- **Nessun dato audience:** Crea personas da interviste o assumi basandoti su offering +- **Competitor sconosciuti:** Esegui research veloce o usa knowledge generale +- **Offering complesso:** Semplifica in 3 categorie max (entry/core/premium) + +**Limitazioni:** + +- Richiede input base su azienda e audience +- Research competitor approfondito richiede `agency-research` +- Go-to-market plan richiede dati di canale e budget + +--- + +_Skill generata da framework-translator_ diff --git a/agency-strategy/references b/agency-strategy/references new file mode 120000 index 0000000..3dc6b5c --- /dev/null +++ b/agency-strategy/references @@ -0,0 +1 @@ +../references \ No newline at end of file diff --git a/agency-ux-copy/SKILL.md b/agency-ux-copy/SKILL.md new file mode 100644 index 0000000..494e918 --- /dev/null +++ b/agency-ux-copy/SKILL.md @@ -0,0 +1,253 @@ +--- +name: agency-ux-copy +description: Progettare sitemap e scrivere copy per pagine web conversion-oriented. Usare quando: (1) nuovo sito web, (2) rewrite copy esistente, (3) ottimizzare conversioni. Output: Sitemap, page structures, copy V1, SEO notes. +--- + +# Agency UX Copy Architect — Sitemap e Copy + +Progetta la struttura del sito e scrive copy chiaro e conversion-oriented. + +## Quando Usare + +- **Nuovo sito:** Creare sitemap e copy da zero +- **Website refresh:** Riscrivere copy esistente +- **Landing page:** Pagina campaign specifica +- **Conversion optimization:** Migliorare CTA e flow + +--- + +## Input + +| Input | Tipo | Validazione | +|-------|------|-------------| +| `client_path` | string | Percorso client | +| `strategy_docs` | array | Positioning, messaging, content pillars | +| `design_layouts` | array | Page layouts (da design system) | +| `seo_keywords` | array | Keyword seed (se disponibili) | +| `page_list` | array | Pagine richieste (opzionale) | + +--- + +## Processo + +### Fase 1: Sitemap + +**Obiettivo:** Definire architettura informazione. + +**Azioni:** + +1. Identifica pagine necessarie: + - Obbligatorie: Home, About, Services, Contact + - Opzionali: Case Studies, Blog, Resources + +2. Per ogni pagina, definisci: + - Nome + - Scopo/Intent + - CTA primaria + - Note SEO + +**Template:** + +```markdown +# Sitemap + +## Homepage +- **Intent:** Presentare value prop e guidare a CTA +- **CTA:** "Prenota call" +- **SEO:** Keyword primaria + secondary + +## Services +- **Intent:** Descrivere offerte +- **CTA:** "Richiedi preventivo" +- **SEO:** "servizi {settore}" + +## About +- **Intent:** Costruire trust +- **CTA:** "Conosci il team" +- **SEO:** "chi siamo {settore}" + +## Contact +- **Intent:** Facilitare contatto +- **CTA:** "Invia messaggio" +- **SEO:** "contatti {settore}" +``` + +**Output:** +- `clients/{client}/website/sitemap.md` + +--- + +### Fase 2: Page Skeletons + +**Obiettivo:** Creare struttura per ogni pagina. + +**Azioni:** + +1. Per ogni pagina in sitemap, definisci: + - H1 (headline principale) + - H2/H3 (sezioni) + - Hero section (headline, sub, CTA) + - Content sections (ordine logico) + - CTA sections (mid-page, footer) + - FAQ (se applicabile) + +2. Usa pattern da references: + - `hero_sections.md` per hero + - `conversion_patterns.md` per CTA + - `design_patterns.md` per layout + +**Template:** + +```markdown +# Homepage + +## Hero +- H1: {Headline} +- Sub: {Supporting copy} +- CTA: {Testo CTA} +- Proof: {Proof chips} + +## Section 1: Services Overview +- H2: {Titolo} +- Content: {Card grid con 3-6 servizi} + +## Section 2: Proof +- H2: {Titolo} +- Content: {Logo wall o testimonial} + +## Section 3: CTA Finale +- H2: {Titolo} +- CTA: {Testo CTA} +``` + +**Output:** +- `clients/{client}/website/pages/{page_name}.md` + +--- + +### Fase 3: Copywriting + +**Obiettivo:** Scrivere copy per ogni sezione. + +**Azioni:** + +1. **Hero copy:** + - Headline: 6-12 parole, outcome-focused + - Sub: 1-2 frasi, meccanismo + proof + - CTA: Verbo chiaro ("Prenota", "Richiedi") + +2. **Section copy:** + - Intro: 1-2 frasi + - Bullets: 3-5 punti chiave + - Microcopy: Label, button text + +3. **Usa framework da `references/copy_frameworks.md`:** + - PAS (Problem-Agitate-Solve) + - AIDA (Attention-Interest-Desire-Action) + - Before-After-Bridge + +4. **Applica `references/conversion_patterns.md`:** + - 1 CTA primaria per pagina + - Ripeti CTA 2-3 volte + - Friction reducers vicino a form + +**Regole copy:** +- Parole semplici, niente gergo +- Frasi corte +- Focus su benefici, non features +- Proof ovunque possibile + +**Output:** +- Copy completo in `clients/{client}/website/pages/*.md` + +--- + +### Fase 4: SEO Metadata + +**Obiettivo:** Ottimizzare on-page SEO. + +**Azioni:** + +1. Per ogni pagina, compila: + - Title tag (50-60 caratteri) + - Meta description (150-160 caratteri) + - H1 (unico per pagina) + - Keyword primaria + - Internal linking notes + +**Template:** + +```markdown +## SEO Metadata — Homepage + +- **Title:** {Keyword primaria} | {Brand Name} +- **Meta description:** {Copy con keyword, 150-160 char} +- **H1:** {Headline hero} +- **Keyword primaria:** {keyword} +- **Internal links:** → Services, → Case Studies, → Contact +``` + +**Output:** +- `clients/{client}/website/seo/meta.md` + +--- + +### Fase 5: QA Copy + +**Obiettivo:** Verificare qualità copy. + +**Azioni:** + +1. Leggi tutto il copy ad alta voce +2. Verifica: + - Chiarezza (niente ambiguità) + - Coerenza tono (brand voice) + - CTA chiare e visibili + - Proof presente + - Niente gergo o fuffa + +3. Compila QA checklist + +**Output:** +- `clients/{client}/website/qa/qa_website.md` + +--- + +## Output + +| File | Formato | Descrizione | +|------|---------|-------------| +| `clients/{client}/website/sitemap.md` | Markdown | Architettura sito | +| `clients/{client}/website/pages/*.md` | Markdown | Copy pagine | +| `clients/{client}/website/seo/meta.md` | Markdown | SEO metadata | +| `clients/{client}/website/qa/qa_website.md` | Markdown | QA checklist | + +--- + +## References + +- [copy_frameworks.md](../../references/copy_frameworks.md) — Framework copy +- [conversion_patterns.md](../../references/conversion_patterns.md) — CTA e conversioni +- [hero_sections.md](../../references/hero_sections.md) — Hero patterns +- [navigation_patterns.md](../../references/navigation_patterns.md) — IA patterns +- [brand_voice.md](../../references/brand_voice.md) — Tone of voice + +--- + +## Note + +**Edge Cases:** + +- **Nessuna keyword SEO:** Crea seed list ragionata basata su offering +- **Cliente non fornisce info:** Usa assunzioni documentate in decision log +- **Copy esistente da rewrite:** Mantieni struttura, migliora chiarezza e CTA + +**Limitazioni:** + +- Copywriting efficace richiede comprensione profonda del cliente +- SEO avanzata richiede keyword research dedicata +- Test A/B richiede implementazione tecnica + +--- + +_Skill generata da framework-translator_ diff --git a/agency-ux-copy/references b/agency-ux-copy/references new file mode 120000 index 0000000..3dc6b5c --- /dev/null +++ b/agency-ux-copy/references @@ -0,0 +1 @@ +../references \ No newline at end of file diff --git a/agency-visual-generator/SKILL.md b/agency-visual-generator/SKILL.md new file mode 100644 index 0000000..2bf8577 --- /dev/null +++ b/agency-visual-generator/SKILL.md @@ -0,0 +1,247 @@ +--- +name: agency-visual-generator +description: Generare asset visuali (card, carousel, thumbnail) per social e YouTube basati su content approvato e style guide. Usare quando: (1) post social needs visual, (2) YouTube thumbnail, (3) carousel Instagram/LinkedIn. Output: Asset PNG/webp in cartella client, QA visual compilato. +--- + +# Agency Visual Generator — Asset Visuali + +Genera asset visuali platform-ready basati su content approvato e style guide. + +## Quando Usare + +- **Social post:** Creare visual per post in queue +- **YouTube:** Thumbnail per video +- **Carousel:** Instagram/LinkedIn multi-slide +- **Brand assets:** Immagini coordinate per cliente + +--- + +## Input + +| Input | Tipo | Validazione | +|-------|------|-------------| +| `client_path` | string | Percorso client | +| `content_files` | array | Post o script che richiedono visual | +| `style_guide` | object | Style guide cliente (colori, font) | +| `asset_type` | string | "card" / "carousel" / "thumbnail" | +| `platform` | string | "linkedin" / "instagram" / "youtube" | + +--- + +## Processo + +### Fase 1: Analisi Richiesta + +**Obiettivo:** Capire che asset serve. + +**Azioni:** + +1. Leggi content file (post o script) +2. Identifica: + - Piattaforma target + - Tipo asset (card, carousel, thumbnail) + - Copy da includere (hook, CTA) + - Visual brief (se presente) + +3. Verifica aspect ratio richiesto: + - **LinkedIn card:** 1200x627px (1.91:1) + - **Instagram carousel:** 1080x1350px (4:5) + - **YouTube thumbnail:** 1280x720px (16:9) + +--- + +### Fase 2: Style Guide Check + +**Obiettivo:** Caricare o creare style guide. + +**Azioni:** + +1. Cerca `clients/{client}/design/style_guide.md` o `clients/{client}/assets/brand/style_guide.md` + +2. Se esiste: + - Carica colori (hex) + - Carica font (family, weights) + - Carica logo (se disponibile) + +3. Se NON esiste: + - Crea draft style guide in `clients/{client}/assets/brand/style_guide.md` + - Chiedi approvazione prima di procedere + +**Template Style Guide:** + +```markdown +# Style Guide — {Client} + +## Colors +- Primary: {hex} +- Secondary: {hex} +- Text: {hex} +- Background: {hex} + +## Fonts +- Primary: {font-family} +- Secondary: {font-family} + +## Logo +- URL: {logo_url} +- Usage: {note} +``` + +--- + +### Fase 3: Compilazione JSON Template + +**Obiettivo:** Preparare prompt per generazione. + +**Azioni:** + +1. Carica template appropriato da `core/templates/visual/`: + - `linkedin_card.json` + - `instagram_carousel.json` + - `youtube_thumbnail.json` + +2. Compila campi: + - `text` (headline, sub, CTA) + - `colors` (da style guide) + - `fonts` (da style guide) + - `logo` (se disponibile) + - `imagery` (descrizione visual) + +**Esempio YouTube Thumbnail JSON:** + +```json +{ + "format": "youtube_thumbnail", + "dimensions": { "width": 1280, "height": 720 }, + "text": { + "headline": "3 Errori Comuni", + "sub": "Che Tutti Fanno in {Settore}", + "cta": "GUARDA ORA" + }, + "colors": { + "background": "#1a1a2e", + "text": "#ffffff", + "accent": "#e94560" + }, + "fonts": { + "headline": "Inter Bold 72px", + "sub": "Inter Regular 36px" + }, + "imagery": "Foto persona sorpresa, lato destro, sfondo sfocato" +} +``` + +--- + +### Fase 4: Generazione Immagine + +**Obiettivo:** Generare asset con tool configured. + +**Azioni:** + +1. Usa tool di generazione immagini (OpenClaw integration o servizio esterno) +2. Passa JSON template come prompt strutturato +3. Genera immagine PNG/webp +4. Salva in: + - `clients/{client}/assets/social/{post_id}.png` + - `clients/{client}/assets/youtube/thumbnails/{ep_id}.png` + - `clients/{client}/assets/social/carousels/{id}/slide_01.png`, etc. + +5. Aggiorna content file con `asset_path` + +--- + +### Fase 5: Visual QA + +**Obiettivo:** Verificare qualità asset. + +**Azioni:** + +1. Usa checklist da `references/qa_visual.md`: + +**Readability:** +- [ ] Text readable at mobile size (320px) +- [ ] Strong contrast text/background +- [ ] Headline <= 8 words + +**Brand:** +- [ ] Colors match style guide +- [ ] Fonts match style guide +- [ ] No off-brand elements + +**Message:** +- [ ] One clear idea per image +- [ ] Visual supports hook/CTA +- [ ] No misleading visuals + +**Technical:** +- [ ] Correct aspect ratio +- [ ] No artifacts / broken text +- [ ] Safe margins for UI overlays + +2. Registra risultato in `clients/{client}/assets/qa/qa_visual.md` + +**Template:** + +```markdown +# QA Visual — {Asset Name} + +**Data:** 2026-03-09 +**Asset:** {path} + +## Checklist + +| Categoria | Check | Risultato | +|-----------|-------|-----------| +| Readability | Text mobile-size | ✅ Pass | +| Readability | Contrast | ✅ Pass | +| Brand | Colors | ✅ Pass | +| Brand | Fonts | ⚠️ Fallback usato | +| Message | One idea | ✅ Pass | +| Technical | Aspect ratio | ✅ Pass | + +## Esito + +**Status:** APPROVED / NEEDS_FIX + +**Note:** {Eventuali fix richiesti} +``` + +--- + +## Output + +| File | Formato | Descrizione | +|------|---------|-------------| +| `clients/{client}/assets/social/*.png` | PNG/webp | Card social | +| `clients/{client}/assets/social/carousels/*/slide_*.png` | PNG | Carousel slides | +| `clients/{client}/assets/youtube/thumbnails/*.png` | PNG | YouTube thumbnail | +| `clients/{client}/assets/qa/qa_visual.md` | Markdown | QA checklist | + +--- + +## References + +- [qa_visual.md](../../references/qa_visual.md) — QA checklist +- [platform_patterns.md](../../references/platform_patterns.md) — Pattern per piattaforma +- [publishing_gates.md](../../references/publishing_gates.md) — Gate pre-publish + +--- + +## Note + +**Edge Cases:** + +- **Nessuno style guide:** Crea draft e chiedi approvazione +- **Testo troppo lungo:** Adatta copy (max 8 parole headline) +- **Logo mancante:** Procedi senza, segnala nel QA + +**Limitazioni:** + +- Richiede integrazione tool generazione immagini +- Quality varia in base a prompt e tool +- Iterazioni possono essere necessarie per perfezionare + +--- + +_Skill generata da framework-translator_ diff --git a/agency-visual-generator/references b/agency-visual-generator/references new file mode 120000 index 0000000..3dc6b5c --- /dev/null +++ b/agency-visual-generator/references @@ -0,0 +1 @@ +../references \ No newline at end of file diff --git a/agency-youtube/SKILL.md b/agency-youtube/SKILL.md new file mode 100644 index 0000000..8560487 --- /dev/null +++ b/agency-youtube/SKILL.md @@ -0,0 +1,246 @@ +--- +name: agency-youtube +description: Creare YouTube strategy, calendario e script retention-first. Usare quando: (1) nuovo canale YouTube, (2) pianificare content video, (3) scrivere script. Output: YouTube strategy, calendario, 2+ script completi con thumbnail brief. +--- + +# Agency YouTube Producer — Strategy e Script + +Strategia YouTube, calendario e script orientati a retention. + +## Quando Usare + +- **Nuovo canale:** Impostare strategy da zero +- **Content planning:** Pianificare episodi +- **Script writing:** Scrivere script retention-first +- **Channel refresh:** Aggiornare approccio + +--- + +## Input + +| Input | Tipo | Validazione | +|-------|------|-------------| +| `client_path` | string | Percorso client | +| `content_pillars` | array | Da strategy | +| `brand_voice` | object | Tone of voice | +| `target_audience` | object | Audience YouTube | +| `video_frequency` | string | Frequenza upload (es. "1x settimana") | + +--- + +## Processo + +### Fase 1: YouTube Strategy + +**Obiettivo:** Definire approccio al canale. + +**Azioni:** + +1. **Channel positioning:** + - Scopo del canale + - Audience target + - Value proposition unica + +2. **Format/Serie:** + - Identifica 2-4 format ricorrenti + - Per ogni formato: nome, descrizione, frequenza + +3. **KPI:** + - Views + - Watch time / retention + - Subscribers + - Engagement (comments, likes) + +**Template:** + +```markdown +# YouTube Strategy + +## Channel Positioning +- **Scopo:** {Perché esiste il canale} +- **Audience:** {Chi guarderà i video} +- **Value Prop:** {Perché guardare questo canale} + +## Format / Serie + +### Format 1: {Nome} +- **Descrizione:** {Cosa è} +- **Frequenza:** {Ogni quanto} +- **Durata target:** {Minuti} + +### Format 2: {Nome} +... + +## KPI Target +- Views/episodio: {target} +- Retention media: {target}% +- Subscriber growth: {target}/mese +``` + +**Output:** +- `clients/{client}/youtube/youtube_strategy.md` + +--- + +### Fase 2: Calendario Episodi + +**Obiettivo:** Pianificare 4-8 episodi. + +**Azioni:** + +1. Crea calendario con: + - Episodio # + - Titolo working + - Formato + - Pillar + - Status (idea/script/filmed/edited/published) + - Data target publish + +**Template:** + +```markdown +# YouTube Calendar + +| Ep # | Titolo | Formato | Pillar | Status | Data Target | +|------|--------|---------|--------|--------|-------------| +| 001 | "3 errori comuni in {settore}" | Tutorial | Education | Script | 2026-03-15 | +| 002 | "Case Study: {Cliente}" | Case Study | Proof | Idea | 2026-03-22 | +| 003 | "Come {risultato} in 5 step" | Tutorial | Education | Script | 2026-03-29 | +``` + +**Output:** +- `clients/{client}/youtube/calendar.md` + +--- + +### Fase 3: Script Writing + +**Obiettivo:** Scrivere 2+ script completi retention-first. + +**Azioni:** + +1. Usa struttura da `references/youtube_script_framework.md`: + - 0-10s: Hook (promise + curiosity) + - 10-25s: Credibility (why listen) + - 25-60s: Problem definition + - Main: 3-5 chapters con open loops + - End: Summary + CTA + +2. Per ogni script, compila: + +**Template:** + +```markdown +# Episode 001 — {Titolo} + +**Format:** {Tutorial/Teardown/Case Study} +**Durata target:** {minuti} +**Status:** Draft + +## Hook (0-10s) +{Promise + curiosity. Esempio: "In questo video ti mostro come X in Y tempo. La maggior parte sbaglia Z..."} + +## Credibility (10-25s) +{Perché ascoltarti. Esempio: "Ho aiutato 50+ clienti a fare X..."} + +## Problem (25-60s) +{Definisci problema relatable. Esempio: "Se sei qui, probabilmente stai lottando con..."} + +## Chapter 1: {Titolo} +- Punto chiave 1 +- Esempio concreto +- Mini-recap + +## Chapter 2: {Titolo} +... + +## Chapter 3: {Titolo} +... + +## Summary + CTA +- Recap punti chiave +- CTA: "Iscriviti", "Commenta", "Guarda il prossimo video" + +## Thumbnail Brief + +**Titolo su thumbnail:** {3-5 parole max} +**Visual:** {Cosa mostrare} +**Colori:** {Palette} + +## Metadata + +**Titolo video (3 opzioni):** +1. {Opzione 1} +2. {Opzione 2} +3. {Opzione 3} + +**Descrizione:** +{Copy descrizione YouTube con link e timestamp} + +**Tags:** {tag1, tag2, tag3} + +**Chapters:** +0:00 Intro +0:45 Chapter 1 +2:30 Chapter 2 +... +``` + +**Output:** +- `clients/{client}/youtube/scripts/ep_001.md`, `ep_002.md`, etc. + +--- + +### Fase 4: Published Log (Opzionale) + +**Obiettivo:** Tracciare video pubblicati. + +**Azioni:** + +1. Dopo publish, aggiorna: + - Data publish + - Video URL + - Performance (views, retention, etc.) + +**Output:** +- `clients/{client}/youtube/published_log.md` + +--- + +## Output + +| File | Formato | Descrizione | +|------|---------|-------------| +| `clients/{client}/youtube/youtube_strategy.md` | Markdown | Strategy canale | +| `clients/{client}/youtube/calendar.md` | Markdown | Calendario episodi | +| `clients/{client}/youtube/scripts/*.md` | Markdown | 2+ script completi | +| `clients/{client}/youtube/published_log.md` | Markdown | Log publish (opzionale) | + +--- + +## References + +- [youtube_script_framework.md](../../references/youtube_script_framework.md) — Struttura script +- [content_formats.md](../../references/content_formats.md) — Formati YouTube +- [brand_voice.md](../../references/brand_voice.md) — Tone of voice +- [youtube_script.md](../../templates/youtube_script.md) — Template script + +--- + +## Note + +**Edge Cases:** + +- **Nessun dato audience:** Usa personas da strategy o assumi basandoti su content pillars +- **Cliente non vuole video:** Focus su script per voiceover + B-roll +- **Thumbnail:** Usa brief per `agency-visual-generator` + +**Limitazioni:** + +- Upload video richiede tool esterno o integrazione YouTube API +- Performance tracking richiede YouTube Studio access +- Script efficaci richiedono pratica e testing + +--- + +_Skill generata da framework-translator_ diff --git a/agency-youtube/references b/agency-youtube/references new file mode 120000 index 0000000..3dc6b5c --- /dev/null +++ b/agency-youtube/references @@ -0,0 +1 @@ +../references \ No newline at end of file diff --git a/references/audience_personas.md b/references/audience_personas.md new file mode 100644 index 0000000..3bd3d3c --- /dev/null +++ b/references/audience_personas.md @@ -0,0 +1,35 @@ +# Audience Personas + +_Framework: agency_v3_1 | Estratto: 2026-03-09_ +_Usato da: agency-strategy, agency-research_ + +## Sommario + +Template per definire ICP e personas. + +--- + +## Persona Template + +| Campo | Descrizione | +|-------|-----------| +| **Nome** | Nome fittizio della persona | +| **Ruolo/Contesto** | Lavoro, settore, situazione | +| **Obiettivi** | Cosa vuole raggiungere | +| **Pain Points** | Problemi, frustrazioni | +| **Trigger di Acquisto** | Cosa li spinge a cercare soluzioni | +| **Obiezioni** | Dubbi, barriere all'acquisto | +| **Canali** | Dove si informano (social, search, etc.) | +| **Linguaggio** | Parole che usano (verbatim) | + +--- + +## Note + +- Compilare 2-4 personas per cliente +- Usare linguaggio reale (da interviste, recensioni, social) +- Aggiornare dopo research competitor + +--- + +_Reference generato da framework-translator_ diff --git a/references/brand_voice.md b/references/brand_voice.md new file mode 100644 index 0000000..74670d4 --- /dev/null +++ b/references/brand_voice.md @@ -0,0 +1,49 @@ +# Brand Voice + +_Framework: agency_v3_1 | Estratto: 2026-03-09_ +_Usato da: agency-strategy, agency-social, agency-youtube_ + +## Sommario + +Linee guida tono di voce per web e social. + +--- + +## Attributi (scegline 3-5) + +- Professionale ma umano +- Diretto +- Ottimista realistico +- Tecnico solo quando serve +- Ironico (leggero) + +--- + +## Dos & Don'ts + +### Do +- Frasi brevi, verbi attivi +- Spiegazioni con esempi +- CTA chiare + +### Don't +- Superlativi vuoti ("il migliore") +- Fuffa motivazionale +- Troppo slang se non coerente + +--- + +## Micro-linee Guida + +**Emoji:** +- (Sì/No) + regole specifiche + +**Uso del "tu" vs "voi":** +- Definire preferenza + +**Punteggiatura:** +- Es. niente !!! + +--- + +_Reference generato da framework-translator_ diff --git a/references/case_study_structures.md b/references/case_study_structures.md new file mode 100644 index 0000000..41692d3 --- /dev/null +++ b/references/case_study_structures.md @@ -0,0 +1,57 @@ +# Case Study Structures + +_Framework: agency_v3_1 | Estratto: 2026-03-09_ +_Usato da: agency-strategy, agency-ux-copy_ + +## Sommario + +Template per case study che dimostrano competenza e riducono rischio percepito. + +--- + +## Case Study Skeleton (Consigliato) + +### 1) Snapshot +- Cliente / settore +- Obiettivo +- Servizi +- Risultato chiave (1-3 metriche) + +### 2) Problema +- Contesto +- Vincoli +- Perché era difficile + +### 3) Approccio +- Strategia +- Decisioni chiave (3-5) + +### 4) Soluzione +- Cosa è stato creato +- Highlights + +### 5) Risultati +- Metriche (se disponibili) +- Output qualitativi (es. "riduzione frizione") + +### 6) Learnings +- Cosa rifaresti +- Cosa evitare + +### 7) CTA +- "Vuoi un progetto simile?" + +--- + +## Se Non Hai Metriche + +**Usa:** +- Outcomes qualitativi +- Deliverable concreti +- Quote cliente + +**Indica:** "Metriche non disponibili" (trasparenza). + +--- + +_Reference generato da framework-translator_ diff --git a/references/content_formats.md b/references/content_formats.md new file mode 100644 index 0000000..f05de45 --- /dev/null +++ b/references/content_formats.md @@ -0,0 +1,75 @@ +# Content Formats + +_Framework: agency_v3_1 | Estratto: 2026-03-09_ +_Usato da: agency-social, agency-youtube_ + +## Sommario + +Formati content per social e YouTube, organizzati per rubriche. + +--- + +## Content Pillars → Formats + +Ogni pillar dovrebbe produrre 3-5 format ricorrenti (rubriche). + +--- + +## Social Formats (Agency) + +### 1) Breakdown (analisi di un sito/campagna) +- Hook: "3 cose che funzionano / non funzionano" +- Bullets +- Takeaway + +### 2) Mini-case (prima/dopo) +- Contesto +- Intervento +- Risultato (anche qualitativo) + +### 3) Opinion / POV +- Tesi chiara +- 2-3 argomenti +- CTA: commenta / DM + +### 4) Process Snippet +- Come lavorate +- Step e strumenti + +### 5) Toolkit / Checklist +- Template +- Lista rapida + +**Regola:** 1 CTA semplice per post. + +--- + +## YouTube Formats + +### A) Tutorial (How-to) +- Promise in hook +- Step-by-step +- Recap + CTA + +### B) Teardown (competitor/site review) +- Framework +- Score +- Recommendations + +### C) Case Study Narrative +- Problema +- Viaggio +- Risultato +- Lezioni + +--- + +## YouTube Retention Tips + +- Hook <10s +- Pattern interrupts ogni 20-40s (grafica, esempio, cambio ritmo) +- Chapters chiari + +--- + +_Reference generato da framework-translator_ diff --git a/references/conversion_patterns.md b/references/conversion_patterns.md new file mode 100644 index 0000000..69408d0 --- /dev/null +++ b/references/conversion_patterns.md @@ -0,0 +1,73 @@ +# Conversion Patterns + +_Framework: agency_v3_1 | Estratto: 2026-03-09_ +_Usato da: agency-ux-copy, agency-strategy_ + +## Sommario + +CTA, forms e friction reduction per conversioni. + +--- + +## CTA Hierarchy + +- 1 CTA primaria per pagina +- 1 CTA secondaria (link-style) +- Ripetere CTA primaria 2-3 volte (hero, mid, footer) + +--- + +## Contact Section Patterns + +### A) Simple Form +- Nome, email, messaggio (max 3-4 campi) + +### B) Calendly / Booking +- Utile per agency; includere alternative (email) per chi non vuole booking + +### C) Project Brief Form +- Solo se necessario; meglio a step + +**Regole:** +- Meno campi = più conversione (di solito) +- Indicare tempi di risposta (es. 24-48h) +- Privacy microcopy vicino al submit + +--- + +## Lead Magnet (Optional) + +**Quando usarlo:** +- Se vuoi "consideration" lunga + +**Esempi:** +- Checklist +- Mini guida +- Template + +--- + +## Friction Reducers (Microcopy) + +- "Nessuno spam. Rispondiamo entro 48h." +- "Puoi anche scriverci a..." +- "Budget indicativo? Va bene anche una range." + +--- + +## Conversion Blocks + +- "Process" (3-5 step) +- "What you get" (deliverables) +- "FAQ" (obiezioni) + +--- + +## Anti-pattern + +- CTA vaghe ("Scopri di più" ovunque) +- Form lunghissimi senza motivazione + +--- + +_Reference generato da framework-translator_ diff --git a/references/copy_frameworks.md b/references/copy_frameworks.md new file mode 100644 index 0000000..7df6ee2 --- /dev/null +++ b/references/copy_frameworks.md @@ -0,0 +1,71 @@ +# Copy Frameworks + +_Framework: agency_v3_1 | Estratto: 2026-03-09_ +_Usato da: agency-strategy, agency-ux-copy_ + +## Sommario + +Framework copywriting clarity-first per web e social. + +--- + +## Regole Generali + +- Parole semplici > gergo +- Frasi corte quando possibile +- Evitare claim assoluti non verificabili +- Scrivere per "scan" (titoli, bullets, bold con parsimonia) + +--- + +## PAS (Problem-Agitate-Solve) + +**Struttura:** +- **Problem:** descrivi il problema del cliente +- **Agitate:** conseguenze se non risolto +- **Solve:** come lo risolvi + +**Ottimo per:** +- Hero sub-copy +- Section intro + +--- + +## AIDA (Attention-Interest-Desire-Action) + +**Ottimo per:** +- Landing page +- Sales section + +--- + +## Before-After-Bridge + +**Struttura:** +- **Before:** situazione attuale +- **After:** situazione desiderata +- **Bridge:** come ci arrivi (process) + +--- + +## Microcopy (Forms/Buttons) + +**Button:** +- Usare verbi chiari ("Prenota call", "Richiedi info") + +**Error:** +- Spiegare cosa fare + +**Privacy:** +- Rassicurare + +--- + +## Tone Guardrails + +- Preferire assertività tranquilla (non hype) +- Evitare frasi "AI-ish" (troppo generiche) + +--- + +_Reference generato da framework-translator_ diff --git a/references/design_patterns.md b/references/design_patterns.md new file mode 100644 index 0000000..c286adb --- /dev/null +++ b/references/design_patterns.md @@ -0,0 +1,110 @@ +# Design Patterns + +_Framework: agency_v3_1 | Estratto: 2026-03-09_ +_Usato da: agency-creative-director, agency-design-system, agency-ux-copy_ + +## Sommario + +Pattern UI riusabili per siti agency/services. Strutture, non stile. + +--- + +## Card Grid (Services / Features) + +**Quando usarlo:** +- Overview servizi +- Differentiatori +- Step del processo + +**Regole:** +- Max 6 card desktop, 3-4 mobile +- Titolo breve + payoff 1 riga + micro-CTA +- Icone solo se aggiungono semantica (non decorative) + +**Varianti:** +- Icon + title + 2 bullets +- Number + title + paragraph (per process) +- Split card (testo + mini proof) + +--- + +## Split Layout (Text + Visual) + +**Quando usarlo:** +- Spiegare un concetto o metodo +- Mostrare case study teaser + +**Regole:** +- Testo a sinistra per lingue LTR (scansione naturale) +- 1 solo focus visual (non collage) +- Includere 1 proof nello stesso blocco (numero, logo, quote) + +--- + +## Section Header (Headline + Support) + +**Pattern:** +- Overline (categoria) +- Headline (promessa) +- Supporting copy (beneficio concreto) +- Optional: inline CTA + +**Regole:** +- Headline: 6-12 parole +- Supporting: 1-2 frasi, senza gergo + +--- + +## Logo Wall (Credibility) + +**Quando usarlo:** +- Subito dopo hero o dopo services + +**Regole:** +- Max 12 loghi visibili (se più, carousel o "view all") +- Testo di contesto (es. "Trusted by" o "We worked with") +- Evitare loghi non autorizzati + +--- + +## Testimonial Block + +**Varianti:** +- Quote singola "hero testimonial" +- Grid di 3 testimonial +- Testimonial + risultato (numero) + +**Regole:** +- Migliore se contiene un risultato specifico +- Includere nome/ruolo/azienda quando possibile +- Se anonimo: spiegare perché (settore sensibile) + +--- + +## FAQ (Objections) + +**Quando usarlo:** +- Prima della CTA finale +- Su services e contact + +**Regole:** +- 5-8 domande +- Domande reali (prezzo, tempi, processo, revisioni) +- Risposte brevi e pratiche + +--- + +## Footer (Actionable) + +**Include:** +- CTA compatta +- Contatti chiari +- Link legali +- Social (se utili) + +**Regola:** +- Footer deve "chiudere" il funnel, non solo link. + +--- + +_Reference generato da framework-translator_ diff --git a/references/hero_sections.md b/references/hero_sections.md new file mode 100644 index 0000000..dedca57 --- /dev/null +++ b/references/hero_sections.md @@ -0,0 +1,84 @@ +# Hero Sections + +_Framework: agency_v3_1 | Estratto: 2026-03-09_ +_Usato da: agency-creative-director, agency-ux-copy_ + +## Sommario + +Pattern e formule per hero section efficaci. Deve rispondere in 5 secondi. + +--- + +## Hero Checklist (5 secondi) + +L'hero deve rispondere a: +1. Cosa fai +2. Per chi +3. Che risultato dai +4. Perché fidarsi +5. Qual è la prossima azione + +--- + +## Hero Formula (Services / Agency) + +**Headline:** Outcome + Audience +**Sub:** Come lo fai (meccanismo) + proof +**CTA primaria:** "Prenota call" / "Richiedi preventivo" / "Vedi lavori" +**CTA secondaria:** "Guarda casi studio" / "Scarica guida" + +**Esempi (struttura, non testo finale):** +- "Brand e siti che convertono per [audience]" +- "Strategia, design e contenuti per crescere con coerenza" + +--- + +## Hero Layouts + +### A) Split (text + visual) +- Consigliato per studi: pulito, conversion-friendly + +### B) Centered minimal +- Consigliato se il messaggio è fortissimo e semplice + +### C) Proof-first +- Headline + 3 proof chip (numeri/risultati) + CTA + +--- + +## Proof Chips (sotto CTA) + +Esempi: +- "+120 progetti" +- "Da 7 anni" +- "Tempo medio: 4-6 settimane" +- "Specializzati in [niche]" + +**Regola:** Meglio 1-3 chip concreti che 6 generici. + +--- + +## Hero Visuals + +**Scelte consigliate:** +- Fotografia editoriale (autentica) +- Mockup selettivo (1-2, non griglia infinita) +- Abstract/3D coerente (non stock casuale) + +**Anti-pattern:** +- "Team smiling in office" stock +- Collage confusi +- Troppo testo dentro l'immagine + +--- + +## Above-the-Fold Checklist + +- [ ] Value prop chiara +- [ ] CTA visibile +- [ ] Proof presente +- [ ] Nessun rumore (nav troppo densa, troppi link) + +--- + +_Reference generato da framework-translator_ diff --git a/references/layout_systems.md b/references/layout_systems.md new file mode 100644 index 0000000..3a7fa90 --- /dev/null +++ b/references/layout_systems.md @@ -0,0 +1,68 @@ +# Layout Systems + +_Framework: agency_v3_1 | Estratto: 2026-03-09_ +_Usato da: agency-design-system, agency-creative-director_ + +## Sommario + +Grid, spacing, density per coerenza e ritmo verticale. + +--- + +## Grid (Web) + +**Desktop:** 12 colonne (o 2/3/4 macro colonne) +**Tablet:** 8 colonne +**Mobile:** 4 colonne (stack verticale) + +**Regola pratica:** +- Usa una "content column" leggibile (non full-width testo) + +--- + +## Container Widths + +**Linee guida:** +- Max content width: 1100-1200px +- Reading width per paragrafi: 60-80 caratteri + +--- + +## Spacing System + +**Scala modulare preferita:** 4/8/16/24/32/48/64 + +**Sezioni:** +- Padding top/bottom minimo: 64-96px desktop, 40-64px mobile +- Separare sezioni con whitespace, non linee ovunque + +--- + +## Density Modes + +| Mode | Descrizione | Uso | +|------|-----------|-----| +| Airy | Più spazio, premium feel | Brand luxury, high-end | +| Balanced | Equilibrio | Maggior parte dei casi | +| Dense | Compatto | Pagine data-heavy | + +**Regola:** Scegli 1 density mode dominante e mantienilo. + +--- + +## Vertical Rhythm + +- Headline → supporting → content → CTA: sempre con spacing prevedibile +- Evitare "salti" casuali + +--- + +## Responsive Heuristics + +- Non "ridurre" tutto: spesso serve "stackare" e cambiare ordine +- CTA sempre tappabile e visibile +- Immagini: evitare crop che elimina il soggetto + +--- + +_Reference generato da framework-translator_ diff --git a/references/navigation_patterns.md b/references/navigation_patterns.md new file mode 100644 index 0000000..d479741 --- /dev/null +++ b/references/navigation_patterns.md @@ -0,0 +1,60 @@ +# Navigation Patterns + +_Framework: agency_v3_1 | Estratto: 2026-03-09_ +_Usato da: agency-ux-copy, agency-design-system_ + +## Sommario + +Pattern di navigazione e information architecture per siti agency/services. + +--- + +## Primary Navigation (Agency/Services) + +**Consigliato:** +- Services +- Work / Case studies +- About +- Resources (optional) +- Contact + +**Regole:** +- Max 5 voci primarie +- 1 CTA button in nav (es. "Prenota call") +- Evitare mega-menu se non necessario + +--- + +## Services IA + +**Opzione A) Service overview + pagine dettagli** +- Usa se l'offerta è complessa + +**Opzione B) Packages + outcomes** +- Usa se l'offerta è productizzata + +--- + +## Work / Case Studies IA + +- Index con filtri leggeri (industry/service) +- Scheda case: problema → approccio → soluzione → risultato + +--- + +## Mobile Nav + +- Menu semplice, max 1 livello +- CTA sempre visibile (sticky o nel menu in alto) + +--- + +## Anti-pattern + +- 9 voci in nav +- Dropdown profondi +- CTA nascosta + +--- + +_Reference generato da framework-translator_ diff --git a/references/platform_patterns.md b/references/platform_patterns.md new file mode 100644 index 0000000..7ada452 --- /dev/null +++ b/references/platform_patterns.md @@ -0,0 +1,47 @@ +# Platform Patterns + +_Framework: agency_v3_1 | Estratto: 2026-03-09_ +_Usato da: agency-social, agency-visual-generator_ + +## Sommario + +Pattern specifici per piattaforma social. + +--- + +## LinkedIn + +- Hook + valore + proof +- Tone: professionale, concreto +- CTA: "dimmi nei commenti" / "DM" + +--- + +## Instagram + +**Carousel:** +- 1 idea + step + recap + +**Reel:** +- Hook → 3 punti → CTA "salva" + +--- + +## X / Twitter + +**Thread:** +- Promessa → punti numerati → chiusura + +**Single Tweet:** +- Insight + esempio + +--- + +## TikTok + +- Hook visivo + testo +- Ritmo alto, tagli rapidi + +--- + +_Reference generato da framework-translator_ diff --git a/references/publishing_gates.md b/references/publishing_gates.md new file mode 100644 index 0000000..1178cce --- /dev/null +++ b/references/publishing_gates.md @@ -0,0 +1,40 @@ +# Publishing Gates + +_Framework: agency_v3_1 | Estratto: 2026-03-09_ +_Usato da: agency-orchestrator, agency-publisher_ + +## Sommario + +Gate di approvazione pre-publish per website, social, YouTube. + +--- + +## Regole di Publish + +Publishing allowed only when: + +1. **PUBLISH_APPROVED.md** contiene `YES` +2. **Content file** contiene `APPROVED: YES` nel frontmatter +3. **Logs** sono aggiornati dopo publishing + +--- + +## Flusso + +``` +Draft → Review → Approved → Published +``` + +- Mai publish senza `APPROVED: YES` +- Aggiornare publish log dopo ogni publish + +--- + +## Eccezioni + +- Nessuna eccezione: gate è obbligatorio +- In caso di urgenza: approvazione esplicita richiesta + +--- + +_Reference generato da framework-translator_ diff --git a/references/qa_visual.md b/references/qa_visual.md new file mode 100644 index 0000000..67faadb --- /dev/null +++ b/references/qa_visual.md @@ -0,0 +1,51 @@ +# QA Visual Checklist + +_Framework: agency_v3_1 | Estratto: 2026-03-09_ +_Usato da: agency-visual-generator, agency-publisher_ + +## Sommario + +Checklist per review asset visuali generati (card, carousel, thumbnail). + +--- + +## Readability + +- [ ] Text readable at mobile size (simulate 320px wide) +- [ ] Strong contrast between text and background +- [ ] Headline <= 8 words (unless carousel) + +--- + +## Brand + +- [ ] Colors match the client style guide +- [ ] Fonts match the client style guide (or fallback defined) +- [ ] No off-brand icons/illustrations + +--- + +## Message + +- [ ] One clear idea per image +- [ ] Visual supports the hook/CTA, not competing with it +- [ ] No misleading visuals + +--- + +## Technical + +- [ ] Correct aspect ratio for platform +- [ ] No obvious artifacts / broken text +- [ ] Safe margins for UI overlays + +--- + +## Output + +- **If pass:** mark asset as `approved` +- **If fail:** write fixes in `clients/{client}/backlog/tasks.md` + +--- + +_Reference generato da framework-translator_ diff --git a/references/quality_bar.md b/references/quality_bar.md new file mode 100644 index 0000000..a3227b3 --- /dev/null +++ b/references/quality_bar.md @@ -0,0 +1,41 @@ +# Quality Bar + +_Framework: agency_v3_1 | Estratto: 2026-03-09_ +_Usato da: agency-orchestrator, tutte le skills_ + +## Sommario + +Standard minimo accettabile per deliverable V1. + +--- + +## V1 Principles + +- **Completa > Perfetta** +- **Tracciabile** (decision log + sources log) +- **Ripetibile** (template + checklist) + +--- + +## Pass/Fail Checklist (Generale) + +### Pass se: +- Output in path corretto +- Frontmatter presente e valido +- Fonti loggate quando richiesto +- QA checklist compilata + +### Fail se: +- Output mancante o in path sbagliato +- Citazioni senza sources log +- Tentativo di publish senza `approved` + +--- + +## Applicazione + +Ogni skill deve verificare questi criteri prima di considerare un task completo. + +--- + +_Reference generato da framework-translator_ diff --git a/references/research_citation_rules.md b/references/research_citation_rules.md new file mode 100644 index 0000000..fb746e3 --- /dev/null +++ b/references/research_citation_rules.md @@ -0,0 +1,46 @@ +# Research Citation Rules + +_Framework: agency_v3_1 | Estratto: 2026-03-09_ +_Usato da: agency-research_ + +## Sommario + +Regole per citazione e logging fonti esterne. + +--- + +## Obbligo + +Tutte le fonti esterne devono essere loggate e referenziate. + +--- + +## Web Research + +Consentita **solo** su domini in whitelist: +- Vedi `web_whitelist.yaml` +- Vedi `web_sourcing_standard.md` + +--- + +## Formato + +- Usa ID `SRC-###` +- Per client: `clients/{client}/research/sources.md` +- Per libreria OS: `core/knowledge/sources/SRC-###.md` + +--- + +## Contenuto Minimo + +Ogni source log deve includere: +- Data accesso +- Titolo +- Publisher/autore +- URL +- Affidabilità + motivazione +- Note / estratti brevi + +--- + +_Reference generato da framework-translator_ diff --git a/references/research_playbook.md b/references/research_playbook.md new file mode 100644 index 0000000..8290ddb --- /dev/null +++ b/references/research_playbook.md @@ -0,0 +1,50 @@ +# Research Playbook + +_Framework: agency_v3_1 | Estratto: 2026-03-09_ +_Usato da: agency-research_ + +## Sommario + +Metodo per research competitor e reference. + +--- + +## Competitor Research + +**Analizzare almeno 3 competitor.** + +**Studiare:** +- Positioning +- Messaging +- Offer structure +- Conversion mechanics +- Trust signals +- UX structure +- Visual language + +**Deliver insights:** +- Copy (cosa copiare) +- Avoid (cosa evitare) +- Opportunity (opportunità) + +--- + +## Reference Research + +**Look outside the industry for inspiration.** + +**Raccogliere esempi di:** +- Hero sections +- Layout structures +- Navigation patterns +- Case study formats +- Animation and motion + +**Per ogni reference document:** +- Why it works +- What to borrow +- Possible risks + +--- + +_Reference generato da framework-translator_ diff --git a/references/strategy_playbook.md b/references/strategy_playbook.md new file mode 100644 index 0000000..d083e94 --- /dev/null +++ b/references/strategy_playbook.md @@ -0,0 +1,74 @@ +# Strategy Playbook + +_Framework: agency_v3_1 | Estratto: 2026-03-09_ +_Usato da: agency-strategy_ + +## Sommario + +Framework per positioning, messaging e direzione strategica. + +--- + +## Positioning + +**Definire:** +- Audience +- Problem +- Desired outcome +- Unique value +- Proof + +**Formula:** +> "For [audience] who want [outcome], we provide [solution] unlike [alternative] because [proof]." + +--- + +## Messaging + +### Message House + +**Core message:** +- Primary promise of the brand + +**Supporting messages:** +- 3-5 key arguments supporting the promise + +**Proof points:** +- Evidence such as results, numbers, testimonials + +**CTA:** +- Desired action (contact, signup, purchase) + +--- + +## Offer Architecture + +Organizza offerte in: + +| Tipo | Descrizione | +|------|-----------| +| **Entry offer** | Punto di ingresso, basso impegno | +| **Core offer** | Offerta principale | +| **Premium offer** | High-ticket, completo | + +**Ogni offerta include:** +- Outcome +- Process +- Proof +- CTA + +--- + +## Content Pillars + +Definire 4-6 topic che il brand comunica consistentemente. + +**Esempio:** +- Education +- Insights +- Case studies +- Behind the scenes + +--- + +_Reference generato da framework-translator_ diff --git a/references/trust_signal_patterns.md b/references/trust_signal_patterns.md new file mode 100644 index 0000000..94cd8e1 --- /dev/null +++ b/references/trust_signal_patterns.md @@ -0,0 +1,60 @@ +# Trust Signal Patterns + +_Framework: agency_v3_1 | Estratto: 2026-03-09_ +_Usato da: agency-ux-copy, agency-strategy_ + +## Sommario + +Pattern per costruire fiducia con prova, chiarezza e coerenza. + +--- + +## Tipi di Trust Signals + +### 1) Social Proof +- Loghi clienti +- Testimonial +- Recensioni + +### 2) Proof of Work +- Case studies +- Portfolio +- Process artifacts (wireframe, strategy doc) + +### 3) Authority +- Awards +- Talk / podcast +- Partnerships +- Certifications + +### 4) Transparency +- Process +- Timeline +- Pricing posture (anche "starting from") +- What's included / excluded + +--- + +## Placement + +- Vicino a CTA (subito sopra o sotto) +- Dopo services overview +- Nelle pagine service + +--- + +## Trust Copy Patterns + +- "Abbiamo aiutato [audience] a ottenere [outcome] con [approach]." +- "Approccio: [3 step] — Risultati: [metric]." + +--- + +## Anti-pattern + +- Claim generici senza prova ("best agency", "top quality") +- Numeri senza contesto + +--- + +_Reference generato da framework-translator_ diff --git a/references/weekly_report_template.md b/references/weekly_report_template.md new file mode 100644 index 0000000..5e385ed --- /dev/null +++ b/references/weekly_report_template.md @@ -0,0 +1,52 @@ +# Weekly Report Template + +_Framework: agency_v3_1 | Estratto: 2026-03-09_ +_Usato da: agency-analytics_ + +## Sommario + +Template per report settimanali KPI. + +--- + +## Template + +```markdown +# Weekly Report - Week {WW} + +## KPI Snapshot + +{Inserire metriche chiave} + +## Highlights + +{Cosa ha funzionato} + +## Lowlights + +{Cosa non ha funzionato} + +## Top Content + +{Contenuti migliori} + +## Actions Next Week (max 5) + +1. {Action 1} +2. {Action 2} +3. {Action 3} +4. {Action 4} +5. {Action 5} +``` + +--- + +## Regole + +- Max 5 actions per settimana +- KPI snapshot deve essere conciso +- Focus su insight concreti, non narrative lunghe + +--- + +_Reference generato da framework-translator_ diff --git a/references/youtube_script_framework.md b/references/youtube_script_framework.md new file mode 100644 index 0000000..b88f823 --- /dev/null +++ b/references/youtube_script_framework.md @@ -0,0 +1,32 @@ +# YouTube Script Framework + +_Framework: agency_v3_1 | Estratto: 2026-03-09_ +_Usato da: agency-youtube_ + +## Sommario + +Pattern per script YouTube retention-first. + +--- + +## Struttura Script + +| Tempo | Sezione | Descrizione | +|-------|---------|-------------| +| 0-10s | Hook | Promise + curiosity | +| 10-25s | Credibility | Why you should listen | +| 25-60s | Problem | Define the problem (relatable) | +| Main | 3-5 Chapters | Con open loops | +| End | Summary + CTA | Recap e call to action | + +--- + +## Regole + +- Open a loop ogni 60-90s +- Usare esempi, non teoria +- Hook deve essere <10s + +--- + +_Reference generato da framework-translator_