@damiangilgonzalez/harness 1.3.7

package/skills/write-adr/README-TEMPLATE.md

@@ -0,0 +1,32 @@
+# ADR index
+
+An ADR is an architecture decision already made, with its rationale and the
+alternatives that were discarded. **They are read before touching the area they
+cover**, not after.
+
+Rules for this folder:
+
+- **MADR format**, one file per decision: `ADR-NNN-title-in-kebab-case.md`.
+- An ADR **is not edited to change your mind**: a new one is written that
+  replaces it, and the old one is marked *Superseded by ADR-NNN* with the link.
+- An ADR **is not a plan or a design**. Designs and plans live elsewhere and do
+  not replace an ADR.
+
+## Where to start depending on what you're touching
+
+### Area
+
+| ADR | What it's about | Status |
+|---|---|---|
+| `[001](./ADR-001-title.md)` | What it decides and when to read it. | Accepted |
+
+### Retired or superseded
+
+| ADR | What happened |
+|---|---|
+
+## When a new ADR is needed
+
+A structural refactor, a major dependency change, an architecture decision, or
+a change to a contract. The practical test: if in six months someone is going to
+ask "why is it done this way" and the answer isn't in the code, an ADR is needed.

package/skills/write-adr/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: write-adr
+description: "Use when you need to record an architecture decision, open an ADR, amend or replace an existing one, or when a change is hard to revert and someone will ask in six months why it's done this way (structural refactor, major dependency, API contract, data partitioning, module boundaries)."
+tags: ["adr", "architecture", "documentation"]
+profiles: [core, ui, full]
+---
+
+# Write an ADR
+
+An ADR records a decision **already made**, with its rationale and the alternatives that were discarded. It is read before touching the area it covers. It is not a plan or a design: those live in specs and plans and do not replace it.
+
+## When one is worth it
+
+All three at once; if one is missing, there is no ADR:
+
+1. **Hard to reverse**: changing your mind later is costly.
+2. **Surprising without context**: reading the code, someone will ask "why on earth is it like this".
+3. **Real trade-off**: there were genuine alternatives and one was chosen for concrete reasons.
+
+Explicit "no"s count as much as "yes"es ("issues are NOT indexed").
+
+## Procedure
+
+1. **Read `docs/adr/README.md`** if it exists. Its rules on format, numbering, and the index override this skill. If it doesn't exist, create it from the [`README-TEMPLATE.md`](README-TEMPLATE.md) template.
+2. **Number**: the highest one in `docs/adr/` plus one. Never reuse or backfill gaps.
+3. **File**: `docs/adr/ADR-NNN-title-in-kebab-case.md`, three digits, a title with no accents or emoji.
+4. **Body** from [`ADR-TEMPLATE.md`](ADR-TEMPLATE.md). Each decision is numbered `D1`, `D2`... so it can be cited ("ADR-036 D1") and superseded one at a time.
+5. **Index**: add the row to the README, in the section of the area it touches, with a sentence saying what it decides and when to read it ("read before touching X").
+6. **Cross-references**: if it supersedes or amends another ADR, touch that one too (see below).
+7. **Confirm with the user** the title and the decisions before writing the file. The decision is theirs; you write it up.
+
+## Changing your mind
+
+An accepted ADR **is not rewritten**. Two paths:
+
+- **Amendment** (same decision, new nuance): a blockquote `> **Amendment YYYY-MM-DD.** ...` right below the affected D, stating what changes and the trade-off accepted. Reflected in the index row.
+- **Replacement** (different decision): a new ADR. The old one becomes `Status: Superseded by ADR-NNN` with a link and moves to the "Retired or superseded" section of the index. A single D can be superseded on its own ("Its D3 is superseded by ADR-041").
+
+This way the history explains why it changed.
+
+## Done criteria
+
+- The file exists, the index has the row, and the affected ADRs point to the new one.
+- Each D states what is done **and** what was rejected by doing it.
+- "Discarded alternatives" has at least one with the reason for rejection; without it, someone will propose it again.
+- Every figure, file, or PR cited is real: it has been checked against the repo.
+
+## Common mistakes
+
+| Mistake | Fix |
+|---|---|
+| An ADR that describes a plan ("we'll do X in three phases") | Only what was decided. The plan goes in `docs/superpowers/plans/` |
+| Editing the old ADR to say the new thing | A dated amendment, or a new ADR that supersedes it |
+| Context that tells the story of the session | Context that explains the problem and why the previous state didn't work |
+| Consequences that are only positive | Note the accepted cost; that's what keeps the discussion from reopening |
+| Deciding on your own a D the user hasn't stated | Ask. Recording is yours; deciding is theirs |

package/skills/write-adr/evals/cases.yaml

@@ -0,0 +1,32 @@
+skill: write-adr
+
+should_trigger:
+  - prompt: "Necesito registrar esta decision de arquitectura en un ADR."
+    why: "Disparador directo de write-adr."
+  - prompt: "Abre un ADR para este cambio dificil de revertir."
+    why: "Disparador directo de write-adr."
+  - prompt: "Hay que enmendar el ADR-012 con este nuevo matiz."
+    why: "Disparador directo de write-adr."
+  - prompt: "Record this architecture decision as an ADR before we proceed."
+    why: "Disparador directo de write-adr."
+  - prompt: "Este cambio de contrato de API necesita un ADR."
+    why: "Disparador directo de write-adr."
+
+should_not_trigger:
+  - prompt: "Escribe el plan de implementacion, no una decision ya tomada."
+    route_to: "none"
+    why: "Fuera del alcance de write-adr."
+  - prompt: "Documenta la terminologia del dominio, no una decision de arquitectura."
+    route_to: "domain-modeling"
+    why: "Documentar la terminologia del dominio es el trabajo de domain-modeling, no de write-adr."
+  - prompt: "Implementa el codigo de esta funcionalidad."
+    route_to: "implement"
+    why: "Implementar el codigo es el trabajo de implement, no de write-adr."
+  - prompt: "Revisa los cambios de esta rama."
+    route_to: "revision-de-cambios"
+    why: "Revisar los cambios de una rama es el trabajo de revision-de-cambios, no de write-adr."
+
+capability:
+  - scenario: "El usuario necesita registrar una decision de arquitectura difícil de revertir."
+    must_include:
+      - "ADR"

package/skills/writing-for-agents/SKILL-MECHANICS.md

@@ -0,0 +1,22 @@
+# Mecánica de skills
+
+La rama específica de skills de [`writing-for-agents`](SKILL.md): qué cambia cuando el documento es una skill (frontmatter, la elección de invocación y las skills router). Todo lo demás sobre escribirla es la referencia universal en `SKILL.md`.
+
+## Invocación
+
+Dos opciones, que intercambian las dos cargas:
+
+- Una skill **invocada por el modelo** conserva una `description`, así que el agente puede dispararla de forma autónoma, y otras skills pueden alcanzarla. Aun así puedes escribir su nombre: la invocación por modelo siempre *incluye* el alcance del usuario; una `description` solo añade descubrimiento por el agente, nunca quita el del humano. La `description` es el puntero de contexto de primer nivel de la skill, forzado a estar siempre cargado: carga de contexto permanente a cambio de descubribilidad. Una skill invocada por el modelo cuyo contenido es todo referencia es también un hogar para referencia compartida: otra skill puede invocarla, así que la referencia que necesitan varias skills vive en un solo sitio. Mecánica: omite `disable-model-invocation`, y escribe una `description` orientada al modelo que lleve las ramas de disparo (las reglas de redacción de punteros de `SKILL.md` aplican en su totalidad).
+- Una skill **invocada por el usuario** retira la `description` del alcance del agente: solo el humano que escribe su nombre puede invocarla, y ninguna otra skill puede. Cero carga de contexto, pero gasta carga cognitiva: tú eres el índice que debe recordar que existe. Mecánica: pon `disable-model-invocation: true`; la `description` se vuelve orientada al humano: un resumen de una línea, sin las ramas de disparo.
+
+Elige invocación por modelo solo cuando el agente deba alcanzar la skill por su cuenta, o cuando otra skill deba hacerlo. Si solo se dispara a mano, hazla invocada por usuario y no pagues carga de contexto.
+
+La referencia compartida que necesitan dos skills invocadas por usuario no puede vivir en ninguna de las dos: sin `description`, ninguna puede disparar a la otra. Empújala a un fichero plano fuera del sistema de skills: referencia externa a la que cualquier skill puede apuntar.
+
+## Dividir por invocación
+
+El corte de invocación de la división (el corte de secuencia vive en `SKILL.md`): separa una skill invocada por el modelo cuando tienes una palabra clave distinta que debería dispararla por sí sola (una palabra de disparo que realmente usas en tus prompts), o cuando otra skill debe alcanzarla. Pagas carga de contexto por la nueva `description` siempre cargada, así que ese alcance independiente tiene que merecer la pena.
+
+## Skills router
+
+Cuando las skills invocadas por usuario se multiplican más allá de lo que puedes recordar, esa carga cognitiva acumulada se cura con una **skill router**: una skill invocada por usuario que nombra a las demás y cuándo recurrir a cada una, para que el humano tenga que recordar una sola skill en lugar de muchas. Solo puede insinuar, nunca dispararlas: las skills invocadas por usuario no tienen `description`, así que nada excepto el humano puede alcanzarlas.

package/skills/writing-for-agents/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: writing-for-agents
+description: "Write documents that an agent will consume. Use when creating or editing skills, or when modifying AGENTS.md or CLAUDE.md."
+tags: ["writing", "documentation", "agents"]
+profiles: [core, ui, full]
+---
+
+Referencia para escribir cualquier documento que consume un agente: una skill, un `AGENTS.md` / `CLAUDE.md`, un documento al que se llega por un puntero. El empaquetado cambia; la escritura no: las mismas palancas hacen predecible cada uno, porque el agente sigue el mismo *proceso* en cada ejecución en lugar de producir el mismo resultado.
+
+Cuando el documento que escribes es una skill, lee [`SKILL-MECHANICS.md`](SKILL-MECHANICS.md) para frontmatter, elección de invocación y skills router.
+
+## Punteros de contexto
+
+Un **puntero de contexto** es una referencia que vive en el contexto del agente, que nombra cierto material fuera de contexto y codifica la condición para llegar a él. La `description` de una skill es uno; una línea en `AGENTS.md` que nombra un documento es el mismo objeto. La *redacción* del puntero, no su destino, decide cuándo el agente llega al material, y con qué fiabilidad. Un objetivo imprescindible detrás de un puntero mal redactado es un bug de varianza: afila primero la redacción, y solo pon el material en línea si afilarla falla.
+
+Un puntero hace dos trabajos: decir qué es el material, y listar las **ramas** que deberían disparar llegar a él (una rama es un caso distinto que cubre el documento, de modo que ejecuciones distintas toman caminos distintos por él). Cada palabra de un puntero siempre cargado cuesta en cada turno, así que merece una poda aún más dura que el cuerpo:
+
+- **Antepón la palabra clave**: el puntero es donde hace su trabajo de disparo.
+- **Un disparador por rama.** Sinónimos que renombran una sola rama son una rama escrita dos veces; colápsalos y conserva solo las ramas genuinamente distintas.
+- **Recorta la identidad que el cuerpo ya lleva.**
+
+## Las dos cargas
+
+Cada documento y puntero que añades gasta uno de dos presupuestos:
+
+- La **carga de contexto** es el coste del material siempre cargado en la ventana del agente: una línea de `AGENTS.md`, la `description` de una skill, cualquier cosa que está en contexto cada turno, gastando tokens y atención se dispare o no.
+- La **carga cognitiva** es el coste sobre el humano: qué documentos existen y cuándo recurrir a cada uno. El humano es el índice. No es un coste a minimizar: es el precio de la autonomía humana; gástalo donde el juicio humano importa, quítalo donde no.
+
+El material al que solo se llega por un puntero escapa de la carga de contexto al precio de la línea del propio puntero; el material sin ningún puntero recae por completo en la carga cognitiva.
+
+## Jerarquía de la información
+
+Un documento se construye con dos tipos de contenido: **pasos** (las acciones ordenadas que ejecuta el agente) y **referencia** (definiciones, reglas, hechos consultados bajo demanda). Los dos se mezclan libremente: todo pasos (una receta), toda referencia (las reglas de una revisión, esta skill), o ambos. La decisión central es dónde se sitúa cada pieza en la **jerarquía de la información**, una escalera ordenada por cuán inmediatamente necesita el agente el material:
+
+1. **Paso en el fichero** es el nivel primario: lo que hace el agente, en orden.
+2. **Referencia en el fichero** se consulta bajo demanda. A menudo un conjunto plano legítimo (cada regla de una revisión en el mismo peldaño), lo cual es un arreglo válido, no un olor.
+3. **Referencia divulgada** se empuja a un fichero aparte, al que se llega por un puntero de contexto, cargado solo cuando el puntero se dispara. Va desde un fichero hermano en la misma carpeta hasta referencia totalmente externa que vive en cualquier sitio y a la que cualquier documento puede apuntar.
+
+Empujar demasiado poco hincha la parte de arriba; empujar demasiado esconde material que el agente realmente necesita. Esa tensión es toda la decisión.
+
+**Divulgación progresiva** es el movimiento escalera abajo (fuera del fichero principal y detrás de un puntero) para que la cima siga siendo legible. No es principalmente una optimización de tokens: es cómo se protege la jerarquía. Ramificar es la prueba de divulgación más limpia: pon en línea lo que toda rama necesita, y empuja detrás de un puntero lo que solo alcanzan algunas ramas. Cuando un documento tiene pasos, la referencia en el fichero que debería divulgarse los entierra y convierte el atenderlos en una moneda al aire: una palanca de varianza, no solo de legibilidad.
+
+**Colocación conjunta** es la compañera dentro del fichero: donde la escalera decide *cuán abajo* se sitúa una pieza, la colocación conjunta decide *qué va junto a ella* una vez allí. Mantén la definición, las reglas y las salvedades de un concepto bajo un mismo encabezado en lugar de dispersas, para que leer una parte traiga consigo a sus vecinas. La prueba: el documento debería leerse como documentación escrita para el agente. El material agrupado se lee así; el disperso no. (Distinto de la duplicación: esa repite un mismo significado en dos sitios; la dispersión fragmenta un significado en muchos.)
+
+**Desbordamiento** es el modo de fallo aquí: un documento sencillamente demasiado largo, incluso cuando cada línea está viva y es única. La atención se diluye a través del exceso, y cada línea de más es una más que mantener relevante. La cura es la escalera: divulga la referencia detrás de punteros, y divide por rama o secuencia para que cada camino cargue solo con lo que necesita.
+
+## Pasos y criterios de finalización
+
+Cada paso termina en un **criterio de finalización**, la condición que le dice al agente que el trabajo está hecho. Dos propiedades lo convierten en palanca:
+
+- **Claridad**: ¿puede el agente distinguir hecho de no-hecho? Un límite vago ("comprensión alcanzada") invita a la **finalización prematura**: terminar el paso antes de que esté genuinamente hecho, la atención resbalando hacia *estar terminado*. Los pasos posteriores visibles todavía por delante (los **pasos post-finalización**) aportan el tirón; la claridad del criterio es la resistencia. Defiéndete en orden: **afila primero el límite** (local y barato); solo si es irreduciblemente difuso *y* observas la prisa, oculta los pasos posteriores partiendo la secuencia. Ocultar solo funciona a través de una frontera de contexto real (un traspaso o el despacho a un subagente; una llamada en línea deja los pasos posteriores en contexto y no despeja nada).
+- **Exigencia**: cuánto requiere. "Cada modelo modificado tenido en cuenta" fuerza un trabajo minucioso donde "produce una lista de cambios" no lo hace. La exigencia impulsa el **trabajo de fondo** (la indagación que hace el agente dentro del trabajo, latente en la redacción en lugar de escrita como paso propio), y no está atada a los pasos: "cada regla aplicada" ata un cuerpo de referencia plana igual que "cada paso hecho" ata una secuencia, que es cómo un documento todo-referencia igualmente lleva una barra de exhaustividad.
+
+Los criterios más fuertes son a la vez comprobables y exhaustivos.
+
+## Cuándo dividir
+
+Dividir un documento en dos gasta una de las dos cargas, así que divide solo cuando el corte lo merezca:
+
+- **Por secuencia**: divide una tirada de pasos donde los pasos post-finalización tientan al agente a apresurar el que tiene delante. Mantenerlos fuera de la vista impulsa más trabajo de fondo en la tarea actual. Cuidado con lo contrario: fusionar secuencias expone los pasos posteriores de cada paso a lo que sigue, invitando a la finalización prematura.
+- **Por invocación**, específico de skills: ver [`SKILL-MECHANICS.md`](SKILL-MECHANICS.md).
+
+## Palabras clave
+
+Una **palabra clave** es un concepto compacto que ya vive en el preentrenamiento del modelo, con el que el agente piensa mientras ejecuta el documento (*lección*, *niebla de guerra*, *balas trazadoras*). Repetida como token, nunca como frase, acumula una definición distribuida y ancla toda una región de comportamiento en el mínimo de tokens, al reclutar prioris que el modelo ya tiene. Acuñar una propia funciona si la defines con claridad, pero una palabra inventada no recluta ningún prior: pagas en tokens de definición lo que una palabra preentrenada da gratis; recurre primero a una palabra ya existente.
+
+Ancla dos veces. En el cuerpo, *ejecución*: el agente recurre al mismo comportamiento cada vez que aparece la palabra, y dentro de la referencia plana enfoca la atención en una clase de cosa a buscar. En un puntero, *invocación*: cuando la misma palabra vive en tus prompts, tus documentos y tu código, el agente enlaza ese lenguaje compartido con el material y lo alcanza con más fiabilidad.
+
+Busca oportunidades para refactorizar con palabras clave. Una tríada deletreada en tres sitios, un puntero que gasta una frase en señalar una idea. Cada una es un pasaje que pide colapsar en un solo token:
+
+- "rápido, determinista, con poco overhead" → *ajustado* (un bucle *ajustado*).
+- "un bucle en el que confías" → *en verde*, convirtiendo una puerta difusa en un estado observable binario (el bucle se pone *en verde* con el bug, o no).
+
+Ganas dos veces: menos tokens, y un gancho más afilado para que el agente cuelgue su razonamiento. Asume que todo documento lleva reformulaciones que las palabras clave jubilan. Ve a buscarlas.
+
+La **negación** es el modo de fallo junto a esta palanca: dirigir por prohibición arrastra el comportamiento prohibido al contexto y lo hace *más* disponible, no menos. *No pienses en un elefante*, y el elefante es todo lo que hay; la negación es un modificador débil que el concepto fuertemente activado desborda, así que la prohibición casi se lee como una instrucción de hacer la cosa. Enuncia lo **positivo**: declara el comportamiento objetivo ("escribe comentarios de una línea") para que el prohibido nunca se pronuncie. Una prohibición se gana su lugar solo como barrera dura que no puedes expresar en positivo; aun así, empareja con el objetivo positivo para que la atención caiga en qué hacer.
+
+## Poda
+
+- Mantén cada significado en una **única fuente de verdad**: un lugar autoritativo, para que cambiar el comportamiento sea una edición en un solo sitio. La **duplicación** (el mismo significado en más de un lugar) cuesta mantenimiento y tokens, e infla la prominencia de un significado en la escalera por encima de su rango real. (El inverso accidental de una palabra clave, que repite un token a propósito, nunca el significado.)
+- El **entorno** también es una fuente de verdad (scripts de `package.json`, ficheros de configuración, la estructura de directorios, la salida de `--help`), y un documento que lo repite es una **caché**: una copia de una consulta, que se gana su carga solo cuando la consulta es cara. Cachea lo que el agente no puede encontrar mirando: la convención no escrita, la razón detrás de una elección, la trampa que ninguna configuración confiesa. Deja las consultas de un fichero y un comando a el entorno, donde no pueden quedarse obsoletas.
+- Comprueba cada línea por **relevancia**: ¿sigue teniendo que ver con lo que hace el documento? Una línea pierde relevancia por no incidir nunca en la tarea (mera exposición, o una rama que debería divulgarse) o por quedar obsoleta a medida que cambia el comportamiento o el mundo que describe. Los documentos más cortos son más fáciles de mantener relevantes. Sin una disciplina de poda el destino por defecto es el **sedimento**: capas obsoletas que se asientan porque añadir se siente seguro y quitar se siente arriesgado, hasta que hay que perforar hacia abajo por ellas para encontrar lo que sigue vivo.
+- Caza los **no-ops** frase por frase: una instrucción que el modelo ya obedece por defecto paga carga para no decir nada. La prueba (¿cambia el comportamiento frente al defecto?) es relativa al modelo, no al lector: dos personas en desacuerdo sobre si algo es un no-op están en desacuerdo sobre el defecto, y se resuelve ejecutando el documento, no debatiendo. Cuando una frase falla la prueba, borra la frase entera en lugar de recortarle palabras. La prueba también califica a las palabras clave: una palabra demasiado débil para superar el defecto (*sé minucioso* cuando el agente ya es medio minucioso) es un no-op, y el arreglo es una palabra más fuerte (*implacable*), no una técnica distinta.

package/skills/writing-for-agents/evals/cases.yaml

@@ -0,0 +1,32 @@
+skill: writing-for-agents
+
+should_trigger:
+  - prompt: "Estoy creando una skill nueva, ayudame a escribirla para que la consuma un agente."
+    why: "Disparador directo de writing-for-agents."
+  - prompt: "Necesito editar este AGENTS.md para que un agente lo entienda bien."
+    why: "Disparador directo de writing-for-agents."
+  - prompt: "Revisa este CLAUDE.md pensando en que lo lee un agente, no una persona."
+    why: "Disparador directo de writing-for-agents."
+  - prompt: "Write this skill document so an agent can consume it effectively."
+    why: "Disparador directo de writing-for-agents."
+  - prompt: "Ajusta este documento para que un agente lo siga sin ambiguedad."
+    why: "Disparador directo de writing-for-agents."
+
+should_not_trigger:
+  - prompt: "Escribe un articulo de blog para lectores humanos."
+    route_to: "none"
+    why: "Fuera del alcance de writing-for-agents."
+  - prompt: "Redacta un email de marketing."
+    route_to: "none"
+    why: "Fuera del alcance de writing-for-agents."
+  - prompt: "Documenta el modelo de dominio del negocio."
+    route_to: "domain-modeling"
+    why: "Documentar el modelo de dominio del negocio es el trabajo de domain-modeling, no de writing-for-agents."
+  - prompt: "Genera tickets a partir de esta spec."
+    route_to: "to-tickets"
+    why: "Generar tickets a partir de una spec es el trabajo de to-tickets, no de writing-for-agents."
+
+capability:
+  - scenario: "El usuario crea o edita un documento que va a consumir un agente."
+    must_include:
+      - "agente"

package/skills/youtube-api/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: youtube-api
+description: "Use when wiring code to a real YouTube channel: user OAuth 2.0, resumable videos.insert uploads, editing metadata after publish, pulling views/watch time/retention/traffic from the Analytics API v2 into a dated docs/wiki/youtube/ feedback log. NOT what to publish or how to title and thumbnail it (that is youtube-strategy / youtube-packaging)."
+tags: [youtube, youtube-data-api, youtube-analytics-api, oauth2, resumable-upload, video-metadata, audience-retention, channel-feedback-log]
+recommends: [social-publisher, api-connector-builder, automation-flows, knowledge-ops]
+origin: risco
+---
+
+# YouTube API — Transport + Ingestion for a Real Channel
+
+*You own the wire: authenticate to a YouTube channel, upload and edit videos, pull the numbers, and write those numbers into the wiki as a durable feedback log. You do not decide what to make or how to title it — that is the strategy/packaging family. Deliver clean transport and a queryable log; let the siblings interpret.*
+
+YouTube has **two separate APIs** and you will touch both:
+
+- **Data API v3** — `https://www.googleapis.com/youtube/v3` — the *write* side: `videos.insert` (upload), `videos.update` (edit metadata), `thumbnails.set`. Default quota: a shared 10,000 units/day pool *plus* separate per-day caps of ~100 uploads and ~100 `search.list` calls (see §7).
+- **Analytics API v2** — `https://youtubeanalytics.googleapis.com/v2/reports` — the *read* side: views, watch time, retention, traffic sources. Separate scopes, separate quota.
+
+Auth is **user OAuth 2.0, not a service account.** A human owns the channel; you act on their behalf with a refresh token. A service account cannot own a YouTube channel — if you reach for one, stop. (Service-account Google auth for Gmail/Drive/Sheets is `google-workspace`, a different model.)
+
+Route elsewhere when the job is not transport:
+
+| You actually want | Go to |
+| --- | --- |
+| What videos to make / niche / cadence / growth plan | `../youtube-strategy/SKILL.md` |
+| Video ideas, hooks, a topic backlog | `../youtube-ideation/SKILL.md` |
+| Title + thumbnail packaging, CTR copy, A/B framing | `../youtube-packaging/SKILL.md` |
+| The thumbnail image itself | `../youtube-thumbnails/SKILL.md` |
+| Render/produce the actual video file in code | `../remotion-video/SKILL.md` |
+| Post one asset across many networks at once | `../social-publisher/SKILL.md` |
+| Wrap an arbitrary REST provider with OAuth + retries | `../api-connector-builder/SKILL.md` |
+| Chain upload → Notion row → Slack across tools | `../automation-flows/SKILL.md` |
+| Service-account auth to Gmail/Drive/Sheets | `../google-workspace/SKILL.md` |
+| Generic wiki structure and conventions | `../knowledge-ops/SKILL.md` |
+
+## 1. One-time setup (do this before any code)
+
+A checklist, because each missing step produces a distinct, confusing error later:
+
+1. Create (or pick) a **GCP project**.
+2. **Enable both APIs** in that project: "YouTube Data API v3" *and* "YouTube Analytics API". Enabling one is the most common cause of a `403 ... has not been used in project` on the other.
+3. Configure the **OAuth consent screen** and **publish it to "In production."** Why: an app left in "Testing" status issues refresh tokens that **expire in 7 days** — your cron silently dies the following week. This is the single most common YouTube-ingestion breakage.
+4. Create an **OAuth client**: *Desktop app* for a personal/local script, *Web application* (with an exact redirect URI) for a hosted app.
+5. Request **least-privilege scopes** — not the full management scope.
+
+Scope table — request only what the job needs:
+
+| Scope | Grants | Use for |
+| --- | --- | --- |
+| `https://www.googleapis.com/auth/youtube.upload` | Upload videos | `videos.insert` |
+| `https://www.googleapis.com/auth/youtube.force-ssl` | Manage/edit/delete | `videos.update`, `thumbnails.set` |
+| `https://www.googleapis.com/auth/yt-analytics.readonly` | Read performance | Analytics reports |
+| `https://www.googleapis.com/auth/yt-analytics-monetary.readonly` | Read revenue metrics | only if you pull `estimatedRevenue` etc. |
+
+Bad → Good on scopes:
+
+```text
+Bad:  scopes = ["https://www.googleapis.com/auth/youtube"]   # full account control
+Good: scopes = ["https://www.googleapis.com/auth/youtube.upload",
+                "https://www.googleapis.com/auth/youtube.force-ssl",
+                "https://www.googleapis.com/auth/yt-analytics.readonly"]
+```
+
+Full GCP + consent-screen walkthrough, Desktop-vs-Web choice, and `unauthorized_client` / `access_denied` / redirect-URI troubleshooting live in `references/oauth-setup.md`.
+
+## 2. Get an authed client and keep the token alive
+
+Build both service clients from **one** set of OAuth credentials.
+
+```python
+# python: google-api-python-client + google-auth-oauthlib
+from google_auth_oauthlib.flow import InstalledAppFlow
+from google.auth.transport.requests import Request
+from googleapiclient.discovery import build
+import json, os
+from google.oauth2.credentials import Credentials
+
+SCOPES = ["https://www.googleapis.com/auth/youtube.upload",
+          "https://www.googleapis.com/auth/youtube.force-ssl",
+          "https://www.googleapis.com/auth/yt-analytics.readonly"]
+TOKEN = "token.json"   # gitignored — holds the refresh_token
+
+def creds():
+    c = Credentials.from_authorized_user_file(TOKEN, SCOPES) if os.path.exists(TOKEN) else None
+    if not c or not c.valid:
+        if c and c.expired and c.refresh_token:
+            c.refresh(Request())               # silent renewal — needs "In production" app
+        else:
+            c = InstalledAppFlow.from_client_secrets_file(
+                "client_secret.json", SCOPES).run_local_server(port=0)
+        with open(TOKEN, "w") as f:
+            f.write(c.to_json())
+    return c
+
+c = creds()
+data = build("youtube", "v3", credentials=c)
+yta  = build("youtubeAnalytics", "v2", credentials=c)
+```
+
+```javascript
+// node: googleapis + google-auth-library
+import { google } from "googleapis";
+import fs from "node:fs";
+
+const oauth2 = new google.auth.OAuth2(CLIENT_ID, CLIENT_SECRET, REDIRECT_URI);
+oauth2.setCredentials(JSON.parse(fs.readFileSync("token.json", "utf8"))); // { refresh_token, ... }
+oauth2.on("tokens", (t) => {                 // persist the refreshed token
+  if (t.refresh_token) fs.writeFileSync("token.json", JSON.stringify(t));
+});
+const data = google.youtube({ version: "v3", auth: oauth2 });
+const yta  = google.youtubeAnalytics({ version: "v2", auth: oauth2 });
+```
+
+Rule: persist the **refresh token**, never a bare `access_token`. Access tokens expire in ~1 hour; the credential object refreshes itself. A hardcoded `access_token=...` literal is a guaranteed 401 within the hour — and is exactly what `verify.sh` flags.
+
+## 3. Upload a video (resumable, always)
+
+Decision: any file over a few MB → use the **resumable** protocol. A plain multipart POST drops the whole upload on one network hiccup; resumable survives it.
+
+The protocol is two steps:
+
+1. **Init the session** — POST to the upload endpoint with `uploadType=resumable` and the metadata body. The response `Location` header is your session URL.
+2. **PUT the bytes** to that session URL — one shot or in chunks. On a dropped connection, query with `Content-Range: bytes */*`; the server returns the byte offset already received, and you resume from there.
+
+The client libraries do this for you via a media-upload helper:
+
+```python
+from googleapiclient.http import MediaFileUpload
+
+body = {
+  "snippet": {"title": "Ep. 14", "description": "...", "tags": ["x", "y"], "categoryId": "27"},
+  "status":  {"privacyStatus": "private", "publishAt": "2026-06-10T15:00:00Z",
+              "selfDeclaredMadeForKids": False},
+}
+media = MediaFileUpload("ep14.mp4", chunksize=8 * 1024 * 1024, resumable=True)
+req = data.videos().insert(part="snippet,status", body=body, media_body=media)
+resp = None
+while resp is None:
+    status, resp = req.next_chunk()          # resumes automatically on a transient drop
+video_id = resp["id"]
+data.thumbnails().set(videoId=video_id, media_body=MediaFileUpload("ep14.jpg")).execute()
+```
+
+Throttle the upload **count**, not the unit spend: `videos.insert` has its own cap of ~100 uploads/day, so `uploadLimitExceeded` (429) hits while the 10k unit pool still looks untouched. Space automated uploads out and back off on 429 — figures and citation in §7.
+
+## 4. Edit metadata after publish
+
+`videos.update` does **read-modify-write** semantics on whole parts. The trap: any field you omit inside a part you send gets **cleared**.
+
+```python
+# Bad: wipes description and tags because they aren't in the body
+data.videos().update(part="snippet",
+    body={"id": vid, "snippet": {"title": "New title", "categoryId": "27"}}).execute()
+
+# Good: fetch the current snippet, change one field, send it back whole
+cur = data.videos().list(part="snippet", id=vid).execute()["items"][0]["snippet"]
+cur["title"] = "New title"
+data.videos().update(part="snippet", body={"id": vid, "snippet": cur}).execute()
+```
+
+`categoryId` is required when you send a `snippet` part — another reason to read-modify-write. An update costs **~50 units**.
+
+## 5. Pull performance (Analytics API v2)
+
+Every report is `GET /v2/reports?ids=channel==MINE&startDate=&endDate=&metrics=...&dimensions=...&filters=...`. Four recipes cover the loop:
+
+```python
+# (a) Channel KPIs over a date range
+yta.reports().query(ids="channel==MINE", startDate="2026-05-01", endDate="2026-05-31",
+  metrics="views,estimatedMinutesWatched,averageViewDuration,averageViewPercentage"
+).execute()
+
+# (b) Per-video KPIs
+yta.reports().query(ids="channel==MINE", startDate="2026-05-01", endDate="2026-05-31",
+  metrics="views,estimatedMinutesWatched,averageViewPercentage",
+  filters="video==VIDEO_ID").execute()
+
+# (c) Audience-retention curve for one video
+yta.reports().query(ids="channel==MINE", startDate="2026-05-01", endDate="2026-05-31",
+  metrics="audienceWatchRatio,relativeRetentionPerformance",
+  dimensions="elapsedVideoTimeRatio", filters="video==VIDEO_ID").execute()
+
+# (d) Traffic sources
+yta.reports().query(ids="channel==MINE", startDate="2026-05-01", endDate="2026-05-31",
+  metrics="views,estimatedMinutesWatched",
+  dimensions="insightTrafficSourceType").execute()
+```
+
+Notes that save an afternoon:
+
+- `elapsedVideoTimeRatio` runs 0.0–1.0 (playback position); `audienceWatchRatio` is the absolute retention at that point. Plot one against the other to find the drop-off.
+- `insightTrafficSourceType` values include `YT_SEARCH`, `SUGGESTED`, `BROWSE`, `EXT_URL`, `NOTIFICATION`, `PLAYLIST`, `END_SCREEN`, `NO_LINK_EMBEDDED`.
+- **Impressions / CTR** (`impressions`, `impressionClickThroughRate`) are **content-owner-report metrics**, not reliably available on a plain channel query. If the API returns nothing for them, fall back to the value Studio shows — do not block the pull.
+
+Full metric+dimension catalog and copy-paste bodies for geography, device, and subscribed-status reports are in `references/analytics-queries.md`.
+
+## 6. Ingest into the wiki — the actual deliverable
+
+A pull that prints to stdout and vanishes is wasted. **Every pull appends a dated entry under `docs/wiki/youtube/`** so the channel's numbers become queryable history that the strategy/packaging siblings can read.
+
+```text
+docs/wiki/youtube/
+  index.md                  # rolling pointer to latest snapshot + open questions
+  channel-2026-05-31.md     # dated channel snapshot (one per pull)
+  videos/<VIDEO_ID>.md      # per-video running log, newest entry on top
+```
+
+Per-pull entry template (OKF v0.1: non-empty `type` + the domain keys siblings parse):
+
+```markdown
+---
+type: youtube-metrics
+title: Channel snapshot 2026-05-31
+description: Channel KPIs, traffic and retention for 2026-05-01..2026-05-31.
+tags: [youtube, channel-snapshot]
+timestamp: 2026-05-31T00:00:00Z
+date: 2026-05-31
+range: 2026-05-01..2026-05-31
+channel: MINE
+source: youtube-analytics-api-v2
+---
+## KPIs
+views: 41,233 | watch_min: 88,140 | avg_view_pct: 38.2% | avg_view_dur: 0:04:11
+
+## Traffic (top 3)
+BROWSE 44% · SUGGESTED 31% · YT_SEARCH 12%
+
+## Retention
+Sharp drop 0.00→0.06 (intro), recovers, second dip ~0.55.
+
+## What changed since last pull
+avg_view_pct +2.1pts; SUGGESTED share up 6pts after the Ep.13 packaging change.
+```
+
+Rule: **append, never overwrite.** The feedback log *is* the value — overwriting yesterday's snapshot destroys the trend the siblings need. `docs/wiki/` is an OKF v0.1 bundle: keep the domain keys (`date`, `range`, `channel`, `source`) the siblings parse, add `type`/`timestamp` alongside them, use standard markdown links (never `[[wikilinks]]`), and leave the reserved `index.md` frontmatter-free. Exact file tree, naming, per-video log shape, and how siblings read the log: `references/wiki-schema.md`.
+
+## 7. Quota & failure math
+
+| Call | Cost / allocation |
+| --- | --- |
+| `videos.insert` (upload) | own daily cap: **~100 uploads/day**, not 10k-pool units |
+| `search.list` | own daily cap: ~100 calls/day |
+| write: `videos.update`, `thumbnails.set` | ~50 units (from the 10k pool) |
+| `*.list` read | 1–5 units (from the 10k pool) |
+| Analytics `reports.query` | (separate Analytics quota) |
+
+Per the official docs (Last updated 2026-06-01 UTC, `https://developers.google.com/youtube/v3/getting-started`; per-method costs at `https://developers.google.com/youtube/v3/determine_quota_cost`), a project's default allocation is *"100 search.list calls, 100 videos.insert calls, and 10,000 units per day combined for all other endpoints."* All quotas reset at midnight Pacific. This is a change from the older single-pool model where `videos.insert` cost ~1,600 units — confirm the live figure on the quota-cost page before relying on it, since Google notes the allocation "is subject to change."
+
+On `403 quotaExceeded` / `rateLimitExceeded` or `429`: **exponential backoff with jitter**, then stop for the day on a hard quota cap — retrying a daily-quota 403 in a tight loop just burns the next day too.
+
+Error → cause map:
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| Refresh token dies after ~7 days | App still in "Testing" | Publish consent screen to "In production" |
+| `unauthorized_client` | Consent/client misconfig or wrong client type | Re-check OAuth client + authorized scopes |
+| `403 insufficient permissions` | Missing scope | Add the right scope, re-consent |
+| `uploadLimitExceeded` (429) | Hit the ~100 `videos.insert`/day cap (separate from the 10k unit pool) | Throttle upload count, back off |
+| Empty `impressions`/CTR | Not a content-owner channel query | Read it from Studio |
+| `403 ... API has not been used` | Other API not enabled | Enable both Data v3 and Analytics v2 |
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+| --- | --- | --- |
+| Commit `client_secret.json` / `token.json` with `refresh_token` | Leaks full channel control to anyone with repo read | Gitignore both; load from env/secret store |
+| Request full `auth/youtube` scope | Grants total account control; fails review | Least set: `youtube.upload` + `youtube.force-ssl` + `yt-analytics.readonly` |
+| Hardcode an `access_token` | Dead in ~1 hour | Persist the refresh token; use a refreshable credential |
+| `videos.update` with a partial part | Omitted fields get wiped | Read-modify-write the whole part |
+| Plain multipart upload for a big file | One drop kills the whole upload | Resumable protocol with chunked PUT |
+| Treat the 10k unit pool as the upload budget | Uploads use a separate ~100/day call cap, so `uploadLimitExceeded` 429 hits with the pool untouched | Throttle upload count against the ~100/day cap |
+| Overwrite yesterday's wiki snapshot | Destroys the trend the siblings read | Append a new dated entry every pull |
+| Leave the app in "Testing" | Token silently dies in 7 days | Publish to "In production" |

package/skills/youtube-api/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — youtube-api
+
+These are routing and coverage checks for the skill harness, not live API tests. `should_trigger` asserts the skill fires on YouTube transport + ingestion prompts (upload, metadata edit, Analytics pulls, quota/token debugging, "write stats to the wiki"), including the non-obvious 7-day-refresh-token and `uploadLimitExceeded` cases and a Spanish phrasing. `should_not_trigger` asserts an intent-level prompt routes to the named real sibling instead (youtube-strategy / youtube-packaging / youtube-ideation for what-to-make-and-how-to-package, social-publisher for multi-network, remotion-video for rendering, api-connector-builder for generic OAuth wrapping). The single `capability` case is a rubric scored against a generated answer for the weekly-cron scenario. No live YouTube or Google API calls are made — run them through whatever harness loads `cases.yaml`.

package/skills/youtube-api/evals/cases.yaml

@@ -0,0 +1,50 @@
+skill: youtube-api
+
+should_trigger:
+  - prompt: "Upload a video to my YouTube channel via the API and set its title and tags."
+    why: "Core write path — videos.insert + metadata. The transport job this skill owns."
+  - prompt: "My YouTube refresh token stops working after about a week — why?"
+    why: "Non-obvious: app left in Testing publishing status issues 7-day refresh tokens; this skill maps that symptom to the In-production fix."
+  - prompt: "Pull the averageViewPercentage and the audience-retention curve for video abc123."
+    why: "Analytics read path — elapsedVideoTimeRatio + audienceWatchRatio. Squarely this skill."
+  - prompt: "subir vídeos a YouTube por API y guardar las estadísticas del canal."
+    why: "Spanish; upload + ingest stats — the full transport + ingestion loop this skill owns."
+  - prompt: "videos.insert returns 403 quotaExceeded — how many uploads does the 10k unit quota allow?"
+    why: "Quota math, and a teachable premise correction: uploads use a separate ~100 videos.insert/day call cap, not the shared 10k unit pool (official docs, Last updated 2026-06-01 UTC). Debugging the Data API, this skill's domain."
+  - prompt: "Fetch this month's traffic sources and write them into docs/wiki/youtube/."
+    why: "The ingestion deliverable: insightTrafficSourceType report appended to the channel feedback log."
+  - prompt: "I keep getting uploadLimitExceeded even though I have quota units left."
+    why: "Non-obvious separate daily upload-count cap distinct from unit quota — this skill explains the throttle-count rule."
+
+should_not_trigger:
+  - prompt: "What kind of videos should my channel make to grow this quarter?"
+    route_to: youtube-strategy
+    why: "Growth plan / niche / cadence is strategy; this skill only delivers the numbers, it does not set the plan."
+  - prompt: "Write me 5 high-CTR title and thumbnail text options for this video."
+    route_to: youtube-packaging
+    why: "Packaging/CTR copy. This skill fetches CTR; it does not write the title that lifts it."
+  - prompt: "Brainstorm 20 video ideas for my cooking niche."
+    route_to: youtube-ideation
+    why: "Idea generation, no API or ingestion involved."
+  - prompt: "Post this clip to Instagram, TikTok, and YouTube at the same time."
+    route_to: social-publisher
+    why: "Multi-network cross-posting; this skill is YouTube-only and deep on its two APIs."
+  - prompt: "Render the actual video file in code so I can upload it."
+    route_to: remotion-video
+    why: "Video production/rendering, not transport."
+  - prompt: "Wrap a generic REST API I picked with OAuth and retry/backoff."
+    route_to: api-connector-builder
+    why: "Arbitrary-provider connector; this skill is specific to YouTube's Data + Analytics APIs."
+
+capability:
+  - scenario: "Build a weekly cron that authenticates to a YouTube channel, fetches channel KPIs plus the retention curve and traffic sources for the latest video, and appends a dated entry to docs/wiki/youtube/."
+    must_include:
+      - "User OAuth 2.0 flow (not a service account) with a persisted, refreshable token"
+      - "Note that the OAuth consent screen must be 'In production' or refresh tokens die in ~7 days"
+      - "Analytics query using ids=channel==MINE with metrics including averageViewPercentage"
+      - "Retention via dimensions=elapsedVideoTimeRatio and metrics audienceWatchRatio"
+      - "Traffic via dimensions=insightTrafficSourceType"
+      - "Least-privilege scopes (yt-analytics.readonly, not full auth/youtube)"
+      - "Append-not-overwrite dated wiki entry with frontmatter (date/range/channel)"
+      - "Exponential backoff with jitter on 403 quotaExceeded / 429"
+      - "Never commit client_secret.json or token.json"