Communitygithub.com

brag-more

Transforme o README do GitHub do seu projeto em uma página de apresentação polida — com um hero SVG animado, cards de destaque, vídeo de demonstração, badges honestos e muito mais.

O que é brag-more?

O brag-more é uma skill para agentes de IA (como Claude Code, Cursor ou Codex) que transforma o README de um projeto no GitHub em uma página de apresentação profissional e envolvente. Ele analisa profundamente o código, identidade visual e documentação existente do projeto, e gera um README completo com hero SVG animado usando as cores e fontes reais do projeto, uma seção de demonstração em destaque, cards de feature com visuais, um quickstart testado e badges justificados por evidências. A skill segue uma metodologia rigorosa: inspeciona o projeto (manifestos, workflows, assets visuais), planeja a estrutura do README, constrói os assets (animação SVG, preview social, badges) e verifica a precisão de cada afirmação. Suporta múltiplos estilos (clean, bold, minimal, showcase) e respeita temas claro e escuro. Se não existir um vídeo de demonstração, o brag-more pode criá-lo usando a skill /brag ou seu próprio workflow de vídeo. O resultado é um README verdadeiro, executável, escaneável e visualmente atraente, que faz qualquer repositório parecer um projeto open-source bem cuidado.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/omer-chandna/brag-more/tree/HEAD/skills/brag-more

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Prévia

Do README da skill

brag-more preview

Documentação

/brag-more

Você construiu. Agora faça o repositório se gabar também. O README é a primeira coisa que qualquer um vê no GitHub; transforme-o em uma página de apresentação que venda o projeto em cinco segundos e leve um estranho do zero a executá-lo em um minuto.

Seja qual for o projeto, o resultado deve parecer um README de um projeto open-source bem cuidado: confiante, escaneável, visual e verdadeiro. Nada na página que não mereça seu lugar.

Uso: /brag-more [opções]. Opções (flags ou linguagem natural):

OpçãoPadrão
--style clean|bold|minimal|showcaseinferido do projeto (veja Estilos)
--previewdesligado: escreve README.md no lugar. Com ele, escreve apenas em brag-output/repo/ e deixa README.md intacto
--no-bannerbanner ligado
--no-videodesligado: se o projeto não tem vídeo de demonstração, crie um primeiro (veja O vídeo)
--no-demodemonstração ligada quando há algo para mostrar

Os arquivos de trabalho vão em brag-output/repo/ (com timestamp brag-output-YYYY-MM-DD-HHmmss/repo/ se brag-output/ já existir e não for desta execução). Os assets referenciados pelo README vão no repositório, em .github/readme/, para acompanhá-lo.

1. Inspecionar

Leia o projeto, não apenas o README antigo:

  • O README existente, cada linha. É a escrita do usuário. Mantenha tudo que for verdadeiro e útil (passos de instalação, tabelas de configuração, créditos, notas de licença, links de patrocinadores, agradecimentos); reformate, não jogue fora.
  • Identidade: cores e fontes exatas da marca a partir das folhas de estilo ou configuração de tema, o logotipo ou favicon, qualquer imagem hero ou OG existente.
  • O que é: manifestos de pacotes (package.json, pyproject.toml, Cargo.toml, go.mod, …) para o nome, descrição, versão, licença, binários e scripts; o ponto de entrada e as principais rotas ou comandos para as funcionalidades reais.
  • Como executá-lo: os comandos reais de instalação e inicialização a partir dos scripts do manifesto, Makefile, justfile, Dockerfile ou workflow de CI. Anote as versões de runtime que o projeto fixa.
  • Sinais para badges: LICENSE, .github/workflows/*, se o pacote está publicado (npm, PyPI, crates.io — verifique o nome do manifesto e a flag private), o remote git (git remote get-url origin) para owner/repo.
  • Saída de demonstração existente: se brag-output*/brag.mp4 e brag.jpg existirem, são o melhor material de demonstração na máquina. Use o mais novo. Se não houver, você criará no próximo passo.

Pule saída de build, arquivos de lock, .git/, arquivos de ambiente e segredos (.env, .env.*), material de chaves e credenciais, e qualquer coisa que .gitignore exclua por esses motivos.

Antes de escrever, responda: O que é (uma frase que um estranho entenda)? Para quem é? Qual é a única coisa que faz melhor que a alternativa? Qual é o gancho visual — a captura de tela, GIF ou banner que faz alguém parar de rolar? Quais são as 3–5 funcionalidades reais? Qual é o caminho mais curto do clone à execução?

O README é público. Nunca carregue segredos, tokens, hostnames internos, nomes reais de clientes ou usuários, endereços de e-mail ou outros dados pessoais nele ou em suas imagens. Se uma captura de tela mostrar tais dados, substitua por substitutos ficcionais plausíveis.

O vídeo (antes do plano, quando não existe um)

O melhor demo do README é o vídeo de lançamento do projeto, então o brag-more o cria quando está faltando. Pule esta etapa quando --no-demo ou --no-video estiver definido, ou quando brag-output*/brag.mp4 já existir.

  1. Se a skill /brag estiver instalada (verifique a lista de skills), execute-a para este projeto através da ferramenta Skill, passando quaisquer desejos de --tone ou formato. Diga ao usuário em uma linha: "Ainda não há vídeo de lançamento, então estou criando um com /brag primeiro."
  2. Caso contrário, leia <skill-dir>/video.md (o workflow de vídeo enxuto incluído aqui, do brag-slim) e siga-o. Ele precisa apenas de ferramentas já na máquina.
  3. Quando terminar, o vídeo, pôster e cópia de compartilhamento estarão em brag-output/. Continue com o README usando-os como demonstração.

Se a criação do vídeo falhar ou o usuário não quiser esperar, continue sem ele e use os fallbacks sob Demonstração.

2. Planejar

Escreva brag-output/repo/readme-plan.md: a frase de efeito, o estilo escolhido, a ordem das seções, quais visuais você criará e o que cada um mostra, quais badges são justificados (e a evidência para cada um), e o que você está mantendo do README antigo.

Forma: uma forma inicial, não um template. Elimine qualquer seção que seria vazia ou de preenchimento.

  1. Hero — o hero SVG animado (veja Construir), em seguida centralizado: a frase de efeito, uma linha curta de badges e uma linha de navegação com links (Demo · Instalar · Docs · …).
  2. Demonstração — o produto em uso, logo abaixo do hero, emoldurado: o loop do vídeo de demonstração, um GIF da UI real ou uma gravação de terminal. Um visual, grande.
  3. Porquê — 2–4 frases: o que faz pelo usuário e o que o diferencia, nas próprias palavras do projeto. Para uma ferramenta de desenvolvedor, um bloco de código de 3–5 linhas que é o argumento de venda vence um parágrafo (bun run index.tsx # TS e JSX prontos para uso).
  4. Vitrine de funcionalidades — 3–6 funcionalidades reais, cada uma com seu próprio pequeno visual: uma captura de tela recortada da UI real, um GIF de terminal por comando ou um trecho de código e sua saída. Disponha os visuais como cards lado a lado (veja Construir). Funcionalidades apenas de texto recebem uma introdução em negrito e uma linha.
  5. Início rápido — copiável e colável, em ordem, cada comando verificado contra o projeto. Pré-requisitos primeiro.
  6. Uso — um ou dois exemplos reais: um comando e sua saída, um trecho de código ou um bloco de configuração.
  7. Como funciona — opcional. Um parágrafo curto ou um diagrama Mermaid quando a arquitetura é a parte interessante.
  8. Todo o resto do README antigo — configuração, FAQ, roadmap, contribuição, créditos — organizado, dobrado em <details> quando longo.
  9. Rodapé — linha de licença, mais a faixa de arte de encerramento (veja Construir).

Leis do README

  • Verdadeiro. Cada afirmação, número, funcionalidade e badge deve ser respaldado pelo projeto. Nenhuma estrela, download, benchmark, depoimento ou logotipo "usado por" inventado. Um badge aparece apenas se o que ele aponta existe (um pacote publicado, um workflow real, um arquivo de licença).
  • Executável. Cada comando em Início rápido e Uso existe no projeto como escrito. Se puder executá-lo com segurança (instalar, build, --help, testes), faça. Se um passo precisar de segredos ou um serviço pago, diga isso claramente em vez de esconder.
  • Teste de cinco segundos. Alguém que chega ao repositório a partir de um tweet sabe o que é, vê funcionando e encontra o comando de instalação sem rolar além da primeira tela.
  • Mostre a coisa. A demonstração mostra o produto real em uso, não uma animação de logotipo ou arte abstrata. Reutilize UI real, CSS real, texto real.
  • Diga o que o repositório é. Se o repositório é o site, landing page ou demonstração para um produto, diga isso na frase de efeito; não implique que as pessoas podem baixar um aplicativo ou instalar um pacote que o repositório não distribui.
  • Específico. Deve parecer escrito para este projeto exato. "Extremamente rápido", "perfeito", "de última geração", "otimize seu fluxo de trabalho" são proibidos a menos que o projeto os mereça mensuravelmente.
  • Escaneável. Parágrafos curtos, cabeçalhos que dizem algo, uma ideia por marcador. Emoji em cabeçalhos apenas se a própria voz do projeto os usa, e então com moderação (o estilo showcase é a exceção: um emoji por cabeçalho de seção, por design).
  • Ambos os temas. Leitores do GitHub usam modo claro e escuro. Cada imagem fica correta em #ffffff e em #0d1117: PNGs transparentes com borda visível, ou <picture> com uma fonte prefers-color-scheme por tema.
  • Cabe na coluna. A coluna do README tem cerca de 830px de largura no desktop e muito menos em celulares. O texto do banner permanece legível quando dimensionado para largura de celular; tabelas têm poucas colunas; nenhum layout HTML bruto largo que quebre em dispositivos móveis.
  • Todo link resolve. Links relativos apontam para arquivos que existem; âncoras correspondem a cabeçalhos reais.

Estilos

EstiloSensaçãoUse quando
cleanHero animado com movimento contido, demonstração emoldurada, cards organizadosA maioria dos projetos; o padrão
boldHero sem margens em cores da marca com um momento animado maior, frase de efeito impactante, demonstração em destaqueAplicativos de consumo, projetos lúdicos, lançamentos
minimalPequeno logotipo animado + nome + frase de efeito, seções simplesBibliotecas, CLIs, infraestrutura, ferramentas sérias
showcaseO README técnico denso com seções de emoji (pense em um hackathon vencedor ou projeto de pesquisa): uma captura de tela real do produto no topo, uma linha de prêmio ou status, em seguida uma seção por tópico liderada por emojiHackathon, pesquisa, ML, dados ou projetos de ciência; qualquer coisa com profundidade real para mostrar. Escolha-o quando o usuário pedir "algo como Find My Shark" ou um README detalhado no estilo de documentação

A receita showcase

Modelado no README do Find-My-Shark do proprietário. Mantenha o que o faz funcionar e corrija o que não funciona:

  • Título com um emoji e a linha de conquista abaixo ("NASA Space Apps 2025, Vencedor Impacto Galáctico"), apenas se o projeto realmente a conquistou. Pergunte ou leia do README antigo; nunca invente uma.
  • Uma captura de tela real ou o GIF de demonstração diretamente abaixo do título, emoldurado (veja Demonstração, emoldurado). Mantenha o hero animado apenas se ele adicionar algo; aqui o produto real é a estrela.
  • Uma frase de 2-3 linhas e a linha "por que importa", em seguida seções cada uma liderada por um emoji: Funcionalidades, Região/Escopo ou Entradas, Fontes de Dados (tabela), Como funciona ou Modelo Matemático, Início Rápido (instalação, uso básico, uso de API), Estrutura do Projeto (árvore anotada), Configuração (a configuração real), Arquivos de Saída, Opções de Linha de Comando, Antecedentes, Extensões Futuras, Testes, Logging, slogan de encerramento.
  • Inclua apenas seções para as quais o projeto tem conteúdo real. A profundidade no nível de hackathon é o objetivo, então mantenha os detalhes: parâmetros, fórmulas, limites, nomes de conjuntos de dados e a árvore do projeto.
  • Corrija os deslizes usuais: use a URL de clone real (nunca seu-usuario), substitua entradas desatualizadas do bloco de código da árvore do projeto pelo que existe, adicione uma tabela de conteúdo ou linha de links rápidos quando houver mais de seis seções, envolva seções de referência longas (opções de CLI, configuração completa, antecedentes científicos) em <details>, adicione badges para a stack real (versão do Python, licença, bibliotecas principais) e uma <picture> ou captura de tela emoldurada para ambos os temas, e defina a descrição do repositório e tópicos na entrega.
  • Âncoras com emoji: o GitHub remove o emoji do slug de um cabeçalho, mas mantém o hífen, então ## 🚀 Início Rápido é #-início-rápido, não #início-rápido. Escreva cada link de navegação e link de badge dessa forma e verifique cada um contra seu cabeçalho. O resumo <details> não é um cabeçalho e não tem âncora.
  • Ainda siga cada lei do README (Verdadeiro, Executável, Ambos os temas) e a etapa Verificar.

3. Construir

Os melhores READMEs no GitHub (Excalidraw, Scalar, Supabase, Charm, Rich, Bun) compartilham alguns movimentos. Use todos eles; é isso que faz este parar uma rolagem.

O hero: um SVG animado

Esta é a assinatura. Um banner estático parece um template; um hero que se move — nas próprias cores, fontes e UI do projeto — parece feito para este projeto. O GitHub renderiza um SVG em uma tag <img> com seus CSS @keyframes em execução, então o hero pode animar sem as faixas ou peso de um GIF.

Construa .github/readme/hero.svg (viewBox cerca de 1600×800, renderizado em width="100%"):

  • A cena é o produto. Recrie o hero real do projeto ou tela chave como formas SVG: sua imagem de fundo, seu título em sua própria fonte e um elemento de UI real fazendo seu trabalho (um cartão deslizando, um comando digitando, um gráfico desenhando, um toast aparecendo). Uma ideia, um loop.
  • Movimento: CSS @keyframes em um bloco <style> dentro do SVG, apenas em transform e opacity, com transform-box: fill-box; transform-origin: center em qualquer coisa que escale ou gire. Um loop de 6–10 s que retorna ao quadro inicial perfeitamente, entradas escalonadas, cada linha de texto estabilizada por tempo suficiente para ser lida. Adicione uma deriva lenta no fundo (uma escala de 1,0 → 1,05 ao longo do loop) para que o quadro nunca pareça congelado. Um CSS transform substitui o atributo SVG transform de um elemento, então posicione as coisas com um <g transform=…> externo e anime um elemento interno.
  • Movimento reduzido: envolva os keyframes em @media (prefers-reduced-motion: no-preference) para que leitores que optarem por sair vejam o quadro final estabilizado. O quadro estabilizado deve ser publicável por si só e mostrar o produto, então qualquer coisa que só apareça no meio do loop (uma sobreposição de correspondência, um toast) começa oculta com um atributo opacity="0" e é revelada apenas por seus keyframes.
  • Autocontido. Um SVG carregado através de <img> não pode buscar nada: sem fontes web por URL, sem imagens externas, sem scripts. Incorpore fontes como base64 @font-face (os arquivos latin do Google Fonts já têm cerca de 20 KB e podem ser incorporados inteiros; subconjunte outras fontes com pyftsubset … --text="…" --flavor=woff2, que precisa de um fontTools recente), ou converta o texto em caminhos. Incorpore fotos como base64 JPEG, redimensionadas para o que o hero precisa. Evite <foreignObject> (Safari não renderiza dentro de <img>). Mantenha o arquivo abaixo de ~1,5 MB.
  • Ambos os temas. Se o hero for sem margens e opaco, funciona em ambos; caso contrário, faça hero-dark.svg também e alterne com <picture> ou fragmentos de URL #gh-dark-mode-only / #gh-light-mode-only.
  • Texto: o nome do projeto e a frase de efeito, grandes (o hero encolhe para cerca de 40% em celulares). Nada mais.
<p align="center">
  <a href="<link do site ou demo>"><img src=".github/readme/hero.svg" alt="<Projeto> — <frase de efeito>" width="100%"></a>
</p>

Também capture o quadro estabilizado em 1280×640 para .github/readme/social-preview.png (opaco) para o cartão social do repositório; renderize o SVG em um navegador headless com movimento reduzido ativado.

Se o projeto não tiver identidade visual que valha a pena animar (uma biblioteca sem UI), faça uma marca d'água animada: o nome em uma fonte adequada, um movimento que diga o que faz (um valor fluindo através de um cano, texto sendo formatado, um teste ficando verde).

Demonstração, emoldurada

Em ordem de preferência:

  1. O vídeo de demonstração. Aquele encontrado em Inspecionar ou feito na etapa O vídeo. Se um brag.mp4 existir, faça um GIF de pré-visualização em loop ou WebP animado a partir de seus 4–8 segundos mais fortes

...

[truncado para tradução]

Habilidades Relacionadas