claude-code-arcane 1.2.0 → 1.4.0

package/skills/job-hunt/references/templates/Entrevista.md

@@ -0,0 +1,44 @@
+---
+tipo: entrevista
+aplicacion: 
+empresa: 
+ronda: 
+fecha: {{date:YYYY-MM-DD}}
+duracion: 
+entrevistadores: []
+modalidad: 
+---
+
+# {{title}}
+
+## Aplicación
+- [[]]
+
+## Preparación
+- Research de empresa: [[]]
+- Temas a repasar:
+  - 
+- Preguntas propias a hacer:
+  - 
+
+## Durante la entrevista
+### Temas que surgieron
+- 
+
+### Preguntas que me hicieron
+- 
+
+### Preguntas que hice
+- 
+
+## Feedback
+### Cómo salí (autoevaluación)
+
+
+### Señales de ellos
+
+
+## Próximo paso
+
+
+## Notas post-entrevista

package/skills/job-hunt/references/templates/Perfil.md

@@ -0,0 +1,38 @@
+---
+tipo: perfil
+rol_objetivo: 
+seniority: 
+stack: []
+modalidad: []
+mercado_objetivo: []
+match_score_minimo: 75
+salario_minimo_usd_mes: 
+keywords: []
+keywords_excluir: []
+regla_seniority: 
+fuentes: []
+---
+
+# Perfil — {{title}}
+
+## Resumen
+> 2–3 líneas: quién sos para este rol y qué te hace fuerte.
+
+## Stack principal
+- 
+
+## Experiencia destacada para este perfil
+- 
+
+## Diferenciales
+- 
+
+## Logros cuantificables (para CV)
+> Con número, contexto y resultado. Reusables en CVs y LinkedIn.
+- 
+
+## CVs asociados
+- 
+
+## Aplicaciones relacionadas
+- 

package/skills/job-search/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: job-search
+description: "Find, score and prioritize job openings against your profile, then build a structured 7-day search plan with daily goals. Creates application and company notes in the workspace. Triggers: buscar trabajo, encontrar ofertas, scorear ofertas, plan de busqueda laboral, priorizar postulaciones, job search plan, donde aplicar."
+argument-hint: "[search <query> | score <job-url> | plan]"
+category: "career"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Edit, WebFetch, WebSearch
+---
+
+# Job Search — Búsqueda, scoring y plan
+
+Encontrás ofertas, las **scoreás** contra el perfil del usuario, priorizás, y armás un **plan de búsqueda de 7 días** con objetivos diarios. Alimentás el workspace con notas de aplicación y empresa para que el resto del flujo (`/cv-tailor`, `/cover-letter`, etc.) las consuma.
+
+## Inputs
+
+- **Perfil(es) objetivo** (`01-Perfiles/`): rol, seniority, stack, modalidad, mercado, **score mínimo** (default 75), salario mínimo, keywords y keywords a excluir.
+- Fuentes de ofertas que use el usuario (job boards, WeWorkRemotely, LinkedIn, Workable, etc.).
+
+## Modos
+
+### `search <query>` — Encontrar ofertas
+1. **Sourcing.** Conseguir ofertas frescas que matcheen el perfil (rol + stack + modalidad + mercado). Dos caminos:
+   - **Apify MCP (opcional).** Si hay un MCP de Apify conectado, podés usar un actor de scraping de LinkedIn Jobs para traer ofertas estructuradas. Ejemplo de pedido: *"Scrapeá LinkedIn jobs para [rol] posteadas en los últimos 7 días en empresas de 50–5000 empleados; filtrá por match con mi background en [dominio]; devolvé tabla rankeada con empresa, rol, ubicación, salario, fecha de posteo y fit score 1–10 basado en mi resume; marcá el top 10 para aplicar hoy."* Buscá el actor con ToolSearch (`apify`) si el MCP está presente. **⚠️ OBLIGATORIO: antes de invocar Apify, mostrá el warning de abajo y pedí confirmación explícita.**
+   - **WebSearch/WebFetch (default recomendado).** Camino sin Apify: buscar en job boards (muchos con feed/API pública: WeWorkRemotely, RemoteOK, etc.) y fetchear los JDs. Es el default seguro y gratis.
+
+> ### ⚠️ Warning Apify — mostralo SIEMPRE antes de usar esta parte
+>
+> Antes de correr cualquier actor de Apify (especialmente scraping de LinkedIn), presentá estos puntos al usuario y esperá confirmación explícita. No invoques Apify "en silencio".
+>
+> 1. **No es gratis.** Apify cobra por uso (compute units / por resultado); un scrape grande consume crédito. El tier free es limitado.
+> 2. **Scrapear LinkedIn viola sus Términos de Servicio.** LinkedIn detecta y bloquea scraping activamente y puede **restringir o banear la cuenta**. La legalidad de scrapear datos públicos está en zona gris (caso hiQ vs LinkedIn); el riesgo de ToS/cuenta es real y es del usuario, no de Apify. Preferir actors sobre **job boards públicos** antes que LinkedIn directo; si igual se scrapea LinkedIn, hacerlo de forma consciente y no con una cuenta crítica.
+> 3. **El API token de Apify es sensible.** Autoriza correr actors (y gastar el plan) en nombre del usuario. Mantenerlo seguro; no exponerlo ni commitearlo. (Apify no recolecta conversaciones/tokens y trata a los actors como no confiables: les da un proxy y no les entrega las credenciales — un actor malicioso puede usar las tools habilitadas pero no exfiltrar el token.)
+> 4. **Calidad/estabilidad variable.** Los scrapers de LinkedIn se rompen seguido; los resultados pueden venir incompletos o desactualizados.
+>
+> Si el usuario no confirma, usá el camino WebSearch/WebFetch.
+2. Para cada oferta candidata: extraer rol, empresa, stack, modalidad, ubicación, rango salarial, link, fecha de cierre.
+3. Scorear (ver rúbrica) y filtrar por el umbral del perfil.
+4. Crear nota en `03-Aplicaciones/` (template `Aplicacion`, estado `interesado`, con `score`) + nota en `04-Empresas/` (template `Empresa`) por cada una sobre el umbral.
+5. Actualizar el `00-Dashboard.md` con las activas por prioridad, marcando el **top 10 para hoy**.
+
+### `score <job-url>` — Scorear una oferta puntual
+1. WebFetch del JD.
+2. Aplicar la rúbrica contra el perfil → score 0–100 + breakdown + recomendación (aplicar / borderline / skip).
+3. Si pasa, crear las notas como arriba.
+
+### `plan` — Plan de búsqueda de 7 días
+Generar un plan accionable con objetivos diarios. Ejemplo de esqueleto (ajustar al estado del usuario):
+
+- **Día 1 — Base.** Perfil maestro + perfiles por rol al día; LinkedIn optimizado (`/linkedin-optimize`).
+- **Día 2 — Sourcing.** Buscar y scorear 15–20 ofertas; quedarte con las ≥ umbral.
+- **Día 3 — Research.** Empresas + contactos objetivo de las top.
+- **Día 4 — Aplicaciones tanda 1.** CV custom + cover letter para las 5 de mayor prioridad (`/cv-tailor`, `/cv-ats-export`, `/cover-letter`).
+- **Día 5 — Outreach.** Mensajes a recruiters/hiring managers de las top (`/cold-outreach`).
+- **Día 6 — Aplicaciones tanda 2** + follow-ups de la tanda 1.
+- **Día 7 — Review.** Métricas (aplicadas / respuestas / entrevistas), ajustar perfil/CV según señales, planear próxima semana.
+
+## Rúbrica de scoring
+
+Ver `references/scoring-rubric.md`. En resumen, score ponderado 0–100 sobre:
+- Match de stack/skills (peso alto)
+- Seniority correcto (penalizar over/under-qualified)
+- Modalidad y mercado/elegibilidad (remoto, zona horaria, visa)
+- Salario vs mínimo
+- Cultura/etapa según preferencia
+- Señales de calidad de la oferta (claridad, recencia, # aplicantes)
+
+Umbral default ≥75 (configurable en el frontmatter del perfil, campo `match_score_minimo`).
+
+## Tracking
+
+- Estados de aplicación: `interesado` → `aplicado` → `en proceso` → `entrevista` → `oferta` / `rechazado` / `descartado`.
+- Mantener el `00-Dashboard.md` como vista única: activas por prioridad, próximas entrevistas, qué cierra pronto, a seguir esta semana.
+
+## Reglas
+
+- No aplicar a todo: el umbral existe para concentrar esfuerzo donde hay match real.
+- Marcar gaps con honestidad al scorear (no inflar el match).
+- Respetar elegibilidad (visa/zona horaria) — un score alto con bloqueo de elegibilidad no sirve.
+- No guardar datos sensibles de recruiters en remotos sin confirmación.
+
+## Handoff
+
+Confirmá (approval) antes de crear notas de aplicación/empresa o tocar el Dashboard. Cuando las ofertas priorizadas están READY, el siguiente paso es `/cv-tailor` sobre las de prioridad alta.

package/skills/job-search/references/scoring-rubric.md

@@ -0,0 +1,43 @@
+# Job Scoring Rubric
+
+Score ponderado 0–100 para decidir dónde invertir esfuerzo. El objetivo no es aplicar a todo: es concentrarte en ofertas con match real. Umbral default **≥75** (configurable por perfil en `match_score_minimo`).
+
+## Dimensiones y pesos (default)
+
+| Dimensión | Peso | Cómo puntuar |
+|---|---:|---|
+| **Match de stack/skills** | 30 | % de must-haves que cumplís. 30 si cubrís todos los core; baja proporcional. |
+| **Seniority** | 15 | 15 si el nivel encaja. Penalizar over-qualified (aburrimiento/rechazo) y under-qualified (filtro). |
+| **Modalidad + elegibilidad** | 20 | Remoto/híbrido/presencial según preferencia; zona horaria; visa/eligibility. Si hay bloqueo duro de elegibilidad → cap fuerte al score. |
+| **Salario** | 15 | 15 si ≥ tu objetivo; proporcional hasta tu mínimo; 0 si por debajo del mínimo. Si no publican, neutro (≈8) y marcar. |
+| **Empresa/cultura/etapa** | 10 | Encaje con preferencia (startup vs enterprise, producto vs consultora, valores). |
+| **Calidad de la oferta** | 10 | Claridad del JD, recencia (fresca > vieja), pocos aplicantes, proceso definido. |
+
+Sumá las dimensiones → score 0–100.
+
+## Ajustes / banderas
+
+- **Frase gatillo positiva** (ej. "code-forward", "high autonomy", stack que amás): +2–5 si refuerza tu fit.
+- **Red flag en el JD** (ego, "rockstar", scope imposible, "trabajamos como familia"): −5–10 y nota de cautela.
+- **Cierre inminente:** no cambia el score, pero sube la **prioridad** de acción.
+- **Elegibilidad bloqueada** (visa que no tenés, zona horaria incompatible obligatoria): cap el score a <50 aunque el resto sea perfecto.
+
+## De score a acción
+
+| Score | Acción |
+|---|---|
+| **≥85** | Prioridad alta. Aplicar con CV custom + cover letter + outreach. |
+| **75–84** | Aplicar; CV custom sí, outreach si hay contacto fácil. |
+| **60–74** | Borderline. Aplicar solo si hay tiempo o un ángulo fuerte (referido). |
+| **<60** | Skip salvo razón estratégica. |
+
+## Prioridad (distinta del score)
+
+`prioridad` en el frontmatter combina score + urgencia + elegibilidad:
+- **alta:** score ≥85, o ≥75 con cierre inminente / referido caliente.
+- **media:** 75–84 sin urgencia.
+- **baja:** borderline o a la espera de validar requisitos.
+
+## Registro
+
+Guardá el `score` en el frontmatter de la nota de `03-Aplicaciones/` y reflejá las activas en `00-Dashboard.md` agrupadas por prioridad. Anotá el breakdown si el score fue borderline — ayuda a decidir y a re-evaluar después.

package/skills/linkedin-optimize/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: linkedin-optimize
+description: "Optimize a LinkedIn profile to attract recruiters and rank in search — headline, About, experience with KPIs, keywords, value proposition and a 30-second pitch. No LinkedIn Premium needed. Triggers: optimizar LinkedIn, mejorar perfil LinkedIn, headline LinkedIn, about LinkedIn, LinkedIn para reclutadores, LinkedIn SEO, pitch profesional."
+argument-hint: "[section | full] (paste your current profile)"
+category: "career"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Edit
+---
+
+# LinkedIn Optimize — Perfil que atrae oportunidades
+
+Optimizás un perfil de LinkedIn para que (1) ranquee en las búsquedas de recruiters y (2) convenza al humano que lo abre. Trabajás contra el **perfil maestro** (`01-Perfiles/`) y lo que el usuario pega de su perfil actual.
+
+> **Importante:** Claude no accede a LinkedIn ni edita el perfil directamente. El usuario pega/sube el contenido actual; vos generás el texto optimizado para que lo copie/pegue.
+
+## Cómo traer tu perfil a Claude
+
+La forma más completa: en LinkedIn → **Recursos / More → Save to PDF** (exporta el perfil entero) y subí ese PDF a Claude. Alternativa: copiar/pegar headline + About + experiencia. Con el PDF, podés pedir una **auditoría contra JDs reales**:
+
+> "Audita mi perfil de LinkedIn (adjunto) contra JDs de [rol] senior en [empresas objetivo]. Encontrá gaps en headline, About y Experience: keywords faltantes, framing de identidad equivocado, credenciales enterradas. Después reescribí headline y About para posicionarme como **builder**, optimizado para la búsqueda de recruiters."
+
+**Framing de identidad:** posicionate como alguien que *construye/entrega* (builder), no como una lista de tareas. El headline y el About deben gritar resultados e identidad, no responsabilidades.
+
+## Las 7 áreas de optimización
+
+Cubrí estas siete (el usuario puede pedir una con `[section]` o todas con `full`):
+
+### 1. Headline (titular)
+- 220 caracteres. No solo el puesto: **rol + valor + keywords**.
+- Patrón: `{Rol} | {especialidad/stack} | {valor o a quién ayudás}`.
+- Las keywords del headline pesan fuerte en el ranking de búsqueda.
+
+### 2. About (sección "Acerca de")
+- Primera 2–3 líneas son las que se ven sin "ver más": que enganchen.
+- Estructura: gancho → qué hacés y para quién → 2–3 logros con número → stack/keywords → CTA suave.
+- Primera persona, tono humano, escaneable (párrafos cortos o bullets).
+
+### 3. Experiencia con KPIs
+- Cada rol con bullets de **logros cuantificables**, no responsabilidades.
+- Mismo principio que el CV: verbo de acción + métrica + impacto.
+- Incluí keywords de tu industria/rol en los bullets.
+
+### 4. Keywords estratégicas (LinkedIn SEO)
+- Identificá las keywords que los recruiters de tu rol buscan.
+- Distribuilas en headline, About, experiencia, y la sección Skills.
+- Las **Skills** (hasta 50, fijá las 3 top) alimentan el match con búsquedas y endorsements.
+
+### 5. Propuesta de valor única
+- Qué te diferencia: combinación de skills, dominio, resultados. Una frase clara que sintetiza "por qué vos".
+
+### 6. Pitch de 30 segundos
+- Versión hablada de tu propuesta de valor: quién sos, qué hacés/resolvés, qué buscás. Para mensajes, networking y el "contame de vos".
+
+### 7. Review ATS / searchability
+- Foto profesional, banner, URL personalizada, "Open to work" configurado (público o solo-recruiters), ubicación y rol objetivo seteados.
+- Perfil completo = más alcance (LinkedIn premia completitud).
+- Sin gaps inexplicados; títulos consistentes con cómo se busca el rol.
+
+## Proceso
+
+1. Leer el perfil maestro + lo que el usuario pega de su LinkedIn actual.
+2. Definir el/los **rol(es) objetivo** y sus keywords (reusá `cv-tailor/references/ats-keywords.md` para el método).
+3. Generar el contenido optimizado por sección (la/s que pida).
+4. Entregar listo para copiar/pegar + un checklist de la review (área 7).
+5. Opcional: guardar el output en `01-Perfiles/LinkedIn.md` para versionarlo.
+
+## Idioma
+
+LinkedIn en **inglés** si apuntás a roles internacionales (mayor alcance), español si tu mercado es local. Se puede tener el About bilingüe.
+
+## Reglas
+
+- No inventar logros ni métricas — todo debe ser defendible.
+- Keywords naturales, no stuffing.
+- Recordar que no se puede acceder/editar LinkedIn: el output es para copiar/pegar.
+
+## Handoff
+
+Pedí aprobación (approval) antes de escribir `01-Perfiles/LinkedIn.md`. Cuando el contenido está READY para copiar/pegar, un buen siguiente paso es `/portfolio-site` para alinear el portfolio web.

package/skills/master-profile/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: master-profile
+description: "Build and maintain the master professional profile — the single source of truth (experience, skills with levels, projects, education, references, bios) that every CV, LinkedIn profile and portfolio derives from. Triggers: perfil maestro, master resume, cronologia laboral, single source of truth CV, mi experiencia profesional."
+argument-hint: "[build | update | derive <role>]"
+category: "career"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Edit
+---
+
+# Master Profile — Single Source of Truth
+
+Construís y mantenés el **perfil maestro**: el documento del que derivan todos los CVs, el LinkedIn y el portfolio. La regla de oro: **si algo cambia, se cambia acá primero** y de acá se sincroniza al resto.
+
+Vive en `01-Perfiles/Perfil Maestro.md` dentro del career workspace. Los perfiles por rol (`Backend.md`, `Frontend.md`, etc.) son **vistas filtradas** del maestro, no fuentes independientes.
+
+## Por qué existe
+
+Mantener N CVs sincronizados a mano es la causa #1 de errores (fechas que no coinciden, logros que faltan en una versión). Con un maestro: editás un lado, derivás el resto. `/cv-tailor`, `/linkedin-optimize` y `/portfolio-site` consumen este archivo.
+
+## Estructura del perfil maestro
+
+Generá el archivo con estas secciones (todas las que apliquen):
+
+1. **Personal info** — nombre, display name, headline actual, ubicación, email público vs personal, teléfono, LinkedIn, GitHub, portfolio. (El email *público* puede diferir del personal.)
+2. **Bios** — tres largos: corto (hero/one-liner), medio (2–3 oraciones para "About"), largo (about page completo).
+3. **Work experience** (más reciente primero) — por cada rol: empresa, período, ubicación/modalidad, producto, stack, manager/referencia, y **bullets de logros con número→contexto→resultado**.
+4. **Education** — institución, período, foco.
+5. **Certifications** — nombre, año, estado (completo/in progress).
+6. **Skills consolidados con nivel** — agrupados (lenguajes, frameworks, infra, tooling) con nivel (Expert/Advanced/Proficient/…) y opcionalmente % para el portfolio.
+7. **Projects** — tech, rol, highlights, link en vivo.
+8. **Achievements / highlights** — premios, showcases, hitos.
+9. **Languages** — idioma + nivel.
+10. **References** — nombre, rol, relación, contacto.
+
+## Modos
+
+### `build` — Crear el maestro desde cero
+1. Si no existe el workspace, sugerir `/job-hunt setup` primero.
+2. Recolectar info por sección — preferí **entrevistar al usuario por bloques** (no un cuestionario gigante). Empezá por experiencia y skills.
+3. Para cada logro, empujar a la forma **cuantificable**: "¿qué número podés ponerle? ¿comparado con qué? ¿qué resultado tuvo?". Un bullet sin métrica es una oportunidad perdida.
+4. Escribir `01-Perfiles/Perfil Maestro.md`.
+5. Sugerir derivar el primer perfil por rol: `/master-profile derive <role>`.
+
+### `update` — Mantener al día
+1. Leer el maestro actual.
+2. Aplicar el cambio (nuevo rol, nuevo logro, ascenso, proyecto).
+3. **Avisar qué derivados quedan desactualizados** (CVs por rol, LinkedIn, portfolio) y ofrecer re-derivarlos.
+
+### `derive <role>` — Vista por rol
+1. Leer el maestro.
+2. Crear/actualizar `01-Perfiles/<Role>.md` con el template `Perfil` (ver `Templates/Perfil.md`): filtrar y reordenar la experiencia/skills/proyectos hacia ese rol, definir keywords objetivo, score mínimo y mercado.
+3. Este perfil por rol es el `perfil_base` que después usa `/cv-tailor`.
+
+## Principios de redacción
+
+- **Logros, no responsabilidades.** "Reduje latencia de servidor 25%" > "Encargado del servidor".
+- **Verbos de acción + métrica + impacto.** Owned, shipped, led, reduced, increased, scaled.
+- **Verdad verificable.** Nada que no puedas defender en una entrevista.
+- **Inglés para roles internacionales**, español cuando aplique. El maestro puede tener los valores en inglés (van directo a CV/portfolio) y las meta-notas en español.
+
+## Reglas
+
+- Una sola fuente de verdad: no dejar que un CV por rol "evolucione" por fuera del maestro.
+- No inventar logros ni métricas — si el usuario no tiene el número, marcarlo como pendiente, no fabricarlo.
+- Separar email público de personal; no exponer datos sensibles en archivos que vayan a un remoto.
+
+## Handoff
+
+Confirmá con el usuario (approval) antes de escribir el perfil maestro o pisar derivados. Cuando el maestro está READY, derivá perfiles por rol y seguí con `/cv-tailor`, `/linkedin-optimize` o `/portfolio-site`.

package/skills/merchant-feed/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: merchant-feed
+description: "Build and validate product feeds for shopping channels — Google Merchant Center and Meta Catalog — including required/recommended attributes, attribute mapping, and feed validation. Includes a feed validator/generator script. Triggers: building a product feed, fixing feed disapprovals, mapping catalog to feed attributes."
+argument-hint: "[validate | generate | map]"
+category: "ecommerce"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+# Merchant Feed
+
+Shopping ads and free listings live or die on feed quality. A clean, complete feed gets products approved and surfaced; a sloppy one gets disapprovals. Map your catalog to channel attributes and validate before upload — platform-agnostic.
+
+## Before Starting
+
+Gather: target channel (Google Merchant / Meta Catalog), source of truth (DB export, CSV, platform), product categories, and goal (validate an existing feed, generate one, or map catalog → feed attributes).
+
+## How This Skill Works
+
+| Mode | Trigger | Output |
+|------|---------|--------|
+| **Validate** | `validate` | Pass/fail report against required attributes |
+| **Generate** | `generate` | Feed emitted from a source CSV |
+| **Map** | `map` | Catalog field → feed attribute mapping |
+
+---
+
+## Phase 1 — Required Attributes
+
+Google Merchant / Meta share a common core. Required for every item:
+
+| Attribute | Notes |
+|-----------|-------|
+| `id` | Stable, unique per variant (use SKU) |
+| `title` | Front-load product; ≤150 chars; match landing page |
+| `description` | Plain, accurate; no promo text/caps |
+| `link` | Canonical PDP URL |
+| `image_link` | Main image, meets resolution minimums |
+| `availability` | in_stock / out_of_stock / preorder |
+| `price` | With currency; must match landing page exactly |
+| `brand` | Required unless exempt category |
+| `gtin` / `mpn` | Required where a GTIN exists — improves matching |
+| `condition` | new / refurbished / used |
+
+**Rule:** Feed price and availability must **exactly match** the live PDP, or the item is disapproved and the account is penalized.
+
+---
+
+## Phase 2 — Validate / Generate
+
+Run the validator on a CSV export:
+
+```bash
+python skills/merchant-feed/scripts/feed_validate.py            # demo data
+python skills/merchant-feed/scripts/feed_validate.py feed.csv
+```
+
+It checks every row for required attributes, flags missing/empty values, validates `availability`/`condition` enums and price+currency format, and reports a per-row and summary verdict. For the full attribute reference and category-specific requirements, see [references/feed-attribute-map.md](references/feed-attribute-map.md).
+
+---
+
+## Phase 3 — Recommended Attributes & Quality
+
+Beyond required, these lift performance: `google_product_category`, `product_type`, `item_group_id` (links variants), `color`, `size`, `gender`, `age_group`, `sale_price`, `shipping`, `gtin`. Use `item_group_id` so variants cluster correctly — without it, variants compete as separate products.
+
+---
+
+## Output Artifacts
+
+| Request | Output |
+|---------|--------|
+| Validate | Per-row + summary PASS / FAIL report |
+| Generate | Channel-ready feed file |
+| Map | Catalog → feed attribute mapping table |
+
+A feed is **READY** when every item has all required attributes, price/availability match the PDP, variants share an `item_group_id`, and GTINs are present where they exist.
+
+---
+
+## Related Skills
+
+- **commerce-data-model**: the catalog entities mapped into feed attributes.
+- **product-listing**: titles/descriptions reused between PDP and feed.
+- **shipping-tax**: shipping attribute values in the feed.
+- **schema-markup**: Product structured data complements the feed for organic.

package/skills/merchant-feed/references/feed-attribute-map.md

@@ -0,0 +1,47 @@
+# Product Feed — Attribute Reference & Catalog Mapping
+
+Maps the commerce data model to Google Merchant / Meta Catalog feed attributes. The `feed_validate.py` script enforces the required core.
+
+## Required attributes (every item)
+| Feed attribute | Source (data model) | Rule |
+|----------------|---------------------|------|
+| id | variant.sku | Stable, unique per variant |
+| title | product.title (+ variant) | Front-load product; ≤150 chars; match PDP |
+| description | product.description | Plain, accurate; no promo/ALL CAPS |
+| link | product URL | Canonical, absolute https |
+| image_link | main image | Absolute https; meets resolution min |
+| availability | variant stock | in_stock / out_of_stock / preorder / backorder |
+| price | variant.price | `"21.00 USD"` — matches PDP exactly |
+| brand | product.brand | Required unless exempt category |
+| condition | — | new / refurbished / used |
+
+## Strongly recommended
+| Feed attribute | Source | Why |
+|----------------|--------|-----|
+| gtin | variant.barcode | Improves matching / eligibility |
+| mpn | variant.mpn | Fallback when no GTIN |
+| item_group_id | product.id | Clusters variants (else they compete) |
+| google_product_category | category map | Taxonomy alignment |
+| product_type | primary_category | Your own taxonomy |
+| color / size / gender / age_group | attributes | Apparel facets |
+| sale_price | compare_at logic | Promo pricing |
+| shipping | shipping-tax rules | Overrides account settings |
+
+## Hard rules (disapproval triggers)
+- Feed **price + availability must match the live PDP** exactly.
+- No promotional text in `title`/`description` (no "Free shipping!", no emojis/caps).
+- `image_link` must resolve and meet the channel's minimum resolution.
+- Variants without a shared `item_group_id` are treated as separate products.
+
+## Worked example (CSV row)
+```csv
+id,title,description,link,image_link,availability,price,brand,condition,gtin,item_group_id
+ACME-TEE-RED-M,"Acme Cotton Tee — Red, Medium","Soft 100% cotton crew-neck tee.",https://shop.example.com/p/acme-tee-red-m,https://shop.example.com/img/acme-tee-red-m.jpg,in_stock,21.00 USD,Acme,new,0123456789012,ACME-TEE
+```
+
+## Verdict: READY when
+- [ ] All required attributes present and non-empty
+- [ ] price/availability match PDP
+- [ ] valid availability + condition enums
+- [ ] price formatted `amount ISO-currency`
+- [ ] variants share item_group_id; GTIN present where it exists

package/skills/merchant-feed/scripts/feed_validate.py

@@ -0,0 +1,140 @@
+"""
+feed_validate.py — Validate a product feed CSV against Google Merchant /
+Meta Catalog requirements (the shared required-attribute core).
+
+Checks every row for required attributes, empty values, valid enums
+(availability, condition), and price+currency formatting. Reports a per-row
+and summary verdict. No external dependencies; cross-platform.
+
+Usage:
+    python feed_validate.py               # built-in demo feed
+    python feed_validate.py feed.csv      # validate your feed
+    python feed_validate.py feed.csv --strict   # treat recommended as required
+
+CSV header (required attributes):
+    id,title,description,link,image_link,availability,price,brand,condition
+Recommended columns (warn if absent/empty): gtin, mpn, item_group_id,
+    google_product_category, sale_price
+"""
+
+import argparse
+import csv
+import re
+import sys
+
+
+REQUIRED = ["id", "title", "description", "link", "image_link",
+            "availability", "price", "brand", "condition"]
+RECOMMENDED = ["gtin", "mpn", "item_group_id", "google_product_category"]
+
+AVAILABILITY = {"in_stock", "out_of_stock", "preorder", "backorder"}
+CONDITION = {"new", "refurbished", "used"}
+# e.g. "21.00 USD" / "9.99 EUR"
+PRICE_RE = re.compile(r"^\d+(\.\d{1,2})?\s+[A-Z]{3}$")
+URL_RE = re.compile(r"^https?://", re.IGNORECASE)
+TITLE_MAX = 150
+DESC_MAX = 5000
+
+
+DEMO_FEED = [
+    {"id": "ACME-TEE-RED-M", "title": "Acme Cotton Tee — Red, Medium",
+     "description": "Soft 100% cotton crew-neck tee.", "link": "https://shop.example.com/p/acme-tee-red-m",
+     "image_link": "https://shop.example.com/img/acme-tee-red-m.jpg", "availability": "in_stock",
+     "price": "21.00 USD", "brand": "Acme", "condition": "new",
+     "gtin": "0123456789012", "item_group_id": "ACME-TEE"},
+    # broken row: bad availability, bad price, missing brand, non-url image
+    {"id": "ACME-MUG-BLUE", "title": "Acme Mug", "description": "",
+     "link": "https://shop.example.com/p/acme-mug", "image_link": "acme-mug.jpg",
+     "availability": "available", "price": "9.99", "brand": "", "condition": "brand-new"},
+]
+
+
+def validate_row(row, idx, strict):
+    errors = []
+    warnings = []
+
+    for attr in REQUIRED:
+        if not (row.get(attr) or "").strip():
+            errors.append(f"missing required '{attr}'")
+
+    avail = (row.get("availability") or "").strip().lower()
+    if avail and avail not in AVAILABILITY:
+        errors.append(f"availability '{avail}' not in {sorted(AVAILABILITY)}")
+
+    cond = (row.get("condition") or "").strip().lower()
+    if cond and cond not in CONDITION:
+        errors.append(f"condition '{cond}' not in {sorted(CONDITION)}")
+
+    price = (row.get("price") or "").strip()
+    if price and not PRICE_RE.match(price):
+        errors.append(f"price '{price}' must be like '21.00 USD' (amount + ISO currency)")
+
+    for url_attr in ("link", "image_link"):
+        val = (row.get(url_attr) or "").strip()
+        if val and not URL_RE.match(val):
+            errors.append(f"{url_attr} '{val}' must be an absolute http(s) URL")
+
+    title = (row.get("title") or "").strip()
+    if len(title) > TITLE_MAX:
+        warnings.append(f"title > {TITLE_MAX} chars ({len(title)})")
+    if len(row.get("description") or "") > DESC_MAX:
+        warnings.append(f"description > {DESC_MAX} chars")
+
+    has_id_link = bool((row.get("item_group_id") or "").strip())
+    if not has_id_link:
+        warnings.append("no item_group_id (variants won't cluster)")
+    if not (row.get("gtin") or "").strip() and not (row.get("mpn") or "").strip():
+        warnings.append("no gtin/mpn (weakens product matching)")
+
+    if strict:
+        errors.extend(f"(strict) {w}" for w in warnings)
+        warnings = []
+    return errors, warnings
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Validate a Google/Meta product feed CSV.")
+    ap.add_argument("csv", nargs="?", help="feed CSV. Omit for demo data.")
+    ap.add_argument("--strict", action="store_true", help="treat recommended issues as failures")
+    args = ap.parse_args()
+
+    if args.csv:
+        try:
+            with open(args.csv, newline="", encoding="utf-8") as f:
+                rows = list(csv.DictReader(f))
+        except OSError as e:
+            print(f"[ERROR] cannot read {args.csv}: {e}")
+            sys.exit(1)
+    else:
+        print("[INFO] No CSV given - using built-in demo feed.\n")
+        rows = DEMO_FEED
+
+    if not rows:
+        print("[ERROR] feed is empty.")
+        sys.exit(1)
+
+    failed = 0
+    for idx, row in enumerate(rows):
+        errors, warnings = validate_row(row, idx, args.strict)
+        rid = row.get("id") or f"row{idx}"
+        if errors:
+            failed += 1
+            print(f"FAIL  {rid}")
+            for e in errors:
+                print(f"        - {e}")
+            for w in warnings:
+                print(f"        ~ {w}")
+        else:
+            print(f"PASS  {rid}")
+            for w in warnings:
+                print(f"        ~ {w}")
+
+    print()
+    passed = len(rows) - failed
+    verdict = "READY" if failed == 0 else "NOT-READY"
+    print(f"{verdict}: {passed}/{len(rows)} items pass required-attribute checks.")
+    sys.exit(0 if failed == 0 else 1)
+
+
+if __name__ == "__main__":
+    main()