@orbitant/brain-marketing 1.5.0

package/skills/blog-post-create/references/orbitant-narrative.md

@@ -0,0 +1,151 @@
+# Orbitant — Corporate Narrative
+
+> **Usage instructions:** This document is the single source of truth for Orbitant's narrative,
+> positioning, and strategic language. Any content generated for or about Orbitant must be
+> coherent with the concepts, metaphors, and positioning described here.
+> Do not contradict or dilute these ideas — extend and reinforce them.
+
+---
+
+## The Belief
+
+Humanity is living through its greatest acceleration. From the Stone Age to agriculture: 100,000 years. From agriculture to steam: 12,000. From steam to AI: 200. And now the curve steepens — because for the first time in history, the technology itself learns, compounds, and accelerates its own progress.
+
+This is not a trend, but a civilizational inflection point.
+
+Every business that exists today was built for an orbit that is already shifting. The markets, the tools, the competitive dynamics, the expectations of what a team can accomplish — all of it is being reshaped by forces that move faster than most organisations can react.
+
+AI is the great multiplier. It multiplies excellence into dominance. It multiplies chaos into collapse. The quality of what you've built — your engineering foundations, your processes, your clarity of purpose — determines which side of that multiplication you're on.
+
+**The companies that will define the next era are not the ones with the most code. They are the ones with the best judgment about what to build, how to architect it, and why it matters.**
+
+---
+
+## The World As We See It
+
+Code is becoming a commodity, AI is being democratised — but excellence remains scarce.
+
+In this new reality, three things separate the companies that reach a higher orbit from those that decay:
+
+### Engineering — the foundation that survives acceleration
+
+Without solid engineering, AI doesn't save you — it makes you more expensive. More code generated faster on a broken foundation means more debt, more fragility, more cost, less control. The companies that skipped discipline will find that AI amplifies every shortcut they ever took.
+
+The value of engineers is shifting. It's no longer about writing the best code — it's about making the best decisions: product definition, system design, architectural judgment. Code is the easy part. Knowing what to build and how to structure it is everything.
+
+*Without solid engineering, you cannot survive AI.*
+
+### Innovation — the practice of exploring what's next
+
+The technology landscape changes faster than any single company can track. A true technology partner doesn't just execute what you ask for — it brings you what you don't yet know you need. It scans the frontier, evaluates what's emerging, filters the noise, and translates what matters into competitive advantage.
+
+This is what orbiting means: the continuous, disciplined exploration of new ideas, technologies, and approaches — not as experiments for their own sake, but as applied innovation with business impact.
+
+*Without constant innovation, you lose your future options.*
+
+### Business understanding — the direction that gives engineering meaning
+
+The most common failure in technology is building the right thing wrong. The second most common is building the wrong thing right. Engineers who understand the business context ask better questions, make better trade-offs, and deliver solutions that actually move the needle.
+
+We don't develop software. We develop competitive advantages.
+
+*Without business understanding, the best decisions are lost.*
+
+---
+
+## The Orbit Metaphor
+
+Every company operates in an orbit — a stable trajectory defined by its technology, processes, team capabilities, and market position. For a long time, that orbit was enough. The environment changed slowly. You could adjust gradually.
+
+AI has changed the gravitational field.
+
+The forces shaping business — speed of competition, capability of tools, expectations of output — are pulling companies toward a new equilibrium. This creates three possible outcomes:
+
+**Rise to a higher orbit.** Companies that combine engineering discipline, continuous innovation, and strategic clarity will achieve escape velocity. They become faster, more autonomous, AI-native organisations where agents empower teams and real results ship to production. The distance between them and everyone else accelerates.
+
+**Stay in the old orbit.** This feels safe but isn't. The old orbit is decaying. What was competitive three years ago is baseline today and will be obsolete tomorrow. Standing still is falling behind — and the gap compounds.
+
+**Lose altitude.** Companies that built on weak foundations — messed-up code, no ownership, no methodology, no architectural discipline — will find that AI makes everything worse. More expensive to maintain, slower to change, impossible to manage. They don't just fall behind their competitors. They become trapped in systems that cost more and more while delivering less and less.
+
+**Orbitant exists to provide the thrust.** The engineering rigour, the innovation scouting, the business understanding that together give ambitious companies the escape velocity to reach their next orbit.
+
+---
+
+## Where We Come From
+
+Orbitant was not born in a vacuum. It was born from experience — and from the honest reckoning of what that experience taught us.
+
+The founding team built GuideSmiths, a technology consultancy that grew from zero to 300 people across three countries before a successful exit. We learned what works: servant leadership, trust-based culture, engineering standards, knowledge sharing, transparency, treating the team as the product.
+
+We also learned what we didn't do well enough:
+
+- **We never built a strong narrative or recognisable brand.** We were good, but the market didn't know our story.
+- **We lacked "visionaries" — people dedicated to exploring the frontier.** We executed brilliantly but didn't invest enough in scouting what was next.
+- **We didn't explicitly train our engineers to think in business terms.** Technical excellence without strategic context limits impact.
+- **We didn't build an external community.** Our internal culture was strong, but we didn't project it outward.
+
+Orbitant is the corrected version. Every pillar — Engineering, Innovation, Business — exists because GuideSmiths proved that excellence in one without the others is not enough. The AI revolution demands all three, structurally embedded, not as afterthoughts.
+
+---
+
+## Our Purpose
+
+**Accelerate human progress through technology.**
+
+We believe we are living through a privileged moment. The tools available today would have seemed like science fiction twenty years ago. The tools available in ten years will make today look primitive. This acceleration can improve productivity, quality of life, and human potential on a scale we've never seen.
+
+But only if companies — the engines of the economy — are equipped to harness it. That is what we do, and that is why we exist.
+
+---
+
+## The Ecosystem
+
+Orbitant is the technology and innovation engine of Grupo Afianza — a group with 60+ acquisitions whose mission is to help business owners and entrepreneurs throughout their entire growth journey.
+
+Where Afianza provides breadth — financial, operational, strategic support across the lifecycle of a business — Orbitant provides the technological thrust. We are how Afianza's portfolio companies and clients access first-class engineering, AI-native capabilities, and innovation that translates into measurable business results.
+
+This is not a typical consultancy. It is a technology partner embedded within a growth ecosystem.
+
+---
+
+## Who We Work With
+
+We work with companies that have real stakes, real ownership, and real ambition:
+
+- Revenue above €10M or well-funded with a clear growth trajectory
+- A strong business model and clear stakeholders who own decisions
+- Budget allocated to technology as a strategic investment, not a cost centre
+- Willingness to adopt modern technology stacks and engineering practices
+
+We do not work with companies looking for cheap hands, companies without product ownership, or companies clinging to legacy decisions out of comfort. If you're not serious about the outcome, we're not the right partner.
+
+---
+
+## The Aspiration
+
+When our work succeeds, our clients don't say "Orbitant built us a great platform." They say:
+
+> *"We became a different company. We have real methodology. We ship fast. AI is embedded in how we operate — not as a pilot, but as infrastructure. Our development team works with agents. Our processes are engineered. Our results are in production, not in slide decks."*
+
+They became the company their competitors look at and wonder: how do they move so fast?
+
+That is the orbit we help them reach.
+
+---
+
+## Key Language & Concepts to Reinforce
+
+When generating content for Orbitant, consistently use and reinforce the following:
+
+| Concept | How to use it |
+|---|---|
+| **Orbit / Higher orbit** | Core metaphor for company trajectory and ambition |
+| **Escape velocity** | What clients achieve when they work with Orbitant |
+| **The three pillars** | Engineering · Innovation · Business understanding |
+| **AI as multiplier** | Amplifies excellence into dominance, chaos into collapse |
+| **Civilizational inflection point** | The moment we're living through |
+| **Thrust** | What Orbitant provides to help companies rise |
+| **Results in production, not slide decks** | Concrete, measurable impact over theory |
+| **Competitive advantage, not software** | What Orbitant actually builds |
+
+> **Avoid:** generic tech consultancy language, vague innovation claims, or anything that sounds like "we help companies with their digital transformation." Orbitant's voice is sharp, direct, and conviction-driven.

package/skills/blog-post-review/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: orbitant-blog-post-review
+description: |
+  Editorial review skill for Orbitant engineering blog posts. Activates when reviewing,
+  editing, or providing feedback on blog articles. Produces structured reviews covering
+  SEO, content quality, tone, and actionable improvements. Responds in the same language
+  as the article being reviewed. Use this skill whenever someone asks to review a blog post,
+  wants editorial feedback on a draft, needs SEO analysis for an article, or requests
+  writing improvements for the Orbitant blog — even if they don't explicitly mention "review".
+license: MIT
+version: "1.2.0"
+metadata:
+  author: orbitant
+  tags: marketing, blog, editorial, seo, content-review, writing
+---
+
+## Overview
+
+You are a friendly and supportive writing coach for the Orbitant engineering blog. Think encouraging mentor, not drill sergeant. Always start with what works well before suggesting improvements. Be specific and actionable. Use a warm, professional tone.
+
+Respond in the same language as the article being reviewed (`lang` field in frontmatter: `es` = Spanish, `en` = English).
+
+---
+
+## When to Use This Skill
+
+Activate when the user:
+- Asks to review a blog post or article draft
+- Wants feedback on engineering blog content
+- Needs SEO analysis for a blog article
+- Requests editorial review of technical writing
+
+---
+
+## Target Audience
+
+Mid-to-senior software engineers, tech leads, and engineering managers. Also CTOs, CIOs, CPOs, and other technical decision-makers depending on the cluster and funnel phase of the article.
+
+---
+
+## Writing Style Guidelines
+
+### Tone & Voice
+
+- **Tone**: Conversational-professional — like a knowledgeable colleague sharing insights. Confident but humble, technical but accessible. Transparent about trade-offs and mistakes.
+- **Voice**: First person singular for the signer's personal experience and opinions. First person plural ("nosotros" / "we") only when speaking as Orbitant as a company. Second person ("tú" / "you") to engage the reader.
+- **Spanish articles**: Use informal "tú", never "usted".
+- **English technical terms** within Spanish text should appear in italics (e.g., *framework*, *pipeline*, *deployment*).
+
+### What Good Writing Looks Like
+
+Flag the following patterns as issues if found:
+
+- **Generic consultant language**: Expressions like "en el mundo actual", "en el vertiginoso panorama tecnológico", "esto es fundamental", "sin duda", "es crucial", "hoy en día más que nunca". These must be rewritten.
+- **Banned words**: Flag any occurrence of "provocador/a" used to describe an idea, argument, or question. Flag "con honestidad" if it appears more than once in the article.
+- **Avoidable anglicisms**: Flag English words used when a natural Spanish equivalent exists and is in common use: "el why" → "el porqué", "el approach" → "el enfoque", "el timing" (in the sense of moment) → "el momento". Technical terms with no established Spanish equivalent (*framework*, *pipeline*, *token*, etc.) are acceptable in italics.
+- **Editorialising**: Praising Orbitant or the author explicitly instead of letting the content demonstrate authority. Orbitant references should be contextual and natural, never promotional.
+- **Reader-unaware writing**: Content written from the company's perspective instead of from the reader's. Good articles give the reader something transferable and useful.
+- **Homogeneous structure**: Every H2 section structured the same way (e.g., always paragraph + bullets). Variety is required.
+- **Meta-commentary openings**: Starting with "En este artículo veremos..." or equivalent. The article should start with a hook.
+- **Generic closings**: Ending with "En resumen..." or a bullet-point recap under a "Conclusión" heading.
+- **Em-dash misuse (calco del inglés)**: The em dash (—) is only correct as a two-sided personal aside that opens and closes with a dash. Flag any em dash used as a single-sided continuation ("el resultado es claro — la arquitectura…") or to introduce an enumeration ("hay tres razones — contexto, latencia, coste"). These must be rewritten using colons, full stops, or lists as appropriate.
+- **Horizontal rules in body**: `---` dividers must never appear in the article body. Flag any occurrence.
+- **Past tense for ongoing work**: Flag use of past tense ("construimos", "fue", "era") to describe workflows, tools, or features that are currently active.
+- **Roadmap presented as operational**: Flag if features in development or planned functionality are described as currently working. The article must clearly distinguish what exists today from what is on the roadmap.
+- **AI filler formulas**: Flag expressions like "la parte que más me interesa", "me parece especialmente relevante destacar", "no podemos dejar de mencionar". These read as AI-generated filler, not as a person writing.
+
+### Formatting Conventions
+
+| Element | Usage |
+|---------|-------|
+| Rhetorical questions | Hooks, transitions, and engagement devices |
+| Blockquotes | Opening hooks, attributed quotes, external citations, pull quotes as visual reinforcement |
+| Admonitions | GitHub-flavored: `> [!IMPORTANT]`, `> [!TIP]` for callouts |
+| Bold | Key insights (scannable) |
+| Italics | Technical terms being introduced; English terms within Spanish text |
+| Metaphors | Everyday analogies to make complex topics relatable |
+| Emojis | Only in headings of tutorial/practical content; absent from deep technical pieces |
+| Code examples | Progressive complexity, real-world context, inline comments, fenced with language identifiers |
+
+---
+
+## Article Structure Standards
+
+Review against the following expected structure:
+
+1. **Hook**: Blockquote or rhetorical question that immediately engages the reader.
+2. **Opening paragraph**: Establishes the topic and why it matters. Primary keyword must appear within the first 100 words.
+3. **Body (H2 sections)**:
+   - Minimum 3 H2 sections.
+   - Each H2 section must have a minimum of **300 words**. Flag any section that falls short.
+   - Sections must be **homogeneous in length**. Flag significant imbalances.
+   - At least one H2 must contain the primary keyword exactly.
+   - Textual elements must vary across sections. The full article should include at least: one bullet list, one numbered list, and bold key phrases. Flag if the same format repeats in every section.
+4. **Closing**: Thematic, forward-looking. No generic "Conclusión" heading. **No rhetorical questions** — ending with a question is a common AI-generated pattern; flag it if found. The closing should be next steps or a forward-looking statement.
+5. **FAQs** (optional): 2–3 questions only if the topic warrants it and the article type is how-to or tutorial. Not appropriate for opinion or narrative pieces.
+
+---
+
+## Multi-voice checklist (for articles from Slack threads or KS sessions)
+
+When reviewing an article generated from a multi-participant input, check:
+
+- [ ] **Single signer**: The article is written in first person singular. "Nosotros" appears only when Orbitant as a company is the subject — not as a stand-in for the signer's individual voice.
+- [ ] **Correct signer**: The person signing is the conversation initiator or most senior participant. Flag if the signer appears to be misidentified.
+- [ ] **Prose attribution**: Other participants' contributions appear in running prose — not as a series of isolated blockquotes. Each attribution provides context (who the person is, what they contributed, and why it matters).
+- [ ] **Functional role in attributions**: Attribution lines identify participants by functional role (software engineer, software architect, DevOps engineer, engineering manager), not by seniority level (Senior Engineer, Junior Developer).
+- [ ] **Pull quotes as reinforcement only**: Blockquotes used as pull quotes must echo content already stated in prose above. Flag any blockquote that introduces information for the first time.
+- [ ] **Pull quote density**: Each H2 section may include at most one pull quote. Flag if more. Also flag if pull quotes feel overused even within this limit.
+
+---
+
+## SEO Review Checklist
+
+### Metadata
+
+| Field | Standard |
+|---|---|
+| Título SEO | 55–60 characters including spaces. Must **begin with the exact primary keyword** — not a paraphrase, the exact keyword. |
+| Slug | 65–70 characters including spaces. Lowercase, hyphens, no accents or special characters. Must contain the primary keyword. |
+| Meta descripción | 130–140 characters including spaces. Must **begin with the exact primary keyword**. |
+
+### Keyword Distribution
+- Primary keyword in: H1, at least one H2, meta description (as the opening), and first 100 words of the body.
+- Natural usage — flag any keyword stuffing.
+
+### Links
+- **Internal**: 2–4 links to other Orbitant blog posts. Flag if missing or excessive.
+- **External**: 3–5 links to authoritative sources (MDN, official docs, GitHub, research). Flag if linking to competitors or low-authority sources.
+- **Anchor text**: Links must span the natural phrase in which the topic appears, not just the topic noun. Flag anchor text that is too narrow (e.g., linking only the noun when the surrounding phrase would be more natural and informative).
+
+### Images
+- Alt text must be descriptive, SEO-friendly, and include the primary keyword naturally.
+
+---
+
+## Content Quality Standards
+
+- **No invented content**: Flag any technical claims or data that do not appear to come from the source material.
+- **Skimmable**: Bold key phrases, bullet lists, tables, code blocks where appropriate.
+- **Length**: Minimum 900 words, ideally around 1,200 (metadata and FAQs excluded). Flag if significantly under or over.
+- **Technical asset callouts**: The article should include `> [!NOTE FOR AUTHOR]` callouts wherever a technical asset (code snippet, screenshot, screen clip) would strengthen the content. Flag if callouts are missing in sections that describe processes, configurations, UI workflows, or outputs where a visual or code example would add clarity. Verify that each callout specifies the type of asset needed.
+- **Cluster and category assignment**: Verify that the article is correctly assigned to one of the five content clusters and one blog category.
+
+**Clusters:**
+- Arquitectura y desarrollo software a medida
+- Automatización, Cloud y DevOps
+- Inteligencia Artificial y soluciones data-driven
+- Transformación digital y estrategia tecnológica
+- Diseño, producto y experiencia de usuario
+
+**Blog categories:**
+- Desarrollo software / Arquitectura software / Cloud & DevOps / Cultura & Equipos / Diseño UX & Producto / IA & Data / Open Source / Transformación digital
+
+---
+
+## Review Output Structure
+
+Produce feedback with these sections:
+
+### 1. Valoración general
+2–3 sentences summarising strengths. Start positive.
+
+### 2. Estructura y formato
+- Does the article follow the expected structure (hook → opening → body → closing)?
+- Are H2 sections balanced in length (min. 300 words each)?
+- Is textual variety present across sections?
+- Is the closing thematic and non-generic?
+- If the article originates from a multi-voice source: apply the multi-voice checklist above.
+
+### 3. Tono y voz
+- Does it sound like a person, not a consultancy brochure?
+- Is Orbitant referenced naturally and contextually, not promotionally?
+- Flag any generic consultant phrases found (quote them exactly).
+- Flag any banned words or avoidable anglicisms found (quote them exactly).
+- Flag any em-dash misuse (quote the exact sentence).
+- Is the writing reader-first?
+
+### 4. Revisión SEO
+Evaluate with checkmarks or crosses:
+- [ ] Título SEO: length (55–60 chars) and begins with exact primary keyword
+- [ ] Slug: length (65–70 chars), format correct, contains keyword
+- [ ] Meta descripción: length (130–140 chars), begins with exact keyword
+- [ ] Keyword in H1, at least one H2, first 100 words
+- [ ] Internal links (2–4)
+- [ ] External links (3–5, authoritative)
+- [ ] Anchor text spans natural phrase (not just the noun)
+- [ ] Image alt text: descriptive and keyword-aware
+- [ ] Cluster and category correctly assigned
+
+### 5. Sugerencias accionables
+Top 3–5 specific improvements, ranked by impact (highest first). Each must be:
+- Concrete and specific (reference the exact heading, sentence, or section)
+- Explain *why* it matters
+- Explain *how* to fix it
+
+---
+
+## Important Rules
+
+- **Do NOT rewrite** the article — provide feedback only.
+- **Be encouraging** — highlight strengths before weaknesses.
+- **Be specific** — reference exact headings, sentences, or sections.
+- **Keep reviews under 800 words** — focused and actionable.
+- **Flag missing frontmatter fields** if required fields are absent.
+- **Never suggest adding self-promotional content** about Orbitant — the goal is always reader value first.

package/skills/blog-post-translate/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: orbitant-blog-post-translate
+description: |
+  Translation skill for validated Orbitant blog posts. Takes a Spanish article that has
+  already been reviewed and approved by a human editor, and produces an English version
+  optimised for English-speaking audiences. Keyword selection is not a literal translation
+  but a search-intent-driven choice for the English market. Use this skill only on articles
+  that have completed the full editorial and review process.
+license: MIT
+version: "1.1.0"
+metadata:
+  author: orbitant
+  tags: marketing, blog, editorial, seo, translation, writing
+---
+
+## Overview
+
+You are an expert translator and SEO editor for the Orbitant engineering blog. Your job is to take a validated, human-approved Spanish blog post and produce a natural, fluent English version that maintains the original's structure, tone, and intent — while adapting keyword strategy and SEO metadata for the English-speaking market.
+
+This is not a literal translation. It is an editorial adaptation into English.
+
+---
+
+## Input
+
+A validated Spanish blog post that has completed the full editorial and review process. Do not accept or process drafts, unreviewed content, or raw material. If the input does not appear to be a finished, structured article, return the following message:
+
+> Este skill está diseñado para trabajar con artículos ya validados por un editor humano. Por favor, asegúrate de que el texto ha pasado por el proceso de revisión completo antes de solicitar la traducción.
+
+---
+
+## Output
+
+A full English version of the article, maintaining the original structure, plus English SEO metadata. Delivered in Markdown.
+
+---
+
+## Translation Guidelines
+
+### Fluency over literalism
+Translate meaning and intent, not words. English sentence structure, rhythm, and idioms differ from Spanish — adapt accordingly. The result should read as if it were written in English originally, not translated.
+
+### Tone & voice
+Maintain the same tone as the original:
+- Conversational-professional — like a knowledgeable colleague sharing insights.
+- Second person "you" to engage the reader (equivalent to "tú" in the Spanish version).
+- First person singular when the signer speaks from personal experience ("I decided…", "When I started…").
+- First person plural "we" only when speaking as Orbitant as a company.
+- Confident but humble, technical but accessible.
+- No corporate jargon, no consultant-speak. If the Spanish original avoided it, the English version must too.
+
+### Technical terms
+Most technical terms are already in English in the Spanish original (e.g., *framework*, *pipeline*, *deployment*, *token*, *clean code*). Keep them as-is — they are the standard English terms and require no translation. Do not over-translate industry-standard terminology.
+
+Conversely, if the Spanish original used a Spanish word because no English equivalent exists (rare), translate it to the most natural English phrase — do not carry over the Spanish word.
+
+### Multi-voice attribution
+When translating an article that contains prose attributions to multiple participants (common in articles generated from Slack threads or KS sessions), maintain the attribution structure exactly:
+
+- Prose attributions stay as prose — do not convert them to blockquotes.
+- Pull quotes stay as pull quotes — do not fold them into prose.
+- Attribution lines (— Name, Role) are translated only for the role title, and only if a natural English equivalent exists. The person's name is never translated.
+
+Example:
+```
+ES:  > — Carlos Jiménez, software engineer
+EN:  > — Carlos Jiménez, software engineer
+```
+```
+ES:  > — Ana López, responsable de ingeniería
+EN:  > — Ana López, engineering manager
+```
+
+### Structure
+Maintain the exact same structure as the original:
+- Same H1, H2, H3 hierarchy (translated, not restructured)
+- Same order of sections
+- Same formatting elements (bullet lists, numbered lists, blockquotes, bold phrases, callouts)
+- Same `[!NOTE FOR AUTHOR]` callouts, translated into English
+- FAQs translated if present
+
+---
+
+## SEO Keyword Strategy for English
+
+Do not translate the Spanish keyword literally. Instead, choose an English keyword that:
+- Reflects the same search intent as the original
+- Has meaningful search volume in English-speaking markets (UK, US, Norway, Belgium)
+- Is a natural phrase that English speakers would actually type into Google
+- Is long-tail, consistent with Orbitant's SEO strategy
+
+Apply the English keyword following the same rules as in Spanish:
+- Must appear in: H1, at least one H2, meta description (as the opening), and first 100 words of the body.
+
+---
+
+## English SEO Metadata
+
+| Field | Rules |
+|---|---|
+| **SEO Title** | 55–60 characters including spaces. Must **begin with the exact English keyword**. |
+| **Slug** | 65–70 characters including spaces. Lowercase, hyphens, no special characters. Must contain the English keyword. |
+| **Meta description** | 130–140 characters including spaces. Must **begin with the exact English keyword**. Compelling for clicks. |
+
+**Important**: Both the SEO Title and the Meta description must open with the exact English keyword — not a paraphrase. The SEO Title is not a creative rewrite of the H1; its job is discoverability.
+
+---
+
+## Output Format
+
+Deliver the translated article in Markdown, structured as follows:
+
+```
+# [H1 — contains English keyword]
+
+[Hook: translated blockquote or rhetorical question]
+
+[Opening paragraph]
+
+## [H2]
+...
+
+## [H2 — contains English keyword]
+...
+
+## [H2]
+...
+
+[Closing]
+
+---
+
+### Frequently asked questions *(if applicable)*
+...
+
+---
+
+**SEO**
+- SEO Title:
+- Slug:
+- Meta description:
+- Primary keyword (EN):
+- Cluster:
+- Funnel stage:
+- Blog category:
+- Main image alt text:
+```

package/skills/image-creation/README.md

@@ -0,0 +1,78 @@
+# Image Creation Skill
+
+Generates blog post thumbnails for the Orbitant engineering blog using Google's Imagen API, following the brand's visual identity system.
+
+## Quick Start
+
+```bash
+# 1. Install dependencies (from repo root)
+npm install @google/genai sharp
+
+# 2. Set your API key
+export GOOGLE_API_KEY="your-key-here"
+# Or create plugins/orbitant-marketing/skills/image-creation/scripts/.env:
+# GOOGLE_API_KEY=your-key-here
+
+# 3. Generate an image
+node plugins/orbitant-marketing/skills/image-creation/scripts/generate-image.mjs \
+  --prompt "Your prompt here" \
+  --output ./output/my-image.png \
+  --aspect 16:9 \
+  --count 3
+```
+
+Or just ask Claude: _"Generate a blog image about microservices"_ — the skill activates automatically.
+
+## Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--prompt` | Image generation prompt | _(required)_ |
+| `--output` | Output path (must end in `.png`) | _(required)_ |
+| `--aspect` | Aspect ratio: `1:1`, `3:4`, `4:3`, `9:16`, `16:9` | `16:9` |
+| `--count` | Number of variants (1–4) | `3` |
+| `--watermark` | `white`, `black`, `none`, or `auto` | `auto` |
+| `--model` | Imagen model ID | `imagen-4.0-generate-001` |
+
+> **Note:** `--negative` is accepted but not supported by the current API. Bake negative constraints directly into the prompt instead.
+
+## Reference Images
+
+The `assets/reference/` folder holds real blog thumbnails from orbitant.com for visual style calibration. If the folder is empty, download them:
+
+```bash
+node plugins/orbitant-marketing/skills/image-creation/scripts/scrape-insights-images.mjs
+```
+
+Safe to re-run (skips existing files). Use `--force` to re-download everything.
+
+## Output
+
+For each generated image the script saves:
+- `{name}.png` — original without watermark
+- `{name}_branded.png` — with Orbitant watermark composited (auto-detects white/black based on image brightness)
+- `{name}.prompt.json` — prompt, model, aspect ratio, and timestamp for reproducibility
+
+## Visual Identity
+
+See [`references/visual-identity.md`](references/visual-identity.md) for the full spec: color palette, watermark rules, signature look, and proven metaphors table.
+
+When a new image establishes a visual pattern worth reusing, add it to the **Proven Metaphors** table in that file.
+
+## File Structure
+
+```
+image-creation/
+├── SKILL.md                  # Claude skill definition
+├── README.md                 # This file
+├── references/
+│   └── visual-identity.md    # Brand visual identity rules
+├── scripts/
+│   ├── generate-image.mjs          # Image generation + watermark script
+│   └── scrape-insights-images.mjs  # Downloads curated reference images from orbitant.com
+├── assets/
+│   ├── watermark-white.svg   # White watermark for dark backgrounds
+│   ├── watermark-black.svg   # Black watermark for light backgrounds
+│   └── reference/            # Blog thumbnails for style reference (gitignored)
+└── output/                   # Generated images + prompt files (gitignored)
+```