brand-motion-agent-skill

Brand Motion Agent Skill (logo-motion-guardrail)

Una habilidad de agente para animación de logotipos segura para la marca. Enseña a un agente de codificación con acceso al sistema de archivos (Claude Code, Open Code, Cursor y otros) a animar un logotipo ya aprobado sin redibujarlo: preservar la geometría canónica y el bloque final, mantener el movimiento contenido y apropiado para la marca, y ser honesto sobre lo que la fuente puede y no puede soportar. Produce briefs de movimiento y manifiestos neutrales respecto al renderizador y entrega a Remotion, SVG, Lottie/dotLottie, After Effects, FFmpeg o MLT/Kdenlive.

Mantenedor y creador: Aman Paudel — GitHub: poudelaman4

Repositorio: https://github.com/poudelaman4/brand-motion-agent-skill ID de habilidad instalada: animation-logo-skill · Entorno de ejecución: local, con acceso al sistema de archivos, determinista, neutral respecto al renderizador

Palabras clave de descubrimiento

brand-safe logo animation agent skill · Claude Code skill · Open Agent Skills schema · MLT video automation framework · automatización de revelado de logotipos · protección de identidad de marca · validación de geometría canónica · animación de logotipos SVG · revelado de logotipos Lottie · máquina de estados dotLottie · animación de logotipos Remotion · video de logotipo transparente · animación de logotipo sobre fondo blanco · control de calidad de diseño de movimiento con IA

Este README utiliza encabezados explícitos, tablas, bloques de código, rutas de instalación, modos de tarea y terminología para que los indexadores de IA, los rastreadores de LLM y el SEO de Google puedan identificar el repositorio con precisión sin depender de contexto oculto.

Qué es esto

Un paquete de habilidad de agente reutilizable, no un editor de video ni un renderizador. Enseña a un agente cómo:

• Auditar fuentes de logotipos vectoriales, ráster en capas, ráster aplanado y texto en vivo.
• Proteger geometría aprobada, marcas de palabra, contadores, espacio libre, colores y comportamiento alfa.
• Clasificar el logotipo, el movimiento narrativo, el contexto, el tiempo de ejecución, el fondo y la plataforma.
• Elegir un patrón contenido para identidades botánicas, geométricas, monogramas, marcas de palabra, insignias, educativas, premium, lúdicas, de bienestar o tecnológicas.
• Crear un brief de movimiento, un manifiesto preciso por fotogramas, un estado de movimiento reducido y un plan de control de calidad.
• Producir entregas neutrales respecto al renderizador o implementar un renderizador compatible cuando esté disponible.
• Inspeccionar fotogramas codificados, construir hojas de verificación exactas y comparar estados finales con tolerancias documentadas.
• Validar transiciones ráster extraídas en fotogramas fijos directos de inicio/medio/fin y en la salida decodificada antes de la entrega.

El video generativo nunca puede redibujar silenciosamente un logotipo aprobado. Cuando una fuente aplanada no contiene capas semánticas, la habilidad informa la limitación y ofrece una alternativa agrupada o de marca completa en lugar de inventar píxeles ocultos.

Estructura del repositorio

brand-motion-agent-skill/
├── SKILL.md                         # Agent instructions and task modes
├── README.md                        # This document
├── LICENSE                          # MIT license
├── requirements.txt                 # Optional Python inspection/QA utilities
├── assets/
│   ├── motion-brief-template.json   # Creative and approval brief
│   ├── motion-manifest-template.json# Executable motion contract
│   └── motion-tokens.json           # Timing, easing, and overshoot tokens
├── schemas/
│   └── motion-spec.schema.json      # JSON Schema for motion manifests
├── scripts/
│   ├── inspect_logo_assets.py       # Alpha and diagnostic component inspection
│   ├── validate_motion_spec.py      # Manifest validation
│   ├── make_checkpoint_contact_sheet.py
│   ├── compare_final_frame.py       # Encoded final-state comparison
│   └── check_skill.py               # Dependency-free self-check of this package
├── references/
│   ├── patterns/                    # Organic, geometric, monogram, wordmark, badge
│   ├── contexts/                    # Education/LMS, premium, playful, tech, wellness
│   ├── delivery/                    # Backgrounds, alpha, codecs, accessibility
│   ├── implementation/              # Remotion, vector/Lottie, AE, flattened raster
│   └── qa/                          # Checklist, manifest contract, failure catalog
└── evals/                           # Development prompts and fixtures

Requisitos previos

Requeridos para el formato principal de la habilidad:

• Git
• Un agente de codificación de IA con acceso al sistema de archivos
• Python 3.10+ para las utilidades incluidas

Recomendados para producción y control de calidad:

• FFmpeg y FFprobe
• Node.js y un renderizador como Remotion
• Un editor SVG o fuente vectorial para movimiento independiente del logotipo
• Kdenlive/MLT para ensamblaje de línea de tiempo editorial
• Un objetivo de prueba en navegador/entorno de ejecución para salida SVG, Lottie o dotLottie

El agente aún puede operar en modo Plan o Auditoría cuando un renderizador, FFmpeg o capas de fuente no estén disponibles. Debe marcar el renderizado o el movimiento independiente de capas como BLOCKED en lugar de adivinar.

Instalación

1. Clonar el repositorio

El nombre del repositorio y el ID de habilidad instalada son intencionalmente diferentes. La especificación de Open Agent Skills requiere que el directorio que contiene SKILL.md coincida con el name en el frontmatter, así que instala el repositorio como animation-logo-skill:

set -euo pipefail

REPO_URL="https://github.com/poudelaman4/brand-motion-agent-skill.git"
SKILL_ID="animation-logo-skill"
INSTALL_ROOT="${HOME}/.agents/skills"
SKILL_DIR="${INSTALL_ROOT}/${SKILL_ID}"

mkdir -p "${INSTALL_ROOT}"

if [ -d "${SKILL_DIR}/.git" ]; then
  git -C "${SKILL_DIR}" pull --ff-only
else
  git clone "${REPO_URL}" "${SKILL_DIR}"
fi

printf 'Installed skill: %s\n' "${SKILL_DIR}"

La ubicación universal de ~/.agents/skills es detectable por Open Code y también es compatible con agentes que siguen la convención de Agent Skills. Claude Code tiene una ubicación nativa adicional descrita a continuación.

2. Instalar dependencias opcionales de Python

Usa un entorno virtual para que la habilidad no modifique la instalación de Python del sistema:

set -euo pipefail
SKILL_DIR="${HOME}/.agents/skills/animation-logo-skill"

cd "${SKILL_DIR}"
python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

Equivalente en PowerShell de Windows:

$SkillDir = "$HOME\.agents\skills\animation-logo-skill"
Set-Location $SkillDir
py -3.10 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

3. Verificar la instalación

set -euo pipefail
SKILL_DIR="${HOME}/.agents/skills/animation-logo-skill"

test -f "${SKILL_DIR}/SKILL.md"
python3 "${SKILL_DIR}/scripts/validate_motion_spec.py" \
  "${SKILL_DIR}/evals/files/valid-motion-spec.json" \
  --check-files

command -v git
command -v python3
command -v ffmpeg || true
command -v ffprobe || true

Si el repositorio público aún no es visible, autentica GitHub o verifica el acceso con:

git ls-remote https://github.com/poudelaman4/brand-motion-agent-skill.git

Carga nativa por agente

Habilidad de Claude Code

Claude Code descubre habilidades personales desde ~/.claude/skills/ y habilidades de proyecto desde .claude/skills/.

Instalación personal:

set -euo pipefail
REPO_URL="https://github.com/poudelaman4/brand-motion-agent-skill.git"
SKILL_DIR="${HOME}/.claude/skills/animation-logo-skill"

mkdir -p "$(dirname "${SKILL_DIR}")"
if [ -d "${SKILL_DIR}/.git" ]; then
  git -C "${SKILL_DIR}" pull --ff-only
else
  git clone "${REPO_URL}" "${SKILL_DIR}"
fi

Reinicia Claude Code y luego invócalo directamente:

/animation-logo-skill

O pregunta de forma natural:

Use the animation-logo-skill to audit this logo before proposing any motion.

Instalación de proyecto:

REPO_URL="https://github.com/poudelaman4/brand-motion-agent-skill.git"
SKILL_DIR="$PWD/.claude/skills/animation-logo-skill"
mkdir -p "$(dirname "${SKILL_DIR}")"
git clone "${REPO_URL}" "${SKILL_DIR}"

Confirma la habilidad de proyecto si todo el equipo debe recibirla.

Habilidad de Open Code

Open Code descubre habilidades desde ~/.config/opencode/skills/, ~/.claude/skills/, ~/.agents/skills/ y equivalentes de proyecto. La instalación universal anterior es suficiente:

SKILL_DIR="${HOME}/.agents/skills/animation-logo-skill"
test -f "${SKILL_DIR}/SKILL.md"

Para una ubicación nativa de Open Code, usa:

REPO_URL="https://github.com/poudelaman4/brand-motion-agent-skill.git"
SKILL_DIR="${HOME}/.config/opencode/skills/animation-logo-skill"
mkdir -p "$(dirname "${SKILL_DIR}")"
git clone "${REPO_URL}" "${SKILL_DIR}"

Reinicia Open Code y pídele que cargue la habilidad por nombre:

Load the animation-logo-skill and create a plan for assets/my-logo.svg.

El descubrimiento local de proyecto de Open Code también admite .agents/skills/animation-logo-skill/ y .opencode/skills/animation-logo-skill/.

Cursor

Las versiones de Cursor difieren en el descubrimiento nativo de Agent Skills. Para una configuración confiable nativa del sistema de archivos, instala la habilidad en el proyecto y agrega una regla de Cursor que apunte a SKILL.md:

set -euo pipefail
REPO_URL="https://github.com/poudelaman4/brand-motion-agent-skill.git"
SKILL_DIR="$PWD/.agents/skills/animation-logo-skill"
RULE_DIR="$PWD/.cursor/rules"

mkdir -p "$(dirname "${SKILL_DIR}")" "${RULE_DIR}"
if [ -d "${SKILL_DIR}/.git" ]; then
  git -C "${SKILL_DIR}" pull --ff-only
else
  git clone "${REPO_URL}" "${SKILL_DIR}"
fi

cat > "${RULE_DIR}/brand-motion-agent-skill.mdc" <<'EOF'
---
description: Load the Brand Motion Agent Skill for logo motion planning, implementation, and QA.
alwaysApply: false
---

Read `.agents/skills/animation-logo-skill/SKILL.md` before handling a logo animation, brand mark, wordmark, emblem, logo reveal, logo loop, or logo-motion QA request. Follow its source-capability gate and task modes.
EOF

Abre la raíz del proyecto en Cursor e inicia un nuevo chat para que la regla se descubra.

Cualquier agente con acceso al sistema de archivos

La habilidad es portátil. Clónala en cualquier lugar y dale al agente la ruta absoluta a SKILL.md:

git clone https://github.com/poudelaman4/brand-motion-agent-skill.git \
  /absolute/path/to/animation-logo-skill

Read /absolute/path/to/animation-logo-skill/SKILL.md and follow it for this logo-animation task.

Inicio rápido: cuatro modos de tarea

1. Modo Auditoría — inspeccionar antes de diseñar

Usa Auditoría cuando la fuente pueda estar aplanada, la geometría de la marca sea desconocida o necesites un informe de riesgo antes de renderizar.

Audit /absolute/path/to/assets/my-logo.png. Determine whether it is vector, layered raster,
flattened raster, or live text. Check alpha, resolution, connected components, possible occlusions,
and whether independent letters or leaves are safe. Do not render yet.

Comando de diagnóstico opcional:

SKILL_DIR="${HOME}/.agents/skills/animation-logo-skill"
python3 "${SKILL_DIR}/scripts/inspect_logo_assets.py" \
  /absolute/path/to/assets/my-logo.png \
  --minimum-area 500 \
  --max-components 30

El inspector es solo de diagnóstico. Los componentes conectados no se garantiza que sean capas semánticas del logotipo.

2. Modo Plan/Storyboard — escribir el brief de movimiento

Usa Plan cuando quieras un concepto, contrato de fotogramas, pivotes, inventario de capas, salidas y puertas de control de calidad antes de la implementación.

Plan a premium 2.4-second logo reveal for /absolute/path/to/assets/my-logo.svg.
Classify the mark, choose one primary motion pattern, record semantic pivots and z-order,
create a motion brief and manifest, specify a final hold and reduced-motion state,
and list the exact source layers and approvals needed before rendering.

Comienza desde las plantillas:

SKILL_DIR="${HOME}/.agents/skills/animation-logo-skill"
cp "${SKILL_DIR}/assets/motion-brief-template.json" ./motion-brief.json
cp "${SKILL_DIR}/assets/motion-manifest-template.json" ./motion-manifest.json

3. Modo Producir — implementar y renderizar

Usa Producir después de que la fuente, el modo de tarea, el tiempo, el fondo, la relación de aspecto y el contrato de salida estén claros.

Produce the approved logo animation from ./motion-manifest.json.
Use the approved source geometry, frame-driven timing, separate background compositions,
and exact checkpoint rendering. Deliver the master, requested variants, poster frame,
motion manifest, render commands, and QA report.

Ejemplo de entrega a Remotion:

npx remotion render MyLogoComposition ./renders/my-logo.mp4 \
  --concurrency=2 --codec=h264 --crf=18

El renderizador no se asume intencionalmente por la habilidad. Si Remotion, After Effects u otro renderizador no está disponible, completa el brief/manifiesto neutral respecto al renderizador e informa el renderizado como bloqueado.

4. Modo Interactivo — definir estados, no una línea de tiempo de una sola toma

Usa Interactivo para estados de logotipo de hover, presión, activo, seleccionado, éxito o reactivo.

Use interactive mode for this logo. Define idle, hover, pressed, active, selected, and reduced-motion
states with 90–180 ms transitions, keyboard/focus parity, no motion-only state indicators,
and a static fallback for unsupported runtimes. Use dotLottie or SVG state-machine output if supported.

Utilidades incluidas

Utilidad	Propósito	Comando típico
inspect_logo_assets.py	Inspeccionar alfa, dimensiones, límites y componentes de diagnóstico	python scripts/inspect_logo_assets.py logo.png
validate_motion_spec.py	Validar tiempo de fotogramas, límites, easing, pivotes y transformaciones finales	python scripts/validate_motion_spec.py motion-manifest.json --check-files
make_checkpoint_contact_sheet.py	Extraer puntos de control de fotogramas exactos en una hoja de revisión	python scripts/make_checkpoint_contact_sheet.py --input render.mp4 --output sheet.jpg --frames 0,30,60,96,119
compare_final_frame.py	Comparar un fotograma de póster decodificado con una referencia aprobada	python scripts/compare_final_frame.py --reference logo.png --encoded render.mp4 --frame 119 --tolerance 0.03
check_skill.py	Autoverificación sin dependencias de este paquete (frontmatter, enlaces de referencia, esquema, fixtures de evaluación, prueba de humo del validador)	python scripts/check_skill.py

Todas las utilidades de Python admiten --help. Las dependencias opcionales se enumeran en requirements.txt. check_skill.py solo necesita la biblioteca estándar, por lo que funciona como una puerta de CI o pre-commit. Ejecútala después de cualquier edición a la habilidad para confirmar que el paquete sigue siendo internamente consistente.

Ejemplo de control de calidad de fotogramas exactos

SKILL_DIR="${HOME}/.agents/skills/animation-logo-skill"

python3 "${SKILL_DIR}/scripts/make_checkpoint_contact_sheet.py" \
  --input ./renders/logo.mp4 \
  --output ./qa/logo-checkpoints.jpg \
  --frames 0,24,48,72,95,96,119 \
  --columns 4

python3 "${SKILL_DIR}/scripts/compare_final_frame.py" \
  --reference ./assets/approved-logo.png \
  --encoded ./renders/logo.mp4 \
  --frame 119 \
  --tolerance 0.03 \
  --allow-opaque

Usa --allow-opaque solo cuando un render de fondo blanco opaco o de color de marca se compare intencionalmente con una referencia transparente. Usa --require-alpha cuando el entregable deba contener un canal alfa real.

Para un fundido cruzado de opacidad entre una capa ráster extraída y geometría vectorial o de marca completa, renderiza fotogramas fijos directos en el inicio, punto medio y fin, luego decodifica los mismos fotogramas del archivo codificado. Un fotograma final limpio y una hoja de contactos limpia no prueban que la transición sea limpia.

npx remotion still MyLogoComposition ./qa/frame-24.png --frame=24
ffmpeg -y -v error -i ./renders/my-logo.mp4 \
  -vf "select=eq(n\\,24)" -vsync 0 -frames:v 1 ./qa/decoded-frame-24.png

Reglas de capacidad de fuente y seguridad de marca

La salvaguarda central de la habilidad es la honestidad de la fuente:

Tipo de fuente	Predeterminado seguro	Movimiento independiente
Vectorial/en capas	Grupos nombrados, máscaras, rutas de recorte, morphs compatibles	Permitido cuando la geometría está expuesta
Ráster en capas	Grupos semánticos aprobados con recortes y pivotes ajustados	Permitido después de la aprobación de capas
Ráster aplanado	Marca completa, agrupado o revelado con máscara	Bloqueado a menos que la reconstrucción esté aprobada
Texto en vivo	Contornear o incrustar glifos aprobados	Bloqueado hasta que la fuente de texto esté aprobada

Nunca trates OCR, segmentación, componentes conectados o vectorización automática como verdad canónica de la marca. Una reconstrucción es un nuevo activo y necesita una nueva puerta de aprobación.

Contrato del manifiesto de movimiento

Un manifiesto registra:

• referencia de fuente, checksum/perfil, lienzo, fps y duración
• concepto principal y modo de tarea
• IDs de capa, roles, archivos fuente, límites normalizados, pivotes y orden z
• intervalos de fotogramas de medio abierto, transformaciones, easing, confianza y estado final
• fotograma de asentamiento, inicio de retención, fotograma de póster, variantes de fondo, salidas y entorno de ejecución objetivo
• comportamiento de movimiento reducido y verificaciones de aceptación

El esquema canónico es schemas/motion-spec.schema.json. Valida antes de renderizar:

python3 scripts/validate_motion_spec.py ./motion-manifest.json --check-files

Una composición de cuatro segundos a 30 fps tiene 120 fotogramas indexados 0–119. Un intervalo de capa es de medio abierto: [start_frame, start_frame + duration_frames). Las capas de estado final deben asentarse antes de que comience la retención.

Entrega a renderizador y MLT/Kdenlive

La habilidad es neutral respecto al renderizador. Puede entregar a:

• Remotion: funciones de fotograma deterministas, capas React, activos locales de staticFile() y salida H.264/MP4.
• SVG/Lottie/dotLottie: grupos vectoriales nombrados, rutas de recorte, temas y máquinas de estado interactivas.
• After Effects: capas de forma, mates, máscaras y fotogramas clave explícitos.
• Marco de automatización de video MLT: secuencias PNG transparentes, ProRes 4444/XQ o un máster sin pérdida aprobado para ensamblaje de línea de tiempo en Kdenlive/MLT.
• FFmpeg: extracción de fotogramas, inspección de flujo, verificaciones de alfa/códec y generación de hojas de contactos.

Mantén una especificación de movimiento y un modelo de tiempo canónicos, pero crea composiciones separadas cuadradas, verticales, horizontales, alfa, blancas, oscuras e interactivas donde el lienzo o el entorno de ejecución lo requiera.

Bucle de investigación y actualización

references/sources.md registra la procedencia de la investigación para Agent Skills, diseño de movimiento, accesibilidad, SVG/Lottie, Remotion, códecs y precedentes de marca. El paquete no obtiene ni aplica silenciosamente tendencias web en tiempo de ejecución.

Para actualizar la habilidad de forma segura:

1. Agrega o revisa una fuente en references/sources.md.
2. Separa la documentación técnica normativa de tutoriales y precedentes de marca.
3. Actualiza assets/motion-tokens.json solo cuando el cambio sea ampliamente útil.
4. Actualiza la referencia de patrón/contexto relevante.
5. Agrega o revisa una evaluación en evals/.
6. Ejecuta la validación de manifiesto/script y compara el comportamiento con habilidad versus línea base.

Estado de evaluación

El conjunto de evaluación de desarrollo (evals/evals.json) tiene 5 casos con 24 aserciones que cubren:

• ráster aplanado con solicitudes inseguras de movimiento independiente
• fantasmas de transición de ráster aplanado y control de calidad de fotogramas directos
• planificación de vector en capas para educación/LMS
• reparación de manifiesto inválido
• requisitos de alfa, movimiento reducido, relación de aspecto y estado final

evals/trigger-queries.json contiene 12 casos de enrutamiento positivos y 8 negativos para verificar que la habilidad se active en trabajo de movimiento de logotipos y se mantenga fuera de tareas no relacionadas.

Una autoverificación se puede ejecutar en cualquier momento:

python scripts/check_skill.py

Resultados registrados (vuelve a ejecutar después de ediciones importantes y actualiza este bloque):

Verificación	Comando	Resultado
Autocomprobación del paquete	python scripts/check_skill.py	PASS — 31 rutas referenciadas, 5 evaluaciones / 24 aserciones, prueba de humo del validador
Manifiesto válido	python scripts/validate_motion_spec.py evals/files/valid-motion-spec.json	PASS
Manifiesto inválido	python scripts/validate_motion_spec.py evals/files/invalid-motion-spec.json	FAIL (esperado) — los 8 errores plantados fueron detectados
Inspección de fuente aplanada	python scripts/inspect_logo_assets.py evals/files/flattened-logo.png	Informa límites alfa + componentes y advierte que no son capas semánticas

La iteración local también obtuvo 10/10 aserciones con la skill frente a 5/10 sin la skill. Trata cada número aquí como un punto de referencia de desarrollo, no como un sustituto de la revisión humana del gusto visual y el ajuste de marca.

Solución de problemas

La skill no aparece

• Confirma que el directorio se llama animation-logo-skill.
• Confirma que SKILL.md está directamente dentro de ese directorio.
• Reinicia el agente después de la primera instalación.
• Para Claude Code, revisa ~/.claude/skills/animation-logo-skill/ o la ruta del proyecto .claude/skills/.
• Para Open Code, revisa ~/.config/opencode/skills/, ~/.agents/skills/ o los equivalentes del proyecto.
• Para Cursor, confirma la regla .cursor/rules/*.mdc y abre la raíz del proyecto.

El clon devuelve 404

Verifica que el repositorio sea público, que la URL sea correcta y que la autenticación de GitHub esté disponible:

git ls-remote https://github.com/poudelaman4/brand-motion-agent-skill.git

Las utilidades de Python fallan

cd "${HOME}/.agents/skills/animation-logo-skill"
. .venv/bin/activate
python -m pip install -r requirements.txt
python scripts/inspect_logo_assets.py --help

Las comprobaciones de FFmpeg fallan

Instala FFmpeg y verifica ambos binarios:

ffmpeg -version
ffprobe -version

Un logo aplanado no puede animarse de forma independiente

Ese es un resultado esperado de BLOCKED, no una razón para fabricar capas. Solicita la fuente vectorial/en capas, aprueba una reconstrucción o usa el respaldo de marca completa/grupo.

Licencia y atribución

Copyright © 2026 Aman Paudel (GitHub: poudelaman4).

Publicado bajo la Licencia MIT.

Los logotipos, fuentes, material de archivo, códecs y materiales de referencia de terceros siguen sujetos a sus respectivas licencias y derechos de autor. Este repositorio no otorga permiso para reutilizar activos de marca de terceros.

Contribuciones

Las contribuciones deben preservar los principios fundamentales del paquete:

• la geometría aprobada es inmutable
• las limitaciones de la fuente son explícitas
• el movimiento es determinista y basado en fotogramas cuando corresponda
• un gesto principal supera a un montón de efectos
• la fidelidad del estado final es medible
• la accesibilidad y el movimiento reducido son parte de la producción
• todas las afirmaciones nuevas se etiquetan como observadas, inferidas, provisionales o bloqueadas

Ejecuta los validadores incluidos e incluye una evaluación o un artefacto de revisión visual de QA para los cambios de comportamiento.