brand-motion-agent-skill

Brand Motion Agent Skill (logo-motion-guardrail)

Uma skill de agente para animação de logotipos com segurança de marca. Ela ensina um agente de codificação habilitado para sistema de arquivos (Claude Code, Open Code, Cursor e outros) a animar um logotipo já aprovado sem redesenhar: preservar a geometria canônica e o lockup final, manter o movimento contido e adequado à marca, e ser honesto sobre o que a fonte pode ou não suportar. Ela produz briefs de movimento e manifestos neutros em relação ao renderizador e faz a entrega para Remotion, SVG, Lottie/dotLottie, After Effects, FFmpeg ou MLT/Kdenlive.

Mantenedor e criador: Aman Paudel — GitHub: poudelaman4

Repositório: https://github.com/poudelaman4/brand-motion-agent-skill ID da skill instalada: animation-logo-skill · Runtime: local, habilitado para sistema de arquivos, determinístico, neutro em relação ao renderizador

Palavras-chave de descoberta

brand-safe logo animation agent skill · Claude Code skill · Open Agent Skills schema · MLT video automation framework · automação de revelação de logotipo · proteção de identidade de marca · validação de geometria canônica · animação de logotipo SVG · revelação de logotipo Lottie · máquina de estados dotLottie · animação de logotipo Remotion · vídeo de logotipo transparente · animação de logotipo com fundo branco · QA de design de movimento com IA

Este README usa cabeçalhos explícitos, tabelas, blocos de código, caminhos de instalação, modos de tarefa e terminologia para que indexadores de IA, scrapers de LLM e SEO do Google possam identificar o repositório com precisão sem depender de contexto oculto.

O que é isto

Um pacote de skill de agente reutilizável, não um editor de vídeo ou renderizador. Ele ensina um agente a:

• Auditar fontes de logotipo vetoriais, raster em camadas, raster achatado e texto vivo.
• Proteger geometria aprovada, wordmarks, contadores, espaço livre, cores e comportamento de alpha.
• Classificar o logotipo, o movimento narrativo, o contexto, o tempo de execução, o fundo e a plataforma.
• Escolher um padrão contido para identidades botânicas, geométricas, monogramas, wordmarks, selos, educacionais, premium, lúdicas, de bem-estar ou de tecnologia.
• Criar um brief de movimento, um manifesto preciso por quadro, um estado de movimento reduzido e um plano de QA.
• Produzir entregas neutras em relação ao renderizador ou implementar um renderizador suportado quando disponível.
• Inspecionar quadros codificados, construir folhas de checkpoint exatas e comparar estados finais com tolerâncias documentadas.
• Validar transições de raster extraídas em stills diretos de início/meio/fim e na saída decodificada antes da entrega.

Vídeo generativo nunca é permitido redesenhar silenciosamente um logotipo aprovado. Quando uma fonte achatada não contém camadas semânticas, a skill relata a limitação e oferece um fallback agrupado ou de marca inteira em vez de inventar pixels ocultos.

Estrutura do repositório

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

Pré-requisitos

Necessário para o formato central da skill:

• Git
• Um agente de codificação de IA habilitado para sistema de arquivos
• Python 3.10+ para os utilitários incluídos

Recomendado para renderização de produção e QA:

• FFmpeg e FFprobe
• Node.js e um renderizador como Remotion
• Um editor SVG ou fonte vetorial para movimento independente do logotipo
• Kdenlive/MLT para montagem de linha do tempo editorial
• Um alvo de teste em navegador/runtime para saída SVG, Lottie ou dotLottie

O agente ainda pode operar no modo Plano ou Auditoria quando um renderizador, FFmpeg ou camadas de fonte estiverem indisponíveis. Ele deve marcar renderização ou movimento independente de camadas como BLOCKED em vez de adivinhar.

Instalação

1. Clonar o repositório

O nome do repositório e o ID da skill instalada são intencionalmente diferentes. A especificação Open Agent Skills exige que o diretório contendo SKILL.md corresponda ao name no frontmatter, então instale o repositório 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}"

O local universal ~/.agents/skills é detectável pelo Open Code e também é compatível com agentes que seguem a convenção Agent Skills. O Claude Code tem um local nativo adicional descrito abaixo.

2. Instalar dependências Python opcionais

Use um ambiente virtual para que a skill não modifique a instalação Python do 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 no Windows PowerShell:

$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 a instalação

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

Se o repositório público ainda não estiver visível, autentique o GitHub ou verifique o acesso com:

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

Carregamento nativo pelo agente

Skill do Claude Code

O Claude Code descobre skills pessoais em ~/.claude/skills/ e skills de projeto em .claude/skills/.

Instalação pessoal:

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

Reinicie o Claude Code e invoque diretamente:

/animation-logo-skill

Ou pergunte naturalmente:

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

Instalação no projeto:

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}"

Faça commit da skill do projeto se todo o time deve recebê-la.

Skill do Open Code

O Open Code descobre skills em ~/.config/opencode/skills/, ~/.claude/skills/, ~/.agents/skills/ e equivalentes de projeto. A instalação universal acima é suficiente:

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

Para um local nativo do Open Code, use:

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}"

Reinicie o Open Code e peça para carregar a skill pelo nome:

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

A descoberta local de projeto do Open Code também suporta .agents/skills/animation-logo-skill/ e .opencode/skills/animation-logo-skill/.

Cursor

Versões do Cursor diferem na descoberta nativa de Agent Skills. Para uma configuração confiável de sistema de arquivos, instale a skill no projeto e adicione uma regra do Cursor que aponte para 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

Abra a raiz do projeto no Cursor e inicie um novo chat para que a regra seja descoberta.

Qualquer agente habilitado para sistema de arquivos

A skill é portátil. Clone-a em qualquer lugar e forneça ao agente o caminho absoluto para 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.

Início rápido: quatro modos de tarefa

1. Modo Auditoria — inspecionar antes de projetar

Use Auditoria quando a fonte pode estar achatada, a geometria da marca é desconhecida ou você precisa de um relatório de risco antes da renderização.

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

O inspetor é apenas diagnóstico. Componentes conectados não são garantidos como camadas semânticas de logotipo.

2. Modo Plano/storyboard — escrever o brief de movimento

Use Plano quando você quer um conceito, contrato de quadros, pivôs, inventário de camadas, saídas e portões de QA antes da implementação.

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.

Comece pelos modelos:

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 Produção — implementar e renderizar

Use Produção depois que a fonte, o modo de tarefa, o tempo, o fundo, a proporção e o contrato de saída estiverem 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.

Exemplo de entrega Remotion:

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

O renderizador não é assumido pela skill intencionalmente. Se Remotion, After Effects ou outro renderizador estiver indisponível, complete o brief/manifesto neutro em relação ao renderizador e relate a renderização como bloqueada.

4. Modo Interativo — definir estados, não uma linha do tempo única

Use Interativo para estados de logotipo de hover, pressionar, ativo, selecionado, sucesso ou reativo.

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.

Utilitários incluídos

Utilitário	Finalidade	Comando típico
inspect_logo_assets.py	Inspecionar alpha, dimensões, limites e componentes de diagnóstico	python scripts/inspect_logo_assets.py logo.png
validate_motion_spec.py	Validar tempo de quadros, limites, easing, pivôs e transformações finais	python scripts/validate_motion_spec.py motion-manifest.json --check-files
make_checkpoint_contact_sheet.py	Extrair checkpoints exatos de quadros em uma folha de revisão	python scripts/make_checkpoint_contact_sheet.py --input render.mp4 --output sheet.jpg --frames 0,30,60,96,119
compare_final_frame.py	Comparar um quadro pôster decodificado com uma referência aprovada	python scripts/compare_final_frame.py --reference logo.png --encoded render.mp4 --frame 119 --tolerance 0.03
check_skill.py	Autoverificação sem dependências deste pacote (frontmatter, links de referência, schema, fixtures de avaliação, teste de fumaça do validador)	python scripts/check_skill.py

Todos os utilitários Python suportam --help. Dependências opcionais estão listadas em requirements.txt. check_skill.py precisa apenas da biblioteca padrão, então funciona como um portão de CI ou pre-commit. Execute-o após qualquer edição na skill para confirmar que o pacote ainda está internamente consistente.

Exemplo de QA de quadro exato

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

Use --allow-opaque somente quando uma renderização com fundo branco opaco ou cor da marca está sendo intencionalmente comparada a uma referência transparente. Use --require-alpha quando a entrega deve conter um canal alpha real.

Para um crossfade de opacidade entre uma camada raster extraída e geometria vetorial ou de marca inteira, renderize stills diretos no início, meio e fim, depois decodifique os mesmos quadros do arquivo codificado. Um quadro final limpo e uma folha de contato limpa não provam que a transição está limpa.

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

Regras de capacidade da fonte e segurança da marca

O guarda-corpo central da skill é a honestidade da fonte:

Tipo de fonte	Padrão seguro	Movimento independente
Vetorial/em camadas	Grupos nomeados, máscaras, caminhos de trim, morphs compatíveis	Permitido quando a geometria está exposta
Raster em camadas	Grupos semânticos aprovados com cortes e pivôs apertados	Permitido após aprovação das camadas
Raster achatado	Revelação de marca inteira, agrupada ou com máscara	Bloqueado a menos que a reconstrução seja aprovada
Texto vivo	Contornar ou incorporar glifos aprovados	Bloqueado até que a fonte/texto seja aprovado

Nunca trate OCR, segmentação, componentes conectados ou vetorização automática como verdade canônica da marca. Uma reconstrução é um novo ativo e precisa de um novo portão de aprovação.

Contrato do manifesto de movimento

Um manifesto registra:

• referência da fonte, checksum/perfil, canvas, fps e duração
• conceito primário e modo de tarefa
• IDs de camada, papéis, arquivos de origem, limites normalizados, pivôs e ordem z
• intervalos de quadros half-open, transformações, easing, confiança e status de estado final
• quadro de assentamento, início de hold, quadro pôster, variantes de fundo, saídas e runtime alvo
• comportamento de movimento reduzido e verificações de aceitação

O schema canônico é schemas/motion-spec.schema.json. Valide antes de renderizar:

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

Uma composição de quatro segundos a 30 fps tem 120 quadros indexados 0–119. Um intervalo de camada é half-open: [start_frame, start_frame + duration_frames). Camadas de estado final devem assentar antes do hold começar.

Entrega para renderizador e MLT/Kdenlive

A skill é neutra em relação ao renderizador. Ela pode entregar para:

• Remotion: funções de quadro determinísticas, camadas React, ativos locais staticFile() e saída H.264/MP4.
• SVG/Lottie/dotLottie: grupos vetoriais nomeados, caminhos de trim, temas e máquinas de estado interativas.
• After Effects: camadas de forma, mattes, máscaras e keyframes explícitos.
• Estrutura de automação de vídeo MLT: sequências PNG transparentes, ProRes 4444/XQ ou um master lossless aprovado para montagem de linha do tempo no Kdenlive/MLT.
• FFmpeg: extração de quadros, inspeção de stream, verificações de alpha/codec e geração de folhas de contato.

Mantenha uma especificação de movimento e modelo de tempo canônicos, mas crie composições separadas quadradas, verticais, horizontais, alpha, brancas, escuras e interativas onde o canvas ou runtime exigir.

Loop de pesquisa e atualização

references/sources.md registra a proveniência da pesquisa para Agent Skills, design de movimento, acessibilidade, SVG/Lottie, Remotion, codecs e precedentes de marca. O pacote não busca ou aplica tendências da web silenciosamente em runtime.

Para atualizar a skill com segurança:

1. Adicione ou revise uma fonte em references/sources.md.
2. Separe documentação técnica normativa de tutoriais e precedentes de marca.
3. Atualize assets/motion-tokens.json somente quando a mudança for amplamente útil.
4. Atualize a referência de padrão/contexto relevante.
5. Adicione ou revise uma avaliação em evals/.
6. Execute validação de manifesto/script e compare o comportamento com-skill versus linha de base.

Status de avaliação

O conjunto de avaliação de desenvolvimento (evals/evals.json) tem 5 casos com 24 asserções cobrindo:

• raster achatado com solicitações inseguras de movimento independente
• fantasmas de transição em raster achatado e QA de quadro direto
• planejamento de vetor em camadas para educação/LMS
• reparo de manifesto inválido
• requisitos de alpha, movimento reduzido, proporção e estado final

evals/trigger-queries.json contém 12 casos de roteamento positivos e 8 negativos para verificar que a skill dispara em trabalho de movimento de logotipo e fica fora de tarefas não relacionadas.

Uma autoverificação pode ser executada a qualquer momento:

python scripts/check_skill.py

Resultados registrados (re-executar após edições importantes e atualizar este bloco):

Verificação	Comando	Resultado
Autoverificação do pacote	python scripts/check_skill.py	PASSOU — 31 caminhos referenciados, 5 avaliações / 24 asserções, teste de fumaça do validador
Manifesto válido	python scripts/validate_motion_spec.py evals/files/valid-motion-spec.json	PASSOU
Manifesto inválido	python scripts/validate_motion_spec.py evals/files/invalid-motion-spec.json	FALHOU (esperado) — todos os 8 erros plantados foram capturados
Inspeção da fonte achatada	python scripts/inspect_logo_assets.py evals/files/flattened-logo.png	Relata limites alfa + componentes e avisa que não são camadas semânticas

A iteração local também classificou 10/10 asserções com a skill versus 5/10 sem a skill. Trate cada número aqui como um benchmark de desenvolvimento, não um substituto para revisão humana do gosto visual e adequação à marca.

Solução de problemas

A skill não aparece

• Confirme que o diretório está nomeado como animation-logo-skill.
• Confirme que SKILL.md está diretamente dentro desse diretório.
• Reinicie o agente após a primeira instalação.
• Para Claude Code, verifique ~/.claude/skills/animation-logo-skill/ ou o caminho do projeto .claude/skills/.
• Para Open Code, verifique ~/.config/opencode/skills/, ~/.agents/skills/ ou os equivalentes do projeto.
• Para Cursor, confirme a regra .cursor/rules/*.mdc e abra a raiz do projeto.

O clone retorna 404

Verifique se o repositório é público, se a URL está correta e se a autenticação do GitHub está disponível:

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

Utilitários Python falham

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

Verificações do FFmpeg falham

Instale o FFmpeg e verifique ambos os binários:

ffmpeg -version
ffprobe -version

Um logo achatado não pode animar de forma independente

Esse é um resultado esperado de BLOCKED, não um motivo para fabricar camadas. Solicite a fonte vetorial/em camadas, aprove uma reconstrução ou use o fallback de marca inteira/grupo.

Licença e atribuição

Copyright © 2026 Aman Paudel (GitHub: poudelaman4).

Lançado sob a Licença MIT.

Logos, fontes, filmagens, codecs e materiais de referência de terceiros permanecem sujeitos às suas respectivas licenças e direitos autorais. Este repositório não concede permissão para reutilizar ativos de marca de terceiros.

Contribuindo

As contribuições devem preservar os princípios centrais do pacote:

• a geometria aprovada é imutável
• as limitações da fonte são explícitas
• o movimento é determinístico e orientado por quadros quando aplicável
• um gesto primário supera uma pilha de efeitos
• a fidelidade do estado final é mensurável
• acessibilidade e movimento reduzido fazem parte da produção
• todas as novas afirmações são rotuladas como observadas, inferidas, provisórias ou bloqueadas

Execute os validadores incluídos e inclua uma avaliação ou artefato de revisão visual de QA para mudanças de comportamento.