alt — Auto-Caption
Ejecuta un VLM local sobre cada imagen en input_dir y escribe un archivo JSON complementario en output_dir. Útil para generar subtítulos automáticamente, comprender contenido por lotes o alimentar descripciones a otras herramientas.
El directorio del skill (donde reside este SKILL.md) se denomina $SKILL_DIR a continuación.
Cuándo usarlo
Usa este skill cuando el usuario quiera:
- Generar subtítulos automáticos para Instagram a partir de fotos
- Entender qué hay en un lote de imágenes sin revisarlas manualmente
- Alimentar descripciones de imágenes a un pipeline de contenido o herramienta de programación
Configuración (solo la primera vez)
cd "$SKILL_DIR" && uv sync
Los pesos de moondream2 se descargan en el primer uso (~4 GB desde HuggingFace). Los pesos de Phi-4 son más grandes (~8 GB) y requieren una GPU.
Flujo de trabajo del agente
1. Preguntar al usuario
Antes de describir las imágenes, necesito saber:
🧠 Modelo
- moondream2 — 2B parámetros, rápido, funciona en CPU (por defecto)
- phi4 — 3.8B multimodal, mayor calidad, requiere GPU
💬 Estilo de subtítulo (opcional — usaré un valor predeterminado sensato)
p. ej. "Casual y divertido con emojis" o "Profesional e inspirador"
⚙️ Dispositivo
- auto — GPU si está disponible, si no CPU (por defecto)
- cpu — solo moondream2; ~7s/imagen en una CPU de escritorio moderna
📁 Directorios de entrada / salida (por defecto: ./input y ./output)
2. Editar config.json
Si el usuario proporciona un estilo de subtítulo, intégralo en prompt_caption.
Ejemplo: "Escribe un subtítulo divertido y rico en emojis para Instagram para esta imagen. Incluye 3-5 hashtags."
Si el usuario solicita imágenes con la marca, consulta skills/brand-manager/brand-assets/asset-manifest.json para ver las fuentes disponibles y menciona la fuente de marca preferida en las instrucciones del subtítulo generado o en las notas de entrega. Este skill solo escribe archivos JSON complementarios, por lo que no renderiza texto por sí mismo; los renderizadores posteriores, como visual-hook, video-captioner y end-cta, deben usar los archivos de fuente de marca reales cuando se especifiquen y estén disponibles.
3. Ejecutar
cd "$SKILL_DIR" && uv run python scripts/describe.py --config config.json
La primera ejecución descarga los pesos del modelo: advierte al usuario que esto puede tardar unos minutos.
4. Informar resultados
Muestra la descripción y el subtítulo de cada imagen. Indica al usuario dónde se escribieron los archivos JSON.
Referencia de configuración
| Clave | Valores | Por defecto | Descripción |
|---|---|---|---|
input_dir | ruta | ./input | Carpeta de imágenes de origen |
output_dir | ruta | ./output | Carpeta de destino para archivos JSON complementarios |
model | moondream2, phi4 | moondream2 | Modelo de visión y lenguaje |
prompt_description | cadena | "Describe esta imagen en una oración." | Prompt para el campo de descripción |
prompt_caption | cadena | "Escribe un subtítulo atractivo para Instagram…" | Prompt para el campo de subtítulo |
device | auto, cpu, cuda | auto | Dispositivo de inferencia |
Invocaciones comunes
# Por defecto (moondream2, dispositivo auto)
cd "$SKILL_DIR" && uv run python scripts/describe.py
# Mayor calidad (requiere GPU)
cd "$SKILL_DIR" && uv run python scripts/describe.py --model phi4
# Forzar CPU
cd "$SKILL_DIR" && uv run python scripts/describe.py --device cpu
# Prompt de subtítulo personalizado
cd "$SKILL_DIR" && uv run python scripts/describe.py \
--prompt-caption "Escribe un subtítulo profesional para LinkedIn para esta imagen."
Salida
Para cada photo.jpg en input_dir, escribe photo.json en output_dir:
{
"description": "Una mujer en una cafetería iluminada por el sol sosteniendo una taza de café.",
"caption": "Rituales matutinos ☕✨ Empezando el día bien. #coffeetime #mañanavibes #cafetería",
"tags": ["retrato", "café", "interior", "luz cálida"]
}
Cuando las fuentes de la marca sean relevantes, incluye el nombre/etiqueta de la fuente en las instrucciones posteriores en lugar de incrustar un archivo de fuente en este JSON. Los skills de renderizado son responsables de resolver la ruta del manifiesto y aplicar la fuente.
Manejo de errores
phi4+cpu→ rechazado en la validación de configuración con un mensaje claro- Fallos en la descarga del modelo → se muestran con detalles del error de HuggingFace
- Errores individuales de imagen → se registran; el resto de imágenes continúan
Inferencia remota
Este skill admite subtitulado remoto opcional manteniendo el mismo formato de salida JSON.
- El comportamiento predeterminado sigue siendo local
- Los proveedores remotos son opt-in solamente
- Proveedores compatibles:
huggingface,replicate
Claves de configuración
| Clave | Por defecto | Notas |
|---|---|---|
provider | null | null, local, o none mantiene el modo local |
remote_model | null | Sobrescritura opcional del modelo VLM específico del proveedor |
hf_token_env | HF_TOKEN | Nombre de la variable de entorno de autenticación de HuggingFace |
replicate_api_key_env | REPLICATE_API_TOKEN | Nombre de la variable de entorno de autenticación de Replicate |
remote_timeout_seconds | 300 | Tiempo de espera de la llamada remota |
Ejemplos
# Subtitulado remoto con HuggingFace
export HF_TOKEN=hf_your_token
uv run python scripts/describe.py --config config.json --provider huggingface
# Subtitulado remoto con Replicate
export REPLICATE_API_TOKEN=r8_your_token
uv run python scripts/describe.py --config config.json --provider replicate --remote-model <replicate-model-slug>
Notas
- El modo remoto sigue escribiendo el mismo archivo JSON complementario con
description/caption/tags - La falta de credenciales falla rápidamente; no hay fallo silencioso al modo local
- Replicate requiere un slug de modelo explícito para el subtitulado remoto
Estándares de calidad de subtítulos
El subtítulo es tan importante como la imagen. Un subtítulo débil desperdicia un visual potente. Aplica estos principios al generar o solicitar subtítulos.
Regla de uno
Cada subtítulo debe transmitir una idea central clara. Si el subtítulo intenta comunicar múltiples puntos, se vuelve difuso y pierde impacto. Los subtítulos más potentes tienen un único punto central: una promesa, una lección, una observación, un golpe narrativo.
Prueba: ¿puedes resumir este subtítulo en una oración? ¿Todas las líneas apoyan la misma idea? Si no, recorta hasta que el núcleo esté claro.
Gancho primero
La primera línea de cualquier subtítulo es el gancho. En Instagram, solo se muestran los primeros ~125 caracteres antes de "más" — esa primera línea debe ganarse el toque. En LinkedIn, la primera línea es el titular.
Patrones de gancho que funcionan:
- Contrario: "Deja de hacer X."
- Brecha de curiosidad: "La mayoría de la gente no se da cuenta…"
- Llamada a la identidad: "Si eres [X], presta atención."
- Autoridad/experiencia: "Si tuviera que empezar de nuevo, esto es lo que haría."
- Punto de dolor: "Por eso estás estancado en [X]."
Evita abrir con "Yo" o con una frase de calentamiento que no diga nada. La primera línea debe ganarse el resto de la lectura.
Estructura específica de la plataforma
Instagram:
- Gancho primero (≤125 caracteres)
- Cuerpo: historia, lección o reflexión
- 3–5 hashtags relevantes al final
- Tono auténtico: evita el lenguaje de marketing pulido
- Los emojis son aceptables pero deben reforzar el significado, no decorar
LinkedIn:
- 600–800 caracteres para mejor alcance; 100–150 para alta tasa de clics cuando sea necesario
- Gancho potente en la primera línea
- Sin enlaces externos en el cuerpo de la publicación (LinkedIn suprime el alcance de los enlaces salientes)
- Marcos que funcionan: Gancho → reflexión → desglose → CTA; o Historia → lección → acción → pregunta de participación
- Claridad sobre creatividad: los lectores escanean rápido
- Evitar: exceso de emojis, espacios en blanco excesivos, mismo formato consecutivo, fuentes externas
Prueba antigénérica
Antes de aceptar un subtítulo generado, pregúntate: ¿suena como el experto que tomó esta foto, o suena como escritura genérica de IA? Si podría haber sido escrito por cualquiera sobre cualquier cosa, no sirve. El subtítulo debe reflejar un punto de vista, observación o momento vivido específico.
Evitar
- Abrir con "Yo" como primera palabra
- Declaraciones inspiradoras vagas sin un punto concreto
- Emojis usados como relleno visual en lugar de reforzar el significado
- Más de una llamada a la acción en un solo subtítulo
- Spam de hashtags (10+ hashtags) en LinkedIn