Communitygithub.com

puntorigen/skills

Habilidades locales para agentes de IA en Cursor y otros agentes de codificación con IA — 100% en tu máquina, sin nube, sin claves API. Optimizado para Apple Silicon (MLX/Metal): generación de imágenes local, clonación de voz, música de fondo, video de conversación, video→3D splat y STL imprimible, grabación de acciones web y edición de Word .docx.

¿Qué es skills?

Este conjunto de habilidades proporciona herramientas locales para agentes de codificación con IA como Cursor, Codex y otros, centrándose en tareas de producción de contenido multimedia que se ejecutan completamente sin conexión y sin depender de servicios en la nube. Incluye generación de imágenes con modelos MLX/Metal optimizados para Apple Silicon, clonación de voz de alta calidad (con soporte para múltiples idiomas), generación de música instrumental libre de regalías con ACE-Step 1.5, creación de videos de conversación a partir de una foto y audio, conversión de video a nubes de puntos 3D (splat) y modelos STL imprimibles, grabación y reproducción de acciones web para automatización de pruebas, y edición programática de documentos Word (.docx). Todo se almacena y ejecuta localmente en ~/.bg-music/, ~/.voice-clone-narration/, etc., requiriendo solo una descarga inicial de modelos y dependencias. Es especialmente útil para desarrolladores que necesitan generar activos multimedia sin enviar datos a la nube, manteniendo la privacidad y el control total sobre su contenido.

Compatible con✓Claude Code~Codex CLI✓Cursor
npx skills add puntorigen/skills

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Música de Fondo

Genera música instrumental original y libre de regalías para reels y videos demo a partir de un brief de texto - completamente fuera de línea. Un wrapper impulsa ACE-Step 1.5 (el modelo de música); tú (el modelo) das forma al brief para crear un buen prompt, generas un par de candidatos, dejas que el usuario elija y, opcionalmente, mezclas el ganador debajo de una narración.

Se combina con la habilidad clonación-de-voz-narración: genera la locución allí, la música aquí, luego mix_voiceover.sh atenúa la música bajo la narración para obtener una pista de audio de reel terminada.

flowchart LR
  Brief["brief: género, estado de ánimo, bpm, duración"] --> Gen["generate_music.py<br/>ACE-Step 1.5 (MLX), instrumental"]
  Gen --> Mp3["mp3s candidatos"]
  Nar["narración.mp3 (opcional)"] -.-> Mix["mix_voiceover.sh<br/>ffmpeg sidechain ducking"]
  Mp3 -.-> Mix
  Mix -.-> Reel["reel-audio.mp3"]

Todo vive fuera del repositorio en ~/.bg-music/ (el checkout de ACE-Step, pesos del modelo y audio generado).

Requisitos previos

  • uv (gestor de paquetes) y git - el modelo es una aplicación uv sync, no una instalación pip simple. La configuración lo instala en un entorno aislado.
  • ffmpeg en PATH (codificación MP3 + mezcla). Detente y pide al usuario que ejecute brew install ffmpeg si falta.
  • ~10 GB de disco libre para el código + los pesos del modelo (descargados una vez desde Hugging Face, anónimamente - sin token). Reserva más si usas variantes de modelo más grandes.
  • Mac con Apple Silicon para la ruta nativa rápida (MLX). En CUDA/CPU recurre a PyTorch (más lento en CPU). 16 GB de memoria unificada son suficientes para el nivel 2B-turbo + 0.6B-LM predeterminado.
  • Internet solo en la primera ejecución (para obtener código + pesos). La generación es offline.

Configuración

Resuelve el directorio de la habilidad y ejecuta la configuración una vez (clona ACE-Step 1.5 y sincroniza su entorno - la primera ejecución descarga dependencias y puede tardar varios minutos):

SKILL_DIR="<la carpeta donde vive este SKILL.md>"   # ej. .cursor/skills/bg-music
bash "$SKILL_DIR/scripts/setup_env.sh"

Luego establece los manejadores utilizados por la generación (la configuración también los imprime):

BG_HOME="${BG_MUSIC_HOME:-$HOME/.bg-music}"
PY="$BG_HOME/ACE-Step-1.5/.venv/bin/python"

Flujo de trabajo

Copia esta lista de verificación y sigue el progreso:

- [ ] 1. Confirmar el brief: género, estado de ánimo, tempo (BPM), duración, instrumentos clave
- [ ] 2. Configuración: ejecutar setup_env.sh (solo la primera vez)
- [ ] 3. Escribir un prompt concreto; generar 2 candidatos
- [ ] 4. Reproducir/enlazar los candidatos; dejar que el usuario elija (regenerar si es necesario)
- [ ] 5. (Opcional) Mezclar el ganador bajo una narración en mp3 con ducking
- [ ] 6. Entregar los mp3(s)

Paso 1: Definir el brief

La calidad de la música depende de un prompt concreto. Obtén esto del usuario (o infiere y indica tus elecciones):

  • Género/estilo: lo-fi hip hop, orquestal cinematográfico, ambiente corporativo, synthwave, folk acústico, pop animado...
  • Estado de ánimo: tranquilo, edificante, tenso, soñador, enérgico, melancólico.
  • Tempo: lento / medio / rápido, o un BPM explícito (ej. 90).
  • Duración: segundos (10-600; los reels suelen durar 30-120).
  • Instrumentos clave (opcional): piano Rhodes, pads cálidos, batería suave, guitarra nylon.

Paso 3: Generar

"$PY" "$SKILL_DIR/scripts/generate_music.py" \
  --prompt "warm lo-fi hip hop, mellow Rhodes piano, soft vinyl crackle, laid-back drums, loopable, instrumental" \
  --bpm 80 --duration 60 --count 2 \
  --out "$BG_HOME/out/lofi.mp3"
  • Las pistas son instrumentales por defecto (sin voces).
  • --count 2 produce dos variaciones para elegir (lofi-1.mp3, lofi-2.mp3).
  • Escribe MP3s e imprime sus rutas + duraciones. La primera ejecución descarga los pesos del modelo; las ejecuciones posteriores son mucho más rápidas.

Los buenos prompts son específicos y separados por comas. Incluye género + estado de ánimo + 2-3 instrumentos + una palabra de tempo + "instrumental"/"loopable". Ejemplos:

  • "cinematic inspiring orchestral, soft strings, piano, subtle percussion building to a warm swell, instrumental"
  • "clean corporate ambient, gentle synth pads, light plucks, optimistic, minimal, instrumental"
  • "driving synthwave, analog bass, retro arpeggios, punchy drums, night-drive energy, instrumental"

Paso 5: Mezclar bajo una narración (opcional)

Si el usuario también tiene una locución (ej. de la habilidad clonación-de-voz-narración), atenúa la música automáticamente debajo de ella:

bash "$SKILL_DIR/scripts/mix_voiceover.sh" \
  --voice ~/.voice-clone-narration/out/test-en.mp3 \
  --music "$BG_HOME/out/lofi-1.mp3" \
  --out ~/Desktop/reel-audio.mp3

La música se baja automáticamente cuando la voz está hablando (compresión sidechain), luego vuelve a subir en los silencios. Se repite para cubrir la narración y se desvanece al inicio/fin. Ajusta con --music-gain (nivel de fondo, por defecto -8 dB), --duck (intensidad de atenuación, por defecto 8) y --fade.

Paso 6: Entregar

Incrusta o enlaza el mp3 elegido. Los archivos generados permanecen en ~/.bg-music/out/.

Opciones clave (generate_music.py)

OpciónPredeterminadoPropósito
--prompt(obligatorio)Descripción de la música: género, estado de ánimo, instrumentos, ambiente.
--duration60Longitud en segundos (10-600).
--bpmautoTempo en BPM (30-300); omite para que el modelo elija.
--count2Cuántas variaciones generar.
--outout/music-<ts>.mp3Ruta de salida (o prefijo cuando --count > 1).
--seedaleatorioFijar para reproducibilidad.
--keyscaleautoTono musical, ej. "La menor".
--vocalsoff (instrumental)Permitir voces (rara vez se desea para música de fondo).
--steps8Pasos de difusión (predeterminado turbo; más = más lento, marginalmente mejor).
--mp3-quality2ffmpeg libmp3lame -q:a (0=mejor..9=más pequeño).
--keep-wavoffConservar el wav intermedio.

Opciones clave (mix_voiceover.sh)

OpciónPredeterminadoPropósito
--voice(obligatorio)mp3/wav de narración (se mantiene al nivel completo).
--music(obligatorio)mp3/wav de música de fondo (se atenúa + se repite para cubrir la voz).
--out(obligatorio)mp3 mezclado de salida.
--music-gain-8Nivel base de la música en dB (más bajo = fondo más silencioso).
--duck8Intensidad de atenuación (relación del compresor); más alto = la música baja más bajo el habla.
--fade2Segundos de desvanecimiento de entrada/salida de la música.
--mp3-quality2ffmpeg libmp3lame -q:a.

Seguridad

  • Revela la música generada por IA donde la plataforma o el contexto lo requieran.
  • Uso comercial: ACE-Step 1.5 tiene licencia MIT y está entrenado con datos con licencia / libres de regalías / sintéticos, por lo que las pistas generadas son generalmente seguras de usar. Aún así, según el propio descargo de responsabilidad del modelo, evita prompts que copien la identidad de un artista o pista específicos, y verifica la originalidad antes de la publicación comercial.
  • Nunca subas briefs, prompts o audio generado a ningún servicio externo. Todo permanece local en ~/.bg-music/.

Antipatrones

  • Prompts vagos de una palabra ("música", "algo cool") - obtienes una salida genérica. Da género + estado de ánimo + instrumentos + tempo.
  • Pedir voces cuando solo necesitas un fondo - mantenlo instrumental (el valor predeterminado) para que se asiente limpiamente debajo de la narración.
  • Generar una sola toma y enviarla - genera --count 2 y deja que el usuario elija.
  • Superponer música manualmente debajo de una locución - usa mix_voiceover.sh para que la música se atenúe automáticamente debajo del habla.
  • Preguntar por "una canción que suene exactamente como <artista/pista>" - riesgo de originalidad y licencia.
  • Confirmar cualquier cosa de ~/.bg-music/ en un repositorio.

Recursos

  • Zoo de modelos (por qué 2B-turbo en 16 GB), la hoja de referencia de parámetros completa, patrones de prompt por estado de ánimo, justificación de licencias y solución de problemas: REFERENCE.md
  • Generar la narración para mezclar debajo de la música: la habilidad clonación-de-voz-narración.
  • Verificar el audio final en un video: la habilidad revisar-mp4.

Skills relacionados