---
name: "constructor-skills"
description: 'Convierte un proceso repetible en una skill lista para usar: filtro para decidir si merece ser skill, bloque de una existente o Apps Script, guion de preguntas, anatomía, cómo se escribe y se prueba la description, prueba con y sin la skill, entrega en dos archivos y bitácora. Activar SIEMPRE que aparezca una señal de querer capturar o automatizar un proceso, aunque no se diga skill: "armemos una skill", "esto lo hago siempre igual", "quiero automatizar esto", "esto podría correr solo", "todos los lunes hago", "hacele una skill a un compañero", "¿esto va en la skill que ya tengo?", "cargalo en la bitácora", "revisá la description", "esta skill no se activa", "probá la skill", "mejorá esta skill", o si la persona pega la transcripción de una entrevista o describe paso a paso cómo hace algo. También al revisar, versionar, dividir o auditar una skill. Ante la duda, activala.'
---
# constructor-skills
Versión: v04 general · 13 de octubre de 2026 · Derivada de constructor-skills v11 (versión personal)
---
## ✏️ Antes de instalarla: completá tus datos
Esta skill es una **plantilla**. Todo lo que está entre `[CORCHETES]` es un dato
tuyo: reemplazalo por el tuyo, sin dejar los corchetes.
| Dato | Qué poner | Ejemplo |
|---|---|---|
| `[TU NOMBRE]` | Cómo te llamás | Ana |
| `[CARPETA PARA BORRAR]` | La carpeta de tu Drive donde van las versiones viejas, hasta que las borres | 07 · Para borrar |
| `[ID DE TU CARPETA 05 · SKILLS]` | El ID de la carpeta de Drive donde guardás las skills (lo ves al final de la URL de la carpeta) | 1AbC…xyz |
Cuando termines, **borrá este bloque entero** (desde el título "Antes de
instalarla" hasta la línea de abajo) y guardá la skill.
---
Convierto procesos en skills. El objetivo no es escribir un documento lindo:
es que la persona reciba algo que le resuelva el trabajo el primer día.
> En esta skill **"vos" es [TU NOMBRE]**. Las órdenes en imperativo son para
> Claude.
---
## 1. Primero el filtro: ¿esto merece ser una skill?
⚠️ **No todo proceso merece una skill.** Una skill mal elegida agrega
mantenimiento sin ahorrar tiempo, y es el error que más desprestigia el
proyecto adentro de la empresa.
Aplicá los tres criterios. **Si falla uno, no es skill.**
| Criterio | Se cumple si… | No es skill si… |
|---|---|---|
| **Frecuencia** | pasa al menos 2 veces por mes | pasa una vez por trimestre |
| **Formato estable** | el resultado tiene siempre la misma forma | cada vez sale distinto |
| **Criterio repetible** | las decisiones siguen reglas explicables | depende del olfato de la persona ese día |
**Qué hacer si no pasa el filtro:**
- Frecuencia baja, formato estable → **plantilla** en Drive, no skill.
- Frecuencia alta, formato inestable → todavía no está listo. Falta
entender el proceso, no automatizarlo.
- Todo estable pero el criterio es tácito → **primero documentarlo**, y
recién después convertirlo.
💡 Decir "esto no da para skill" es un resultado válido del relevamiento y
conviene decirlo en voz alta. Protege la credibilidad de las que sí se hacen.
### ⚠️ ¿Es una skill o es un Apps Script?
Un proceso puede pasar el filtro de arriba y aun así no ser una skill. Si
corre sobre datos de Google y no necesita criterio, un **Google Apps Script**
lo resuelve mejor: corre solo, sin que nadie esté presente.
**Detectalo por el disparador, que es la señal más rápida:**
| Cómo lo cuenta | Qué es |
|---|---|
| "todos los lunes", "el día 1 de cada mes" | Apps Script |
| "cuando llega el mail de", "cuando se carga la fila" | Apps Script |
| "cuando alguien completa el formulario" | Apps Script |
| "yo miro y decido", "depende del cliente" | Skill |
| "cuando necesito armar el comparativo" | Skill |
**Va como Apps Script si se cumple todo esto:**
- El disparador es una hora, una fecha o un evento, no una persona escribiendo
- Los datos viven en Google: Sheets, Gmail, Calendar, Drive, Forms
- La regla es determinista: mismo insumo, mismo resultado, sin criterio
- Tiene que correr aunque nadie esté mirando
**Va como skill si aparece cualquiera de estas:**
- El disparador es [TU NOMBRE] en una conversación
- Hace falta criterio, redacción o tono
- El insumo es desestructurado: un texto pegado, un PDF, una conversación
- La salida es una decisión o un texto, no una operación sobre datos
💡 **Muchas veces son las dos cosas.** El Apps Script junta y ordena, la skill
interpreta y redacta. Ejemplo: el script recolecta las respuestas de los
proveedores en una planilla; la skill escribe el comparativo y recomienda.
Cuando sea así, decilo: son dos entregables, no uno.
⚠️ **Qué hay que avisarle antes de proponer un Apps Script:**
- Solo funciona sobre Google Workspace. No sirve para Abejita ni para
sistemas externos.
- Corre con la cuenta dueña de los datos. Para datos de Oxean hay que hacerlo
desde la cuenta de Oxean, y eso necesita permiso de la empresa.
- Pide autorización de permisos amplios sobre la cuenta. Es una decisión de
seguridad, no un trámite.
- Es código: si se rompe, se rompe en silencio. Alguien lo tiene que mantener.
- Claude escribe el código, pero [TU NOMBRE] lo pega en script.google.com y
autoriza los permisos. Esa parte no la puede hacer Claude.
**Reportalo igual que las opciones de la sección 2**, en una línea:
`Conviene un Apps Script en vez de una skill` — porque [criterio].
En la bitácora se carga con Tipo = `Código`.
---
## 2. ¿Skill nueva o bloque de una que ya existe?
⚠️ **Nunca empieces a escribir sin haber revisado 05 · Skills primero.**
Antes de decidir nada, listá lo que ya hay en
`[ID DE TU CARPETA 05 · SKILLS]` y leé la description de las candidatas.
**El default es agregar, no crear.** Crear de más es el error más común: se
llena el repositorio de skills chicas y la persona termina teniendo que
activar tres para resolver una sola tarea.
### Va como bloque de una skill existente si…
- **Comparte el contexto fijo** — las mismas personas, el mismo sistema, el
mismo cliente, el mismo circuito
- **Se dispararía con las mismas frases** que la skill que ya existe
- **La usa la misma persona**, en el mismo momento de su trabajo
- Es una **etapa más** de un flujo que la skill ya cubre
### Va como skill nueva si…
- **El contexto fijo es otro** — otras personas, otro sistema, otro circuito
- **Se activaría en conversaciones donde la existente no debería activarse**
- **La usa otra persona u otra área**
- La skill existente **ya pasó los ~15.000 caracteres** y este bloque no se
usa en la mayoría de los casos
### ⚠️ La trampa del proceso consecuencia
Si el proceso **solo empieza cuando termina otro proceso** —nunca lo pide
nadie con esas palabras, pasa porque acaba de pasar otra cosa— entonces **no
puede ser skill**: no tiene disparador propio y no se activaría nunca sola.
Es un bloque de la skill que lo desencadena.
Ejemplo real: actualizar la bitácora. Nadie escribe "actualizá la bitácora";
pasa porque se acaba de entregar una skill. Por eso vive en la sección 9 de
esta skill y no en una skill aparte.
### 💡 El test de la description
Es el más confiable y el más rápido. **Intentá escribir la description de la
skill existente incluyendo el tema nuevo.**
- Si sale una oración natural → **es un bloque**, agregalo.
- Si tenés que unir dos mundos con un "y además…" y la frase queda rara →
**son dos skills**.
Una description que describe dos cosas distintas no activa bien ninguna de
las dos.
⚠️ Si al agregar el bloque la description **se pasa de 1024 caracteres**
(sección 6), eso también es señal de que son dos skills.
### Cuándo dividir una skill que ya existe
A veces la respuesta no es agregar ni crear, sino **partir**:
- La skill se activa para casos donde la mitad del contenido no aplica
- Hay dos audiencias distintas usando el mismo archivo
- La description ya no se puede escribir sin enumerar temas inconexos
⚠️ Dividir es una acción con costo: hay que reinstalar, reversionar y
actualizar la bitácora. **No lo propongas por prolijidad**, solo cuando la
skill esté fallando en activarse o entregando contenido de más.
### Qué reportar antes de escribir
Decile a [TU NOMBRE], en una línea, cuál de las cuatro es y por qué:
- `Va como bloque en [skill], sección [X]` — porque comparte [criterio]
- `Amerita skill nueva` — porque [qué no encaja en las que hay]
- `Conviene dividir [skill]` — porque [síntoma concreto]
- `Conviene un Apps Script` — porque [criterio de la sección 1]
**Esperá su confirmación antes de escribir.** Es la decisión más cara de
revertir del proceso.
---
## 3. Antes de escribir una línea: el baseline
⚠️ **Ningún proceso se convierte en skill sin medir antes cuánto tarda.**
El número de antes no se puede reconstruir después: una vez que la persona
usó la skill, cualquier estimación va a estar contaminada.
Pedí y anotá:
- **Antes (min):** cuánto tarda hoy, de punta a punta, en un caso real
- **Veces por mes:** el número, no "seguido" ni "bastante"
- **Qué parte duele:** dónde se traba, no dónde tarda
Si no hay número, la skill se hace igual, pero el entregable queda como
`sin medir` en la bitácora. Nunca inventes el baseline ni lo estimes por la persona.
---
## 4. Extraer el proceso: el guion
Sirve tanto si [TU NOMBRE] describe su propio flujo como si está procesando la
entrevista de otra persona.
### Antes de preguntar: ¿ya está en la conversación?
Si [TU NOMBRE] pide "convertí esto en skill" después de haber hecho el trabajo en
el chat, **extraé primero de la conversación** lo que ya se vio: las
herramientas que se usaron, los pasos en orden, las correcciones que hizo y el
formato de lo que salió. Después preguntá solo lo que falta y pedile que
confirme lo extraído. Preguntar lo que ya contó cansa y baja la calidad de las
respuestas.
Lo que tiene que quedar claro antes de escribir, venga de donde venga:
1. Qué tiene que poder hacer Claude gracias a la skill.
2. Con qué frases o situaciones tiene que activarse.
3. Qué forma tiene lo que entrega.
4. Si conviene probarla con casos. Si el resultado se puede verificar (un
archivo, campos fijos, un formato exacto), sí. Si es de criterio o de
redacción, se prueba igual, pero lo juzga quien la usa a ojo (sección 7).
**Las preguntas, en este orden:**
1. **Contame el último caso real, no el proceso en general.** ¿Qué te llegó
y qué entregaste?
2. **¿Con qué empieza?** Un mail, un pedido de alguien, una fecha del
calendario. Ese es el disparador.
3. **¿Qué información necesitás tener sí o sí antes de arrancar?** Esos son
los campos obligatorios.
4. **¿Qué hacés cuando falta un dato?** ¿Frenás, preguntás, o seguís con un
marcador? Esa es una regla, no un detalle.
5. **¿Qué forma tiene lo que entregás?** Pedí un ejemplo real, no una
descripción.
6. **¿A quién le llega y qué hace con eso?** Define el nivel de detalle.
7. **¿Qué sale mal seguido?** Los errores frecuentes son la mitad del valor
de la skill.
8. **¿Qué hacés distinto que otro no haría igual?** Ahí está el criterio
propio, que es lo único que no se puede googlear.
⚠️ **Pedí siempre un ejemplo real de la salida.** Una skill escrita desde la
descripción de un proceso sale genérica; escrita desde un ejemplo concreto
sale usable. Si no hay ejemplo, pedilo antes de escribir.
💡 **Escuchá los desvíos.** Cuando alguien dice "salvo que…", "menos cuando…",
"si es para tal cliente hago otra cosa" — eso son las reglas condicionales, y
son lo que diferencia una skill que sirve de una que hay que corregir siempre.
---
## 5. Anatomía de una skill que funciona
El orden importa: lo que más se usa va arriba.
1. **Encabezado** — nombre, versión y fecha. Una línea de qué hace.
2. **Contexto fijo** — personas, roles, sistemas, clientes. Lo que no cambia
entre un caso y otro.
3. **El flujo, etapa por etapa** — numerado, con quién interviene en cada una.
4. **Los formatos obligatorios** — plantillas exactas, en bloque de código,
listas para copiar y pegar.
5. **Checklists** — uno por etapa que tenga más de tres pasos.
6. **Reglas de estilo y de respuesta** — cómo tiene que contestar Claude.
**Reglas de escritura:**
- Escribí en imperativo dirigido a Claude, no en descripción neutra.
"Pedí el número de proyecto" funciona; "es importante el número de
proyecto" no.
- Las plantillas van en bloque de código, listas para copiar.
- Los datos críticos en **negrita**; 💡 para consejo, ⚠️ para advertencia.
- Los datos que cambian seguido (precios, contactos puntuales) **no van en la
skill**. Se piden en el momento.
- Nunca credenciales, claves de API ni datos de conexión.
- **Sin registro de cambios adentro del archivo.** Para eso están el
versionado y la bitácora.
**Si es un bloque nuevo en una skill existente:** respetá el orden de la
anatomía. Un bloque de contexto va arriba, una etapa nueva va en su lugar
dentro del flujo, un checklist va con los otros checklists. No lo pegues al
final por comodidad.
### Tres niveles de carga: dónde va cada cosa
Una skill se carga en tres momentos, y de ahí sale dónde poner cada cosa:
1. **`name` + `description`**: siempre están en el contexto. Es lo único que
Claude ve para decidir si activa la skill.
2. **El cuerpo del `SKILL.md`**: se lee recién después de que se activó.
3. **Archivos aparte** (`references/`, `scripts/`): solo se leen o se corren
cuando el cuerpo lo indica.
Qué se desprende:
- **Todo lo de "cuándo usarla" va en la `description`.** Una sección
"Palabras activantes" dentro del cuerpo no ayuda a que se active, porque el
cuerpo todavía no se leyó. Si querés dejar frases de ejemplo, que estén en la
`description`.
- **El cuerpo, idealmente por debajo de las 500 líneas.** Si se pasa, antes de
partir en dos skills (sección 2) probá mover el detalle que no se usa en cada
caso a archivos en `references/`: el cuerpo dice cuándo leer cada uno y, si el
archivo pasa las 300 líneas, trae un índice al principio. Partir cuesta más:
hay que reinstalar y reversionar.
- **Cuando una skill cubre variantes** (por cliente, por área), el cuerpo
decide cuál es y manda a leer solo el archivo de esa variante.
⚠️ **No probado en Oxean.** La entrega de hoy es un solo `SKILL.md`. Una skill
con carpetas se entrega como paquete `.skill`, y no se verificó que la tarjeta
de instalación lo acepte ni cómo se respalda en el Drive. Probalo primero con
una skill chica antes de adoptar `references/`.
### Explicá el porqué, y pensá en casos que no viste
- **Cada regla lleva su razón.** "Pedí el número de proyecto, porque sin él no
se puede cruzar con Abejita" se aplica con criterio; "SIEMPRE pedí el número"
se aplica rígido o se ignora. Si te descubrís escribiendo NUNCA o SIEMPRE en
mayúsculas sin motivo, reformulalo con la razón.
- **Excepción:** las reglas duras de la plataforma o de seguridad (el nombre, el
tope de 1024, las credenciales) quedan firmes: no tienen matiz que explicar.
- **La skill se va a usar con pedidos que no estaban en la entrevista.** No la
ajustes a los ejemplos: si una regla solo sirve para el caso que se probó,
buscá la regla general que está detrás.
### Que nada sorprenda
El contenido de una skill no puede sorprender a quien la instala, según lo que
dice su `description`. No lleva código malicioso, ni pasos para saltarse
permisos o sacar datos de la empresa, ni hace algo distinto de lo que promete.
Interpretar un rol ("respondé como un editor") está bien. Si alguien pide una
skill engañosa, no se escribe.
### ⚠️ El nombre de la skill (`name`)
⚠️ **El `name` no puede contener las palabras `claude` ni `anthropic`.** La
plataforma rechaza la instalación y la skill no se guarda. Aplica a cualquier
parte del nombre: `prompt-claude-code` no instala, `prompt-codigo` sí.
Caso real: `prompt-claude-code` falló al instalarse (8/10) y hubo que
renombrarla `prompt-codigo`, reentregar `oxean-git-deploy` (que la nombraba) y
regenerar la bitácora. El nombre es lo primero que se decide, y cambiarlo
después cuesta una cadena de reentregas.
**Cómo elegir el nombre:**
- Elegilo **antes de escribir**, y chequealo contra la regla en ese momento.
- Nombrá la skill por lo que hace (`prompt-codigo`, `oxean-produccion`), no
por la herramienta con la que se usa.
- Minúsculas y guiones, como las que ya hay en 05 · Skills. Revisá que no
choque con el nombre de otra.
- Cuando una skill nombra a otra (una tabla, una referencia), usá el nombre
ya validado.
**Si hay que renombrar una skill que ya existe:**
1. Buscá el nombre viejo en **todas** las skills y en la bitácora: las
referencias cruzadas también se rompen.
2. Versioná todas las que lo nombran, no solo la renombrada.
3. En la bitácora, el nombre cambia en su entrada (no se crea una nueva) y el
motivo va en `Qué falló al usarlo`.
4. Avisale a [TU NOMBRE] que desinstale la skill con el nombre viejo, y que borre
del Drive el archivo con el nombre viejo.
---
## 6. La description: lo que más falla
⚠️ **Una skill excelente con mala description no se activa nunca, y es como
si no existiera.** Es el error número uno.
### ⚠️ Límite duro: 1024 caracteres
El campo `description` **no puede pasar de 1024 caracteres**. Si se pasa, la
instalación falla con el mensaje:
```
field 'description' in SKILL.md must be at most 1024 characters
```
**Contala antes de entregar.** No la estimes a ojo: una description bien
escrita queda cerca del límite y ocho caracteres alcanzan para romperla.
**Cómo recortar sin perder activación**, en este orden:
1. Sacar frases de activación **redundantes** — dos que se disparan igual
2. Acortar el bloque de "qué contiene": es informativo, no activa nada
3. Sacar aclaraciones entre paréntesis
4. **Último recurso:** frases de activación. Son lo que hace el trabajo.
💡 Apuntá a **900 caracteres**, no a 1020. Deja lugar para las frases que
vas a querer sumar en la próxima versión.
### Qué tiene que responder
1. **Qué hace** — en una oración.
2. **Qué contiene** — para que se distinga de skills parecidas.
3. **Cuándo activarse** — la parte larga, y la que hace el trabajo.
**Reglas del bloque de activación:**
- Listá las frases reales que la persona usaría, **no las palabras técnicas**.
Nadie escribe "solicitar cotización a proveedor": escribe "necesito
presupuestar esto".
- Incluí explícitamente los casos donde el tema aparece **sin nombrarse**.
- Cerrá con **"Ante la duda, activala."** cuando la skill es de dominio y
conviene que se dispare de más.
- Claude tiende a **activar de menos**, no de más: por eso la description va
firme y con frases concretas. Pasarse también cuesta (carga la skill donde no
hace falta), y por eso la regla de las vecinas más abajo.
⚠️ **Si agregaste un bloque, actualizá la description en la misma versión.**
Un bloque nuevo que no aparece en la description es contenido que nadie va a
disparar. Es el error más silencioso de todos.
### El set de 20 frases de prueba
Imaginar tres mensajes no alcanza. Armá **20 frases** y guardalas:
- **10 que tienen que activarla**: formales y casuales, de distinto largo, con
el tema sin nombrar en algunas, y alguna donde compite con una vecina y tiene
que ganar esta.
- **10 que no**, y acá está lo que vale: no frases obviamente ajenas, sino
**casi-aciertos**, que comparten palabras o tema con la skill pero piden otra
cosa. "Revisá este mail" para `oxean-edicion` cuando el mail ni está escrito.
Las frases tienen que sonar a pedido real, con contexto y detalle ("tengo que
pedir presupuesto de 40 placas para el stand de un cliente y no sé a quién…"), no a
consigna ("presupuestar"). Y tienen que ser **pedidos de peso**: Claude solo
consulta una skill cuando la tarea no la resuelve solo. "Leé este PDF" no activa
casi ninguna skill, aunque la description sea perfecta.
**Cómo correrlo:**
1. Con agentes: dale a uno independiente solo la lista de `name` + `description`
de todo 05 · Skills y las 20 frases, y pedile que diga cuál skill cargaría
para cada una, sin mirar el cuerpo.
2. Sin agentes: hacelo vos, frase por frase, y decilo (es menos riguroso).
3. Fallos de "debía y no": sumá la frase real a la description. Fallos de "no
debía y sí": acotá la description o declará la vecina.
Guardá el set en el bloque de la skill en la bitácora: la próxima versión lo
vuelve a correr. El optimizador automático de `skill-creator` (`run_loop`) no se
usa: necesita el comando `claude -p`, que solo existe en Claude Code.
### ⚠️ Relación con las skills vecinas
Varias skills pueden activarse a la vez, y está bien: no se pisan, se
complementan. Lo que hay que evitar es que dos descriptions se confundan entre
sí, o que dos skills se contradigan cuando se cargan juntas.
Antes de entregar una description, mirá las que ya hay en 05 · Skills y fijate
con cuáles comparte vocabulario. Clasificá cada par:
- **Complementarias** (una escribe y la otra pule; una arma y la otra agenda):
pueden correr en secuencia. Decilo con una frase en la description de las
dos, por ejemplo "si el texto ya está escrito, sumar oxean-edicion".
- **De dominio distinto que se cruzan** (Abejita es producción y es código):
pueden activarse juntas, pero si dicen cosas distintas hay que decidir quién
manda. La precedencia va en el cuerpo, en una sección 0 de las dos, con una
tabla tema → skill.
**Reglas para escribir el bloque de activación con vecinas:**
- Escribí las frases como las diría [TU NOMBRE]: verbo + objeto ("pedile precio a
tu proveedor", "armá la cartelera"). Las listas de temas sirven solo como
complemento.
- Evitá "cualquier tema de X" o "SIEMPRE" sin frases concretas al lado: una
description tan amplia carga la skill en conversaciones que no la necesitan.
- Si un pedido real no activó la skill, sumá esa frase exacta en la próxima
versión.
- Al crear o versionar una skill, contá los caracteres de **todas** las
descriptions de 05 · Skills, no solo la de la skill, y avisá si alguna pasa
de 950.
---
## 7. Probar antes de entregar
⚠️ **Nunca entregues una skill sin haberla corrido.** Una skill que falla en
el primer uso quema la confianza de esa persona con la AI, y recuperarla
cuesta mucho más que probarla.
**Chequeo previo, antes de los casos:**
- [ ] `name` sin las palabras `claude` ni `anthropic`, en ninguna parte del nombre
- [ ] `description` por debajo de 1024 caracteres, contados
- [ ] El frontmatter tiene `name` y `description`
- [ ] El archivo se llama `SKILL.md`
- [ ] Si hay shell, corré `check-skill_vNN.py` (guardado junto a tus skills): hace los
chequeos de arriba, avisa si pasa las 500 líneas o si queda una sección
de activación en el cuerpo, y cuenta las descriptions de las vecinas
Corré tres casos:
- **Caso típico** — el que la persona hace todas las semanas
- **Caso incompleto** — falta un dato. ¿Frena, pregunta o inventa? Si
inventa, hay que arreglarla.
- **Caso borde** — el "salvo que…" que apareció en la entrevista
Si agregaste un bloque a una skill existente, sumá un cuarto caso: **uno de
los que la skill ya resolvía antes.** Sirve para confirmar que el bloque
nuevo no rompió lo que andaba.
Después de cada uno preguntate: ¿esto lo entregaría tal cual? Si la respuesta
es no, corregí la skill, no el pedido.
### Quién corre los casos
⚠️ **Quien escribió la skill no es el mejor para probarla.** Tiene todo el
contexto en la cabeza y la skill le parece mejor de lo que es.
- **Con agentes disponibles** (Claude Code, Cowork): un agente independiente
por caso **con** la skill y otro igual **sin** ella (el baseline), lanzados
todos juntos. Cada uno recibe la ruta de la skill, el pedido y dónde guardar
el resultado. Anotá cuánto tardó y cuánto gastó cada corrida: sin eso no se
puede decir si la skill ayuda.
- **Si es una versión nueva de una skill existente**, el baseline no es "sin
skill": es la versión anterior (el archivo `_vNN` viejo, que no se edita).
- **Sin agentes** (chat común): corré los casos de a uno siguiendo la skill, sin
baseline, y decile a [TU NOMBRE] que es una prueba menos rigurosa. Su revisión
compensa.
### Qué se mira
- **Resultados verificables** (un archivo, campos fijos, un formato exacto):
escribí aserciones concretas y, si se puede, chequealas con un script.
- **Resultados de criterio** (tono, redacción, diseño): que [TU NOMBRE] lea las dos
salidas lado a lado. No fuerces aserciones donde decide el ojo.
- **Una aserción que pasa igual sin la skill no mide nada**: sacala.
- **Leé cómo trabajó el agente, no solo qué entregó.** Si perdió tiempo en pasos
que la skill le mandó hacer y no aportaban, sacalos. Si todos los casos
terminaron escribiendo el mismo script o repitiendo los mismos pasos, eso va
adentro de la skill (ver *Mejorar una skill*, sección 10).
### Iterar
Corregí la skill, volvé a correr los mismos casos y compará con la vuelta
anterior. Frená cuando [TU NOMBRE] esté conforme o cuando una vuelta ya no mejore
nada. Guardá los pedidos de prueba en la bitácora, dentro del bloque de la
skill: la próxima versión los reutiliza.
💡 Si la pregunta es **"¿la versión nueva es realmente mejor?"**, dale las dos
salidas a un agente sin decirle cuál es cuál y que elija. Solo para decisiones
grandes; para el resto alcanza con la lectura de [TU NOMBRE].
---
## 8. Entrega: dos archivos y la bitácora al día
Sin que [TU NOMBRE] lo pida, y en este orden:
1. **Auditoría de coherencia** contra todo lo que hay en 05 · Skills
(está en la skill `base`), más el chequeo del nombre de la sección 5:
sin `claude` ni `anthropic`, y sin chocar con otra skill.
2. **`nombre-skill_vNN.md`** — respaldo en **05 · Skills** del Drive Oxean AI
(`[ID DE TU CARPETA 05 · SKILLS]`), como archivo `.md` real, nunca
convertido a Google Doc.
3. **`SKILL.md`** — con el frontmatter `name` y `description`, para que
aparezca la tarjeta con el botón **Guardar habilidad** y se instale de un
clic. Mismo contenido que el anterior, distinto nombre a propósito.
4. **La versión nueva de la bitácora de construcción** — sección 9. La
entrega no está completa sin esto.
⚠️ **Nunca entregues solo el texto en el chat para que lo copie a mano.**
**Antes de crear:** revisá qué hay en 05 y usá el número siguiente. Los
archivos existentes no se editan: se lee el actual y se crea el próximo.
**Después de crear:** devolvé el enlace directo.
---
## 9. La bitácora de construcción
**Dónde:** `04 · Vitrina`, como **Google Doc** versionado:
`Bitácora de construcción_vNN` (sin extensión). Es el único registro de lo que se
construyó en el proyecto: no existe una segunda lista en ningún otro lado.
⚠️ **Se versiona igual que una skill, y por el mismo motivo.** Los archivos
existentes no se editan. Entonces no se "agrega una fila":
**se regenera la bitácora entera y se sube como la versión siguiente.**
💡 **Por qué Doc y no `.md` ni planilla.** La bitácora la lee una persona, no
una skill: en Doc se ve con títulos, listas y tablas reales. Claude puede
crearla (subiendo markdown con la conversión activada) **y** leerla de vuelta
con la herramienta de Google Docs, que devuelve la estructura fiel. En cambio,
una planilla de Google no admite escritura y un `.xlsx` sube pero se lee vacío.
El `.xlsx` con diseño sigue existiendo como **exportación a pedido** para
mostrar afuera: no es un segundo original, es una salida generada.
⚠️ **El lector de Drive no sirve para un Doc:** trunca, rompe los emojis y deja
asteriscos sueltos. Leer siempre con la herramienta de Google Docs.
### El procedimiento
1. **Leer la bitácora vigente** en 04 · Vitrina, entera, con la
herramienta de Google Docs (`read_doc`).
2. **Agregar el entregable nuevo, o actualizar el que corresponda** — en la
tabla y en su bloque de Criterio.
3. **Recalcular el Resumen.** Los números se cuentan, no se arrastran.
4. **Pasarla a markdown con un script, editar, y crear el Doc nuevo**
`Bitácora de construcción_vNN+1` subiendo ese markdown **con** la conversión
a Google activada. Nunca transcribir a mano el contenido leído.
Reglas del script: `HEADING_n` → `#`×n · listas con viñeta o numeradas ·
fuente monoespaciada → backticks · negrita y cursiva · tablas → tablas con `|`.
5. **Releer el Doc nuevo con `read_doc`** y compararlo con el markdown: mismos
títulos, mismas filas de tabla, misma cantidad de ítems.
6. **Devolver el enlace**, mover la versión anterior a `[CARPETA PARA BORRAR]` y
avisar.
⚠️ **Un archivo o Doc recién creado puede leerse vacío durante unos minutos.** Es
demora de indexación del Drive, no un error de subida: el archivo está bien.
No volver a subirlo — esperar y releer.
⚠️ **La versión anterior la mueve Claude a `[CARPETA PARA BORRAR]`; borrarla lo
hace [TU NOMBRE].** Es irreversible: Claude nunca la borra ni la manda a la
papelera por cuenta propia.
### Un entregable, un bloque — no uno por versión
💡 Regenerar el archivo permite **modificar** lo que ya está, no solo agregar
al final. Por eso:
- Un entregable que sube de versión **no genera entrada nueva**: se actualiza
la suya (la columna `Ver.`, y `Qué falló al usarlo` si algo se rompió).
- `Reemplazada` es para un entregable sustituido por **otro distinto**, no por
un cambio de versión.
- Entrada nueva solo cuando aparece algo que antes no estaba.
### Estructura del archivo
**1 · Resumen** — entregables registrados, skills en uso, procesos medidos,
% medido, ahorro mensual. Todo calculado.
**2 · Entregables** — una tabla de ocho columnas, para escanear:
| Columna | Qué va |
|---|---|
| Fecha | `AAAA-MM-DD` de la primera entrega |
| Qué se construyó | Nombre. Si es un **bloque**, la skill anfitriona y la sección |
| Ver. | La vigente |
| Tipo | Skill · Bloque · Documentación · Plantilla · Código · Conector · Proyecto |
| Para quién | La persona o el área, no "todos" |
| Medición | `antes` · `después` · `veces/mes` → ahorro, o `sin medir` |
| Estado | En uso · Vigente · Sin uso · Reemplazada · Descartado · Pendiente |
| Archivo | `nombre-skill_vNN.md` |
**3 · Criterio** — un bloque por entregable, con tres campos:
**Por qué así**, **Qué se descartó** y **Qué falló al usarlo**.
💡 **La tabla y el Criterio están separados a propósito.** Los textos largos
metidos en celdas hacen la tabla ilegible; afuera se leen. La tabla es para
escanear el estado; el Criterio es lo que se muestra afuera.
### Reglas de carga
- **Sin medición, `sin medir`.** El baseline de la sección 3 va tal cual, y si
no hay número no entra en el total. **Nunca estimar para llenar el hueco**:
un entregable sin medir es honesto, uno inventado arruina el total.
- **Un bloque se carga igual que una skill**, con Tipo = `Bloque`. Si no, la
decisión de no haber creado una skill nueva se pierde, y es de las más
útiles para mostrar criterio.
- **Un Apps Script se carga con Tipo = `Código`**, y en `Por qué así` va el
criterio por el que no fue una skill.
- **Lo descartado también se carga**, con Estado = `Descartado` y el motivo.
Un entregable que no funcionó vale tanto como uno que anduvo.
- ⚠️ **Qué se descartó no se rellena de memoria.** Si esa decisión no está
documentada en ningún lado, se escribe *(sin documentar — completar de
memoria)* y se le avisa. Un dato faltante es mejor que uno inventado.
💡 **Por qué así y Qué se descartó son los campos que valen.** El resultado
final no enseña nada; el criterio sí, y el criterio es lo que Oxean le vende a
sus clientes. Son los dos que convierten la bitácora en material de Vitrina.
---
## 10. Versionado y auditoría
- Cambio de contenido → versión nueva, `_vNN`.
- El archivo del Drive es el original; la skill instalada es la copia.
Se edita primero el Drive.
- Al respaldar, anotá **hace cuánto no se toca** y **si se sigue usando**.
- Un renombre es un cambio de contenido en cascada: sigue los pasos de la
sección 5.
### Mejorar una skill que ya existe
- **Partí de la última versión del Drive**, no de la instalada: puede estar
desfasada.
- **Conservá el `name` exacto.** Cambiarlo rompe las referencias de las demás
(sección 5, *si hay que renombrar*).
- La versión anterior queda como baseline para la prueba de la sección 7.
- **Trabajo repetido → script.** Si al probarla Claude arma siempre el mismo
script o repite los mismos pasos, guardalo una vez en un archivo (por ejemplo,
`check-skill_vNN.py`, guardado junto a tus skills) y que la skill mande a usarlo. Así
nadie lo reinventa cada vez.
- **Lo que no aporta, se saca.** Una versión nueva no es solo agregar: revisá
qué partes la skill ya no necesita.
⚠️ **Una skill sin uso hace más de un mes suele estar mal definida**, casi
siempre por la description o porque no pasaba el filtro de la sección 1. Ese
diagnóstico es material directo para la Vitrina: es el error más frecuente
que va a aparecer cuando el resto del equipo empiece a crear las suyas.
Cuando pase, cambiá su Estado a `Sin uso` y escribí el motivo en
`Qué falló al usarlo`.
---
## 11. Errores frecuentes
| Error | Cómo se ve | Cómo se arregla |
|---|---|---|
| Skill enciclopedia | 40 páginas que nadie lee | Solo lo que se usa cada vez |
| Skill de un solo uso | Se armó por un caso puntual | Aplicar el filtro de la sección 1 |
| **Skill nueva que era un bloque** | Hay que activar tres skills para una tarea | Sección 2: revisar 05 antes de escribir |
| **Skill sin disparador propio** | Solo arranca cuando termina otro proceso | Es un bloque de la skill que lo desencadena |
| **Skill que debía ser un Apps Script** | [TU NOMBRE] tiene que abrir un chat para algo que podía correr solo | Sección 1: revisar el disparador antes de escribir |
| **Apps Script que debía ser una skill** | El código se rompe cada vez que aparece una excepción | Si hace falta criterio, es skill |
| **Nombre con "claude" o "anthropic"** | La plataforma rechaza el nombre al instalar | Sección 5: elegir el nombre antes de escribir; si hay que renombrar, buscar el viejo en todas las skills y en la bitácora |
| **Description de más de 1024** | No instala, error al guardar | Contarla antes; recortar por el orden de la sección 6 |
| **Bloque agregado sin tocar la description** | El contenido está y nunca se dispara | Actualizar la description en la misma versión |
| **Description sin relación declarada con las skills vecinas** | Se carga la skill equivocada, o se cargan dos que se contradicen | Declarar la complementariedad en la description y la precedencia en el cuerpo (sección 6) |
| Description muda | Nunca se activa sola | Reescribir con frases reales |
| **Description sin set de frases de prueba** | No se sabe si dispara hasta que falla en uso | Sección 6: 20 frases, 10 con casi-aciertos |
| **Palabras activantes en el cuerpo** | Una sección que se lee cuando ya no sirve | Sección 5: van en la `description` |
| **Probada por quien la escribió** | Parece andar y falla el primer día | Sección 7: agente independiente, con y sin la skill |
| **Aserciones que pasan sin la skill** | Todo en verde y no prueba nada | Sección 7: sacarlas |
| **Skill de más de 500 líneas** | Carga de más y cuesta mantenerla | Sección 5: `references/` antes de partir |
| **Reglas en mayúsculas sin razón** | Claude las aplica rígido o las ignora | Sección 5: explicar el porqué |
| Sin ejemplo de salida | El resultado sale genérico | Pedir un caso real antes de escribir |
| Datos volátiles adentro | Queda desactualizada en semanas | Pedirlos en el momento |
| Entregada sin probar | Falla el primer día | Los tres casos de la sección 7 |
| Sin baseline | No hay ahorro demostrable | Medir antes, siempre |
| **Prometer un paso que la herramienta no puede dar** | La skill dice "cargá la fila" y termina en un bloque para pegar a mano | Punto 7 de la auditoría: contrastar lo prometido contra las herramientas que hay |
| **Entrada nueva por cada versión** | La bitácora se llena de duplicados del mismo entregable | Sección 9: una entrada por entregable, se actualiza en su lugar |
| **Regenerar sin leer la vigente** | Se pierde todo lo cargado antes | Sección 9, paso 1: leer primero, siempre |
| **Resubir porque el archivo se leyó vacío** | Dos copias de la misma versión en el Drive | Es demora de indexación: esperar y releer |
