@orbitant/brain-marketing 1.5.0

package/skills/tone/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: orbitant-tone
+description: |
+  Voice and tone reference for Orbitant blog content. Defines what Orbitant writing
+  sounds like, what it values, and what it avoids — with concrete examples.
+
+  Activate when user asks about Orbitant voice, tone, writing style, brand voice,
+  or editorial guidelines. Also trigger when reviewing blog content for consistency,
+  checking if text "sounds like Orbitant", or when creating/editing marketing content
+  — even if they don't explicitly mention tone or voice.
+version: "1.1.0"
+license: MIT
+metadata:
+  author: orbitant
+  tags: marketing, blog, tone, voice, editorial
+---
+
+# Orbitant Tone of Voice
+
+This document defines how Orbitant writes. It is a reference for anyone creating or reviewing blog content — whether you are a human contributor or the content generation agent.
+
+Orbitant's writing reflects how the team actually thinks and works: with technical rigour, intellectual honesty, and a clear connection to real-world impact. We do not write to impress. We write to be useful.
+
+---
+
+## Core principles
+
+### 1. First person, always
+Write from your own experience. Use "I" when sharing something you lived, decided, or learned. Use "we" when speaking as Orbitant as a company. Never write in the third person about your own work or decisions — it creates distance and makes the content feel generic.
+
+> ✅ **Así sí**
+> Cuando empezamos a migrar el sistema de autenticación, lo primero que hicimos fue mapear todos los puntos de entrada. No porque lo diga ninguna guía, sino porque habíamos quemado semanas en una migración anterior por saltarnos ese paso.
+
+<!-- -->
+
+> ❌ **Así no**
+> Las empresas que afrontan migraciones de sistemas de autenticación deben considerar mapear todos los puntos de entrada como primer paso del proceso.
+
+---
+
+### 1b. Multi-voice content: Slack threads, KS sessions, and group conversations
+
+Many Orbitant articles originate from group conversations — a Slack thread that sparked a debate, a KS session where several engineers shared their take. These are multi-voice inputs that need a single editorial voice.
+
+**The rule**: one article, one signer, first person singular.
+
+The signer is the person who initiated the conversation or the most senior participant. Everyone else's contribution lives in the article as prose attribution — not as a series of isolated quotes.
+
+The prose pattern is: context sentence → attribution phrase (name + functional role) → the person's actual point, paraphrased or quoted depending on whether the phrasing itself is what matters.
+
+> ✅ **Así sí**
+> Kevin llevaba semanas midiendo el consumo de tokens entre ambos enfoques y sus números apuntaban en la misma dirección: con arquitectura hexagonal, el agente necesitaba entre tres y cinco veces más contexto para completar el mismo cambio.
+
+<!-- -->
+
+> ❌ **Así no**
+> Kevin dijo: "Con arquitectura hexagonal, el agente necesita mucho más contexto."
+
+The prose version gives context, stakes, and continuity. The quote version is a telegram. The first reads like an article; the second reads like a transcript.
+
+**Pull quotes**: After integrating a contribution into prose, you may extract one memorable phrase as a visual pull quote — a blockquote that echoes what the prose already said. This is visual decoration, not content delivery. The content lives in the prose. Pull quotes lose their effect if overused — use them sparingly and only for phrases that are genuinely worth emphasising.
+
+**Attribution format**: Identify participants by name and functional role. Examples: software engineer, software architect, DevOps engineer, engineering manager, QA engineer. Do not use seniority levels (Senior, Junior, Lead) as the identifier.
+
+---
+
+### 2. Real examples over abstract theory
+Every claim should be grounded in something concrete: a project, a decision, a failure, a result. If you cannot think of a real example, that is a signal that the section needs more thought — not more words.
+
+Theory is only useful when it explains a real situation. Lead with the example, then explain the principle behind it.
+
+> ✅ **Así sí**
+> Teníamos un pipeline que tardaba 22 minutos en completarse. Después de perfilar cada paso, encontramos que el 60% del tiempo lo consumía un único test de integración que se conectaba a una base de datos real. Lo reemplazamos por un mock y bajamos a 8 minutos.
+
+<!-- -->
+
+> ❌ **Así no**
+> Optimizar los tiempos de ejecución de los pipelines de CI/CD es fundamental para mejorar la productividad de los equipos de desarrollo y reducir el time-to-market.
+
+---
+
+### 3. Explain the why behind technical decisions
+Do not just describe what you did. Explain why you chose that approach over the alternatives, what you ruled out and why, and what trade-offs you accepted. This is what makes technical content genuinely useful — and what distinguishes Orbitant's voice from generic documentation.
+
+> ✅ **Así sí**
+> Elegimos SQLite para el almacenamiento local por tres razones: no necesitábamos un servidor separado, el volumen de datos era predecible y pequeño, y queríamos que cualquier desarrollador pudiera levantar el proyecto sin configuración adicional. Valoramos PostgreSQL, pero añadía complejidad operativa que no estábamos dispuestos a asumir en ese contexto.
+
+<!-- -->
+
+> ❌ **Así no**
+> Para el almacenamiento local se utilizó SQLite, una solución ligera y eficiente ampliamente utilizada en el sector.
+
+---
+
+### 4. Practical over theoretical
+Prioritise content that the reader can apply. Code snippets, configuration examples, screen recordings, annotated screenshots — these are worth more than three paragraphs of explanation. When you can show something, show it.
+
+The ideal structure for a technical section is:
+1. State the problem or decision
+2. Show the solution (code, screenshot, clip)
+3. Explain what matters and why
+
+> ✅ **Así sí**
+> Para evitar que las variables de entorno se filtren en los logs, añadimos un middleware de sanitización antes del logger:
+>
+> ```typescript
+> app.use(sanitizeEnvMiddleware());
+> app.use(logger());
+> ```
+>
+> El orden importa: si inviertes las dos líneas, el logger captura los datos antes de que se saniticen.
+
+<!-- -->
+
+> ❌ **Así no**
+> Es importante gestionar correctamente las variables de entorno para garantizar la seguridad de las aplicaciones. Existen diversas estrategias para evitar que información sensible quede expuesta en los registros del sistema.
+
+---
+
+### 5. Honest about trade-offs and mistakes
+Good technical writing acknowledges what did not work, what could be better, and what limitations exist. Readers trust content more when it is honest about complexity. Do not oversell solutions. Do not hide the hard parts.
+
+> ✅ **Así sí**
+> Este enfoque funciona bien cuando el equipo es pequeño y los dominios están bien delimitados. Si tienes más de cuatro o cinco equipos trabajando en paralelo, empieza a aparecer fricción en los límites — y probablemente necesites una estrategia de ownership más explícita.
+
+<!-- -->
+
+> ❌ **Así no**
+> Esta solución es escalable y puede adaptarse a equipos de cualquier tamaño, garantizando la eficiencia operativa en todo momento.
+
+---
+
+## What Orbitant writing is not
+
+- **Not a brochure**: We do not write to sell Orbitant. We write to share what we know. If the content is genuinely useful, it speaks for itself.
+- **Not neutral**: We have opinions. We explain why we prefer certain approaches, tools, or patterns. We do not hedge every sentence to avoid taking a position.
+- **Not formal**: We do not use "usted", corporate passive voice, or expressions like "cabe destacar que", "en el contexto actual", "es de vital importancia". We write like we talk — clearly and directly.
+- **Not theoretical**: We do not write about how things should work in an ideal world. We write about how they work in practice, with real constraints and real consequences.
+
+---
+
+## Words and patterns to avoid
+
+These specific words and patterns degrade Orbitant's voice when they appear in published content. Treat them as red flags in any review.
+
+| Pattern | Problem | Instead |
+|---|---|---|
+| "con honestidad" | Hollow filler — implies other parts are dishonest. Acceptable at most once per article; flag if repeated. | Say the thing directly |
+| "provocador/a" (for ideas or arguments) | Sounds like business magazine copy, not a technical colleague | Describe what specifically challenges or unsettles: "la pregunta incómoda es…" |
+| "en el mundo actual" | Journalist cliché, adds no information | Delete, or replace with the specific context |
+| "es crucial / fundamental" | Tells the reader what to think without showing why | Show the consequence instead |
+| "sin duda" | Hollow intensifier | Delete |
+| "hoy en día más que nunca" | Timeless cliché | Delete |
+| "el why" (when a Spanish equivalent exists) | Avoidable anglicism | "el porqué" |
+| "el approach" | Avoidable anglicism | "el enfoque" |
+| "el timing" (in the sense of "moment") | Avoidable anglicism | "el momento" |
+| "la parte que más me interesa" | AI-sounding filler — no real person writes like this | State the point directly |
+| "me parece especialmente relevante destacar" | AI hedging + filler preamble | Delete the preamble; state the point |
+| "no podemos dejar de mencionar" | Filler | State the point directly |
+
+Technical English terms with no consolidated Spanish equivalent (*framework*, *pipeline*, *deployment*, *token*, *clean code*, *contract testing*) are kept in English and in italics. This list targets words that have a natural Spanish equivalent but get replaced by English out of habit, not necessity.
+
+---
+
+## Style note: em-dash usage (—)
+
+The em dash in Spanish marks **two-sided personal asides** — an inciso that opens and closes with a dash. This is its only correct use in Orbitant writing.
+
+> ✅ **Así sí**
+> Esta decisión —y es algo que Kevin midió durante semanas— tiene un coste real en tokens y latencia.
+
+<!-- -->
+
+> ❌ **Así no (calco del inglés)**
+> El resultado es claro — la arquitectura añade fricción innecesaria.
+> Hay tres motivos — contexto, latencia, coste.
+
+For continuations, use a colon or a full stop. For enumerations, use a list or "x, y, y z" in prose. A single-sided em dash is an anglicism — it does not exist in Spanish punctuation. Flag it in any review.
+
+---
+
+## On mentioning Orbitant
+
+Orbitant can and should appear in blog content — but as context, not as the subject. The subject is always the technical problem, the decision, or the learning.
+
+> ✅ **Así sí**
+> En Orbitant llevamos varios proyectos usando esta arquitectura en producción, y el patrón que mejor nos ha funcionado es...
+
+<!-- -->
+
+> ❌ **Así no**
+> En Orbitant, empresa líder en consultoría de software de nueva generación, hemos desarrollado una metodología propia que...
+
+---
+
+## Asset guidelines
+
+Technical assets are a priority, not an optional extra. When writing about a process, a configuration, or a result, always consider whether a visual or code example would communicate it better than prose.
+
+| Situation | Preferred asset |
+|---|---|
+| Setup or configuration steps | Code snippet |
+| UI workflow or interaction | Annotated screenshot or short screen clip |
+| Before/after comparison | Side-by-side code blocks |
+| System output or result | Screenshot or code output block |
+| Process with multiple steps | Numbered list + clip if the steps involve UI |
+| Architecture, flows, or system relationships | Excalidraw diagram |
+| Decision trees or comparisons between approaches | Excalidraw diagram |
+
+Orbitant accounts have Excalidraw connected to Claude, which makes it straightforward to generate and iterate on diagrams directly. Prefer Excalidraw over static images for anything that represents a system, a flow, or a relationship between components — diagrams created this way are editable and can be updated as the content evolves.
+
+If you cannot include the asset at the time of writing, leave a note in the draft using the following format so it can be added later:
+
+```markdown
+> [!NOTE FOR AUTHOR]
+> Descripción del asset que falta aquí y por qué aporta valor.
+> Tipo de asset sugerido: código | captura | clip | diagrama Excalidraw
+```

package/skills/yt-description/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: orbitant-yt-description
+description: |
+  YouTube video description generator for Orbitant Knowledge Sharing (KS) sessions.
+  Takes a session transcript (.vtt or plain text) and produces a bilingual, SEO-optimised
+  YouTube description — Spanish first, then English — built around a positionable keyword.
+  The description is structured to rank in YouTube and Google search: keyword in the first
+  line, natural repetition in the overview and takeaways, and hashtags chosen for search
+  intent, not just labels. Use this skill whenever someone needs to write or generate a
+  YouTube description for a KS session or any Orbitant video — even if they just say
+  "escribe la descripción del vídeo", "I need the YouTube copy", or "help me upload this
+  session". Also trigger when given a transcript and asked to prepare anything for a
+  video upload.
+license: MIT
+version: "1.0.0"
+metadata:
+  author: orbitant
+  tags: marketing, youtube, seo, video, content, ks-sessions, description, bilingual, keywords
+---
+
+## Overview
+
+You are writing the YouTube description for an Orbitant Knowledge Sharing session. The description does two things at once: it convinces a viewer who lands on the page to watch, and it tells YouTube and Google what the video is about so it surfaces in relevant searches.
+
+**Positioning is the primary goal.** A technically accurate description that nobody finds is worthless. Every structural decision — the first sentence, the takeaways, the hashtags — must serve the keyword strategy.
+
+Read the transcript in full before writing anything. Do not invent content not present in the input.
+
+---
+
+## Step 1 — Keyword research (do this first)
+
+Before writing a single line of description, identify the keyword strategy for the video.
+
+### Primary keyword (one per language version)
+
+The primary keyword is the search phrase a potential viewer would type into YouTube or Google to find this content. It must:
+- Reflect what the session **actually teaches**, not just what it's about
+- Be specific enough to have real search intent (someone looking to solve a problem or learn a skill)
+- Be phrased as a user would type it — not how a speaker would title their talk
+
+**Spanish primary keyword examples for KS sessions:**
+- `cómo usar Claude para automatizar contenido`
+- `crear CLI con IA desde cero`
+- `automatizar changelogs con GitHub Actions`
+- `qué es el patrón decorator en programación`
+
+**English primary keyword examples:**
+- `how to build Claude skills for your team`
+- `automate content creation with AI`
+- `CLI tools with AI step by step`
+
+If the user provides a keyword, use it. If not, derive it from the transcript topic — ask yourself: *what would the ideal viewer search for before finding this video?*
+
+### Secondary keywords (2–4 per language version)
+
+Supporting terms that complement the primary keyword. These appear naturally in the takeaways and overview — do not force them. Examples: tool names (Claude, n8n, Astro), technique names (RAG, streaming, decorator pattern), broader category terms (IA generativa, automatización, DevTools).
+
+---
+
+## Step 2 — Language order
+
+- If the session was conducted **primarily in Spanish**: Spanish version first, English version second.
+- If the session was conducted **primarily in English**: English version first, Spanish version second.
+- Both versions are always present. The English is an adaptation, not a literal translation — keyword choice and phrasing must feel natural for an English-speaking audience searching on YouTube.
+
+**Timestamps are not part of this output.** They are added separately after publication.
+
+---
+
+## Step 3 — Write the description
+
+Apply this structure to each language version.
+
+### 1. Opening line (critical for SEO)
+
+The **first 150 characters** of the description are what YouTube shows in search results before "Show more". This is prime real estate.
+
+The opening line must:
+- Contain the **primary keyword** — ideally in the first 10 words
+- State clearly what the viewer will learn or be able to do
+- Stand alone as a compelling reason to click
+
+> Correct: `Aprende a crear Skills de Claude para automatizar la generación de contenido desde transcripts de sesiones.`
+> Incorrect: `Felipe Polo nos habla sobre su experiencia con la IA en el equipo de Orbitant.`
+
+### 2. Speaker intro
+
+After the opening line, introduce the speaker(s) with 🎙️.
+
+**Single speaker:**
+> `🎙️ [Full Name], [Title] en [Company], comparte [one-sentence description of what they teach].`
+
+**Multiple speakers (up to 3):** One line per speaker, each with their name, title, and company. If all speakers share the same company, mention it only once on the last line.
+
+If there are more than 3 speakers, group them: list the two or three most prominent by name and add "junto a [N] expertos más" or "and [N] more experts".
+
+Keep it factual. Avoid superlatives.
+
+### 3. Overview (1–2 short paragraphs)
+
+Describe what the viewer will learn. Write for the person who found this through search — they have a specific problem or curiosity and need to know in 3 sentences whether this video answers it.
+
+The **primary keyword** must appear at least once more here, naturally. Secondary keywords should appear where relevant — not forced, not repeated mechanically.
+
+Avoid: "una sesión muy interesante", "a fascinating discussion", "todo lo que necesitas saber sobre".
+
+### 4. Key takeaways list
+
+Open with:
+- Spanish: `ℹ️ En esta sesión descubrirás:`
+- English: `ℹ️ In this session you'll discover:`
+
+Follow with 4–7 bullet points, each starting with `→`. Each point should:
+- Describe something concrete and actionable
+- Reference real tools, techniques, or decisions from the session
+- Include secondary keywords naturally where they fit
+
+> Correct: `→ Cómo estructurar un pipeline de Claude para generar borradores de blog posts desde transcripts`
+> Incorrect: `→ Técnicas de productividad con IA`
+
+### 5. Resources section
+
+Only include if there are actual resources to list. Open with:
+- Spanish: `🔗 Recursos mencionados en la sesión:`
+- English: `🔗 Resources mentioned in the session:`
+
+List each resource on its own line. If a URL isn't available yet, use a placeholder: `Blog post: [link próximamente]`.
+
+---
+
+## Step 4 — Hashtags
+
+Add 8–12 hashtags after the English version. Always include `#Orbitant`.
+
+Hashtags in YouTube function as category signals, not just labels. Choose them for **search intent**:
+- Always include `#Orbitant` — no exceptions
+- Use tags people actually search for on YouTube, not internal jargon
+- Include the core topic tags (e.g., `#Claude`, `#InteligenciaArtificial`, `#AI`, `#Automatización`)
+- Include tool names if they are searchable (`#n8n`, `#Astro`, `#GitHub`)
+- Include broader category tags to reach adjacent audiences (`#DevTools`, `#ContentMarketing`, `#SoftwareEngineering`)
+- Avoid tags so broad they're meaningless (`#Technology`, `#Video`, `#Learn`)
+- Do NOT replace `#Orbitant` with a compound variant like `#OrbitantKS` or `#OrbitantSessions` — those are additional tags, not substitutes
+
+---
+
+## Separator
+
+Between the Spanish and English sections, and after the hashtags, use this exact separator line:
+
+```
+________________________________________________
+```
+
+---
+
+## Output format
+
+Deliver as **plain text**, ready to paste directly into YouTube. YouTube does not render markdown — no `**bold**`, no `##` headers, no bullet `-` syntax.
+
+```
+[Primary keyword — first sentence of Spanish version]
+
+🎙️ [Speaker intro — Spanish]
+
+[Overview — Spanish, primary + secondary keywords woven in naturally]
+
+ℹ️ En esta sesión descubrirás:
+→ [specific takeaway with secondary keyword]
+→ [specific takeaway]
+→ [specific takeaway]
+→ [specific takeaway]
+
+🔗 Recursos mencionados en la sesión:
+[resource 1]
+[resource 2]
+
+________________________________________________
+
+[Primary keyword — first sentence of English version]
+
+🎙️ [Speaker intro — English]
+
+[Overview — English, adapted for English search intent]
+
+ℹ️ In this session you'll discover:
+→ [specific takeaway]
+→ [specific takeaway]
+→ [specific takeaway]
+→ [specific takeaway]
+
+🔗 Resources mentioned in the session:
+[resource 1]
+[resource 2]
+
+#tag1 #tag2 #Orbitant
+
+________________________________________________
+```
+
+---
+
+## What to avoid
+
+- **No keyword in the opening line**: if the first sentence doesn't contain the primary keyword, the description will not rank.
+- **Vague takeaways**: "aprenderás sobre IA" tells nobody anything. Be specific about tools, techniques, and outcomes.
+- **Literal translation**: the English keyword is a new keyword research exercise, not a translation of the Spanish one.
+- **Descriptive hashtags**: `#KnowledgeSharing` or `#OrbitantSession` have zero search volume. Use tags people actually search.
+- **Invented content**: do not add resources, tools, or claims not present in the transcript.
+- **Timestamps**: not part of this output.