Como criar uma skill no Codex para cortar e converter vídeos com FFmpeg

Para criar uma skill no Codex que roda o FFmpeg, crie uma pasta em $HOME/.agents/skills (ou em .agents/skills dentro do repositório) com um arquivo SKILL.md. No frontmatter entram name e description, cada um em uma linha só. O corpo registra o caminho absoluto do ffmpeg e do ffprobe, define os comandos de corte, conversão e extração de áudio e exige que a saída seja gravada em caminho absoluto.
O padrão vem da skill de Blender no Codex: um programa local, um comando sem interface gráfica e um arquivo de saída com endereço fixo. A diferença é a tarefa. Aqui o assunto é mídia, e os erros também mudam: codecs, caminhos e arquivos sobrescritos sem querer.
O que você precisa antes de criar a skill de FFmpeg no Codex
Você precisa de três coisas: o Codex rodando no CLI ou na extensão de IDE, o FFmpeg e o ffprobe instalados na sua máquina e uma decisão sobre onde a skill vai morar.
O Codex CLI e a extensão de IDE são os lugares onde a invocação explícita com /skills e $ funciona, segundo a documentação de Agent Skills da OpenAI. Se você ainda está chegando agora, vale entender antes como o Codex funciona.
O FFmpeg e o ffprobe precisam estar instalados e você precisa anotar o caminho absoluto de cada binário. Como descobrir esse caminho depende do seu sistema operacional, então use o jeito que você já conhece no seu ambiente.
Por que caminho absoluto? Porque o Codex vai executar o comando a partir de um diretório de trabalho que nem sempre é o que você imagina. Com o endereço completo do binário, a skill não depende do PATH da sessão.
Para saber quais opções o seu binário aceita, rode:
ffmpeg -h full
Esse comando mostra a ajuda completa no terminal, conforme a documentação do ffmpeg. Ele é útil porque cada build do FFmpeg pode vir com recursos diferentes, e o que vale é o que está instalado na sua máquina.

Black Week do Nexus
A formação de IA mais completa do Brasil
- 7 formações · 112 cursos · 26 mil alunos
Por último, escolha o local da skill:
$HOME/.agents/skills: skill de usuário, vale para qualquer repositório em que você trabalhe..agents/skills: skill de repositório. O Codex procura essa pasta em cada diretório, do diretório de trabalho atual até a raiz do repo.
Para uma ferramenta genérica como o FFmpeg, a pasta de usuário costuma fazer mais sentido. Se a skill for específica de um projeto de vídeo, a pasta do repositório deixa tudo junto do código.
Passo a passo: criar a skill de FFmpeg no Codex
A skill é só uma pasta com um SKILL.md e, se você quiser, scripts e referências. Na documentação, a definição é direta: skill = instruções + recursos + scripts opcionais, para o Codex seguir um fluxo de trabalho de forma confiável.
- Crie a pasta da skill no local escolhido. Por exemplo,
$HOME/.agents/skills/ffmpeg-video/. O nome da pasta é seu, mas ela precisa estar dentro de$HOME/.agents/skillsou de.agents/skills.Erro comum deste passo: criar a pasta fora desses caminhos. O Codex lê skills de locais de repositório, de usuário, de admin e de sistema, e uma pasta solta em outro lugar simplesmente não é encontrada.
- Escreva o frontmatter com
nameedescription. O frontmatter é YAML entre---, e adescriptionprecisa dizer o que a skill faz e quando usar.Isso importa por causa da divulgação progressiva do Codex. No começo ele só vê o
name, adescriptione o caminho de cada skill. OSKILL.mdinteiro só é lido quando ele decide usar a skill, então uma description vaga faz a skill ficar esquecida no canto.Erro comum deste passo:
nameoudescriptioncom várias linhas ou longos demais. Segundo a página Create a skill, esse é o erro de validação mais comum na inicialização. Mantenha cada campo em uma linha, curto e objetivo. - Escreva o corpo do
SKILL.mdcom as regras fixas. Aqui entram o caminho absoluto doffmpege doffprobe, a regra de gravar sempre em caminho absoluto e a política de sobrescrita.A política é simples. Por padrão, a skill usa
-n, que faz o FFmpeg encerrar na hora se o arquivo de saída já existir. O-y, que sobrescreve sem perguntar, só entra quando você pedir isso de forma explícita.Veja um exemplo didático de
SKILL.md. Troque os caminhos de exemplo pelos da sua máquina:--- name: ffmpeg-video description: Corta trechos, converte o contêiner e extrai o áudio de vídeos locais usando o FFmpeg. Use quando o usuário pedir para cortar, converter ou tirar o áudio de um arquivo de vídeo. --- # Skill de FFmpeg ## Binários - ffmpeg: /caminho/absoluto/para/ffmpeg - ffprobe: /caminho/absoluto/para/ffprobe Sempre chame os binários por esses caminhos completos. ## Regras obrigatórias - Entrada e saída SEMPRE em caminho absoluto. Se o usuário passar caminho relativo, pergunte o caminho completo antes de rodar. - Use -n por padrão (não sobrescrever). Só use -y se o usuário escrever que pode sobrescrever. - Faça apenas corte, conversão sem recodificar e extração de áudio. Recuse outras operações. - Se o pedido não tiver início e duração (ou instante final) para um corte, pergunte antes de rodar. ## Comandos modelo (ver seção de comandos) ## Depois de rodar - Confira o arquivo com o ffprobe (duração e fluxos). - Informe ao usuário o caminho absoluto do arquivo gerado e a duração medida. - Defina os três comandos modelo. Coloque os comandos no corpo do
SKILL.md, na seção de comandos, para o Codex não improvisar flags. Todos usam apenas opções descritas na documentação do ffmpeg.Corte de trecho. O
-ssantes do-idefine o ponto de início e busca naquela posição do arquivo. O-tlimita a duração gravada, e o-todefine o instante de parada (use um ou outro):/caminho/absoluto/para/ffmpeg -n -ss 60 -i /videos/entrada.mp4 -t 30 -c copy /videos/saida/corte.mp4Conversão sem recodificar. O
-c copyativa a cópia de fluxo: o FFmpeg pula a decodificação e a recodificação e só faz demux e mux. É como trocar a caixa sem mexer no conteúdo:/caminho/absoluto/para/ffmpeg -n -i /videos/entrada.mkv -c copy /videos/saida/convertido.mp4Extração de áudio. O
-vndeixa os fluxos de vídeo fora da saída. Sem-c, a escolha do codec fica com o padrão do FFmpeg para a extensão que você pedir:/caminho/absoluto/para/ffmpeg -n -i /videos/entrada.mp4 -vn /videos/saida/audio.EXTENSAOTroque
EXTENSAOpelo formato de áudio que você quer. A skill propositalmente não fixa nomes de codec, porque o que está disponível depende do build instalado. Na dúvida, confira comffmpeg -h full.Erro comum deste passo: usar
-ssna entrada junto com cópia de fluxo e esperar um corte cravado no segundo. A página Seeking da FFmpeg Wiki explica que, nesse caso, o FFmpeg só consegue dividir o vídeo em keyframes (i-frames). Além disso, na maioria dos formatos a busca com-ssna entrada não é exata: ele vai para o ponto de busca mais próximo antes da posição pedida.Então escreva no
SKILL.mduma regra para a skill avisar isso:- Ao cortar com -c copy, avise o usuário: o corte acompanha os keyframes e pode começar antes do ponto pedido. - Alternativa: gere o esqueleto com
$skill-creator. O Codex já vem com uma skill embutida que cria skills, chamada com$skill-creatorno CLI ou na extensão de IDE. Ela pergunta o que a skill faz, quando deve ser acionada e se o tipo é só instrução (o padrão) ou com script.Para este caso, só instrução resolve. Depois que o esqueleto estiver pronto, cole os caminhos absolutos, as regras de sobrescrita e os comandos modelo dos passos anteriores.
- Opcional: bloqueie a invocação implícita. Por padrão, o Codex pode acionar a skill sozinho quando acha que ela serve. Se você prefere que uma skill que mexe em arquivos de vídeo só rode quando chamada, coloque esta chave no arquivo
agents/openai.yaml:allow_implicit_invocation: falseO padrão é
true. Comfalse, o Codex não chama a skill por conta própria, mas a invocação explícita com$continua funcionando. - Invoque a skill com um pedido que já declare os limites. Rode
/skillspara ver a lista ou digite$para mencionar a skill pelo nome. Um pedido bom já traz entrada, início, duração, saída e a regra de sobrescrita:

VPS Hostinger para seu sistema
10% OFF extraVPS com SSD NVMe e backups semanais. O cupom MATHEUSHORADECODAR é aplicado automaticamente pelo link.
Ver planos com 10% OFF →$ffmpeg-video corte /videos/entrada.mp4 a partir do segundo 60, com 30 segundos de duração, e grave em /videos/saida/corte.mp4. Não sobrescreva se o arquivo já existir.
Erro comum deste passo: editar o SKILL.md e a mudança não aparecer. O Codex costuma perceber alterações sozinho, mas, se a atualização não surgir, reinicie o Codex. Se aparecer erro de validação na inicialização, corrija o frontmatter e reinicie de novo.
Como conferir se o vídeo cortado ou convertido saiu certo
A conferência é feita com o ffprobe, que lê informações dos fluxos multimídia e mostra tudo num formato legível por pessoas e por máquinas. Inclua essa checagem no SKILL.md para ela rodar sempre depois do FFmpeg.
- Meça a duração do arquivo gerado. O comando da documentação do ffprobe mostra a duração do contêiner como um número puro:
/caminho/absoluto/para/ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 /videos/saida/corte.mp4 - Compare com o que você pediu. Se pediu 30 segundos, o valor deve ficar próximo disso. Num corte com
-c copy, uma diferença pode vir dos keyframes, então ela não indica necessariamente um erro. - Confira os fluxos e o contêiner. O
-show_streamslista os fluxos do arquivo. Na extração de áudio, ele serve para confirmar que não sobrou nenhum fluxo de vídeo. O-show_formatmostra as informações do contêiner na seção FORMAT:/caminho/absoluto/para/ffprobe -v error -show_streams -show_format /videos/saida/audio.EXTENSAO - Use JSON quando a skill precisar ler o resultado. O
-ofaceitadefault,compact,csv,flat,ini,jsonexml. Com-of json, o Codex lê a saída de forma estruturada e consegue informar o resultado sem adivinhar:
/caminho/absoluto/para/ffprobe -v error -show_streams -show_format -of json /videos/saida/corte.mp4
No fim, a skill deve responder com o caminho absoluto do arquivo gerado e a duração medida. Se ela disser só "pronto", você não sabe onde o arquivo foi parar nem se ele está correto.
Que limites declarar no pedido para a skill não estragar seus arquivos
Os limites existem para evitar três estragos concretos: arquivo apagado, corte fora do ponto e saída na pasta errada. Coloque essas regras no SKILL.md e repita as principais no pedido:
- Sem sobrescrita por padrão (
-n). Se o arquivo de saída já existir, o FFmpeg encerra na hora. Isso evita perder um vídeo bom por causa de um nome repetido. -ysó com pedido explícito. Sobrescrever sem perguntar é útil em reprocessamento, mas precisa partir de você, nunca de uma suposição da IA.- Duração máxima com
-tou ponto final com-to. Sem limite, um corte pode ir até o fim do arquivo. Declarar a duração deixa o resultado previsível e fácil de conferir com o ffprobe. - Caminho absoluto de entrada e de saída. Caminho relativo depende do diretório de trabalho, e é assim que o arquivo vai parar numa pasta que você nem lembrava que existia.
- Aviso de corte impreciso na cópia de fluxo. Com
-c copy, o corte acompanha os keyframes. Avisar antes evita que você entregue um trecho que começa antes do ponto combinado. - Escopo restrito a corte, conversão e extração de áudio. Uma skill que faz poucas coisas é mais fácil de auditar. Se o pedido fugir disso, a skill deve recusar em vez de improvisar flags.
Se a saída precisar ir para fora da pasta do projeto, vale consultar antes como funciona o sandbox do Codex no seu sistema, porque não está confirmado neste texto se ele pede aprovação para rodar binários fora do projeto ou gravar fora do workspace.
Próximo passo: adaptar o padrão para outros programas de linha de comando
Antes de usar a skill em arquivos importantes, faça uma cópia de um vídeo qualquer e rode os três comandos nela: corte, conversão e extração de áudio. Confira cada saída com o ffprobe e tente gravar duas vezes no mesmo caminho para ver o -n encerrar o FFmpeg em vez de sobrescrever.
Se tudo se comportar como o SKILL.md descreve, a skill está pronta para o dia a dia.
Depois disso, a mesma estrutura serve para outros programas: caminho absoluto do binário, comando sem interface gráfica e saída com endereço completo. Foi o que a skill de Blender fez com 3D e o que esta fez com vídeo, e o próximo programa de linha de comando que você usa toda semana provavelmente cabe no mesmo molde.
Perguntas frequentes
Posso manter a mesma skill de FFmpeg tanto em $HOME/.agents/skills quanto em .agents/skills do repositório?
Sim, o Codex lê skills de locais de usuário e de repositório ao mesmo tempo. Só que aí você passa a manter duas cópias do SKILL.md, então escolha um lugar só se não tiver motivo real para duplicar.
Fontes consultadas
Consulta em .
Encontre outros guias no YouTube da Hora de Codar. Se quiser aprofundar o contexto, veja Curso Codex Gratuito: O Único Tutorial que Você PRECISA (Com Skills e Projeto).
Formações
Formação Vibe Coding
Do Prompt ao Produto: Crie Software Real com IA
- 474 aulas
- 20 projetos
- 39h 30min
Blog | Mais populares
Codex CLI: como instalar, autenticar e rodar o Codex no terminal
Codex CLI: veja como instalar com npm, autenticar via ChatGPT e rodar o agente de código da OpenAI direto no terminal, com sandbox seguro por padrão.
Quanto custa o Codex? Planos, preços e limites de uso
Codex preço: veja quanto custa o Codex em cada plano do ChatGPT, de US$ 8 no Go até US$ 200 no Pro 20x, e como funcionam os créditos e limites de uso.
Como usar o Codex no ChatGPT: o passo a passo para rodar tarefas sem abrir o terminal
Veja como usar o Codex no ChatGPT: onde acessar pelo navegador, app e celular, como conectar o GitHub e rodar sua primeira tarefa sem abrir o terminal.
