Frontends com Vibecoding · Capítulo 29 de 35 · 42 min
Configurar ambiente, skills e o contêiner de contexto
O ambiente fica montado com contexto oficial, skills lidas antes de confirmar e um pedido de tela em forma de contêiner, com restrições e referências na mesma ordem.
Este capítulo faz parte do curso gratuito Frontends com Vibecoding.
Um agente de programação pode sugerir um pacote que não existe. Em pesquisa publicada pela Lasso Security em março de 2024, Bar Lanyado registrou o nome huggingface-cli, sugerido por modelos, e publicou um pacote vazio para observar o comportamento. O pesquisador relatou mais de 30 mil downloads em três meses. Esse experimento mostrou o risco de confiar no nome sugerido; não demonstrou 30 mil invasões.
Antes de instalar, compare o nome e o comando com a documentação do fornecedor, confira o mantenedor e leia o que será executado. Uma fonte de contexto ajuda a consulta, mas não substitui essa verificação.
Ao terminar, você sabe o que significa conectar uma ferramenta ao agente por MCP ou instalar uma skill, e confere o que já está ligado no projeto antes de autorizar mais. Tempo de leitura: cerca de 42 minutos, e a revisão feita com o time, mais 15.
Na primeira estação fica o agente, aberto no terminal dentro da pasta do projeto. O terminal é a janela preta em que você digita comandos em vez de clicar em botões; é por ela que o agente recebe ordens.
A segunda estação é o projeto no ar, com o comando de desenvolvimento rodando numa janela própria, que atualiza o navegador a cada arquivo gravado. A terceira é o próprio navegador, que o agente abre para ler erros e medir contraste.
Na quarta estação fica o histórico de alterações, o registro de cada mudança, como o extrato de uma conta. Ele deixa desfazer um erro sem refazer o trabalho todo. Uma quinta peça encurta o ciclo: o serviço que sublinha erro no editor devolve a lista de problemas, e o agente conserta no mesmo turno.
Ver como texto
Quatro cartões numerados formam a oficina: 1 o agente, aberto no terminal dentro da pasta do projeto; 2 o projeto no ar, que atualiza a cada arquivo gravado; 3 o navegador, que o agente abre para ler erros e medir contraste; 4 o histórico de alterações, cada mudança registrada como num extrato. Uma faixa embaixo acrescenta a quinta peça: o serviço que sublinha erro no editor devolve a lista de problemas ao agente no mesmo turno.
Com a máquina digitando, o seu gargalo passa a ser descrever o que você quer. O teste barato de clareza é terminar em voz alta a frase: esta tela deu certo se. Quando você não completa a frase, o agente também não completa, porque a instrução chegou incompleta.
Cada tela que funciona vira um commit, o ponto de retorno gravado no histórico com uma mensagem do que mudou. Voltar ao estado anterior custa um comando, e meio dia de mudanças num registro só esconde qual delas quebrou a tela.
Ver como texto
O loop de quatro tempos do vibecoding: Intenção, Geração, Revisão e Iteração em ciclo circular
Antes de pedir uma integração, confira a documentação oficial da biblioteca e sua versão. O MCP é um protocolo que conecta aplicações de IA a ferramentas e fontes de contexto; um servidor MCP não é necessariamente mantido pelo fornecedor da biblioteca. Confira seu mantenedor, suas permissões e a origem dos dados. A documentação também pode ser consultada diretamente, sem MCP.
O motivo é medido. No estudo publicado no USENIX Security 2025, as médias de pacotes inventados foram de pelo menos 5,2% nos modelos comerciais e 21,7% nos modelos abertos avaliados. São resultados daquela amostra, não uma taxa prevista para qualquer modelo atual. Eles mostram por que o comando de instalação precisa ser conferido.
Numa oficina que integra um meio de pagamento ao site, confira os comandos na documentação e use o ambiente de testes do provedor antes de aceitar pagamentos reais. A ligação com uma fonte de contexto ajuda a consulta; a integração ainda precisa de testes e revisão.
Ver como texto
Na amostra do USENIX Security 2025, as médias de pacotes inventados foram de pelo menos 5,2% nos modelos comerciais e 21,7% nos modelos abertos. O quadro lembra uma checagem prática: conferir o comando na documentação do fornecedor antes de instalar.
O contexto oficial mais barato de ligar é uma skill, uma pasta com instruções em texto que o agente lê quando o pedido combina com a descrição dela. Ela não instala programa nenhum: é documentação escrita para a máquina ler.
A Anthropic publica um catálogo aberto dessas pastas, o repositório anthropics/skills, e a instalação cabe em um comando: npx skills add https://github.com/anthropics/skills --skill frontend-design. Ele grava a pasta na sua máquina e serve a qualquer agente que leia esse diretório. A portaria dessa instalação é o assunto da aula seguinte.
Quando o fornecedor da API não publicou contexto nenhum, a saída é construir o seu próprio servidor de contexto, e a skill mcp-builder do mesmo catálogo diz como. API é a porta pela qual dois programas conversam, como o balcão por onde um sistema pede dado a outro.
Duas regras dessa skill evitam a maior parte do retrabalho. Toda ferramenta exposta leva um prefixo no nome, como oficina_listar_ordens, para o agente não confundir com ferramenta de outro servidor. E toda mensagem de erro diz o que fazer, em vez de um código numérico que o agente vai chutar.
Ver como texto
Da fonte à integração testada. 1. Identificar a fonte: Mantenedor, versão e permissões; 2. Conferir a API: Documentação do fornecedor; 3. Testar: Ambiente de testes e resultado observado. MCP conecta ferramentas; a revisão continua.
Antes do primeiro pedido sobre uma biblioteca grande, ligue uma skill do catálogo ou declare a conexão MCP com o endereço da documentação oficial. A chave de acesso fica em variável de ambiente, fora do arquivo versionado.
Grave um commit a cada tela aprovada. E nunca instale um pacote sugerido pelo agente sem abrir a página dele no registro oficial: se a página não existe, o nome foi inventado.
Instale plugin e skill sem cair no pacote de nome inventado
Com a oficina montada e o contexto oficial conectado, o passo seguinte é distinguir plugin de skill e ler o que cada um roda antes de confirmar a instalação.
Um plugin pode adicionar comandos, ferramentas e conexões ao assistente. O alcance depende das permissões do ambiente. Por isso, confira quem publica o pacote, o que ele executa e a quais dados pode ter acesso.
O experimento da Lasso Security mostrou que um nome inventado pode ser repetido e depois registrado por outra pessoa. Encontrar esse nome em um registro de pacotes, por si só, não comprova que ele seja o componente recomendado pelo fornecedor.
A skill é uma pasta com um arquivo de instruções em texto, que o agente lê quando o pedido combina com a descrição dela. Ela não instala programa nenhum. O plugin é o pacote maior: pode trazer skills, comandos, conexões e verificações que rodam com o seu privilégio na sua máquina.
Essa diferença muda a portaria. A skill pede leitura do texto; o plugin pede leitura do texto e dos comandos que ele registra, porque um comando roda o que estiver escrito dentro dele.
Ver como texto
Em cima, a skill: uma pasta com instruções em texto, cuja portaria é ler o texto. Embaixo, o plugin, o pacote maior, que pode trazer skills, comandos, conexões e verificações, todos rodando com o seu privilégio de usuário; a portaria dele pede ler o texto e também os comandos.
Três defesas cobrem a maior parte desse risco, e cada uma limita o que a anterior deixa passar. Instalar só de catálogo autorizado limita a origem. Ler o que o pacote adiciona limita a surpresa. Escolher o escopo mais restrito limita o estrago quando as duas primeiras falham.
Escopo é o alcance da instalação. Instalada na pasta do projeto, a skill vale só para aquele site. Instalada na pasta do usuário, vale para toda sessão aberta na máquina, inclusive a do cliente seguinte.
O catálogo anthropics/skills tem dois caminhos oficiais de instalação. O universal é o comando npx skills add, com o endereço do catálogo e o nome da skill. Dentro do Claude Code existe também o comando de marketplace, que instala o pacote pelo nome do catálogo.
Esse instalador avisa, em inglês, que skills rodam com todas as permissões do agente. A frase diz uma coisa prática: a skill orienta o mesmo programa que grava arquivos e roda comandos. Uma instrução maliciosa escrita nela tem o alcance do próprio agente.
A frontend-design, a mais instalada do catálogo, é a que esta trilha usa nas aulas seguintes.
Ver como texto
As duas vias pelas quais um pacote entra no assistente: a descritiva injeta texto cobrado por turno e vira orçamento recorrente; a executiva registra comandos e conexões que rodam com o privilégio de quem instalou e equivale a admitir um fornecedor. Três defesas se reforçam em ordem: catálogo autorizado, leitura do que o pacote adiciona e escopo restrito.
O custo de uma skill instalada se mede por turno de conversa, cada ida e volta entre você e o assistente. A skill-creator do mesmo catálogo explica essa conta em três níveis.
Nome e descrição de toda skill instalada ficam sempre no contexto, cerca de 100 palavras cada. O corpo do arquivo de instruções só entra quando a skill dispara, e o ideal é ficar abaixo de 500 linhas. As referências entram só quando o corpo as chama.
Dez skills instaladas custam cerca de mil palavras em todo turno, mesmo no pedido que nenhuma delas atende. É por isso que a descrição precisa ser específica no que dispara, e o corpo, curto no que ensina.
Ver como texto
Três faixas numeradas mostram quando cada parte da skill entra no contexto. Faixa 1: nome e descrição, cerca de 100 palavras, sempre. Faixa 2: corpo do arquivo, abaixo de 500 linhas, só se a skill dispara. Faixa 3: referências, só quando o corpo as chama. Um quadro embaixo faz a conta: dez skills instaladas custam cerca de mil palavras em todo turno.
Antes de instalar, leia três coisas na pasta da skill. O frontmatter, o cabeçalho do arquivo com o nome e a descrição, diz quando ela dispara. O corpo diz o que ela manda o agente fazer. A pasta de scripts, quando existe, guarda programas que o agente vai executar, e é ali que uma instrução perigosa se esconderia.
Essa leitura custa cinco minutos. Numa clínica que guarda a agenda dos pacientes no mesmo projeto, é o que separa saber o que o pacote faz de descobrir isso depois que ele rodou.
O segundo custo chega pela credencial exposta. Mais código gerado significa mais arquivo de configuração no projeto, e é ali que uma senha de acesso costuma parar esquecida. O lugar dela é a variável de ambiente, o cofre que fica fora do arquivo enviado ao repositório.
Ver como texto
Árvore de uma pasta de skill com três marcadores. A pasta minha-skill guarda o arquivo SKILL.md, que tem o frontmatter, marcado 1, quando dispara, e o corpo, marcado 2, o que manda o agente fazer; e a pasta scripts, marcada 3, com os programas que o agente executa. Uma faixa embaixo lembra que a senha de acesso fica na variável de ambiente, fora do repositório.
Antes de confirmar qualquer instalação, decida o que o pedido exige. Orientação em texto é a skill; comando e conexão novos são o plugin, que pede portaria mais rígida.
Instale pelo caminho oficial, leia o cabeçalho, o corpo e a pasta de scripts na mesma sessão e escolha o escopo mais restrito. Se a lista de erros de carregamento não ficar vazia, não use o pacote.
Montar o pedido de tela com o contexto que evita o default
Ambiente e skills instalados entregam a matéria-prima, e a tela ainda depende de um pedido que reúna arquivo de sistema, restrições, componentes do registro e cenário fixo.
O pedido de tela virou um contêiner de contexto. No mesmo prompt, que é o pedido escrito que você manda ao agente, entram o arquivo de regras do projeto, o catálogo de peças prontas e as referências.
Cabe muito ali. Na ferramenta de desenho por pedido Aura, uma referência marcada com arroba acrescenta até 100 mil caracteres numa só mensagem, cerca de duas mil linhas de texto.
As sete camadas abaixo são uma proposta de organização do pedido. Elas ajudam a tornar explícitas as referências e as restrições; não garantem fidelidade à marca. Compare a tela com os tokens, componentes e exemplos aprovados, e registre os desvios encontrados antes de reutilizar o pedido.
Ver como texto
Uma caixa grande chamada pedido de tela contém três camadas: o arquivo de regras do projeto, o catálogo de peças prontas e as referências, que chegam a 100 mil caracteres. Uma seta indica a primeira montagem feita e leva à página nova, cujo pedido cabe em dez linhas porque o contexto já mora nos arquivos.
O exemplo da própria documentação troca crie uma landing page por crie usando o modelo de topo e os cartões de preço do catálogo. A edição direcionada muda só a parte pedida, e o catálogo tem mais de mil modelos prontos.
Agora o fornecedor escreve para o agente do cliente, e isso muda onde você busca contexto. O Unicorn Studio, editor de cenas animadas, publica um arquivo de instruções em que o agente lê como usar a cena com segurança e desempenho.
O Refero pesquisa telas reais e exporta o resultado como um DESIGN.md, o arquivo de regras visuais do projeto. No 21st.dev cada componente vem com o pedido pronto para copiar. O MCP, o canal que liga o agente a uma fonte externa, dá a ele busca e instalação.
A GetLayers vende o modelo de página como pedido pronto, parte grátis e parte paga. O risco é o de sempre: modelo de pedido continua sendo modelo, e devolve a mesma tela para todo mundo que comprou.
| Camada | De onde vem | Exemplo de linha no pedido | O que acontece se faltar |
|---|---|---|---|
| 1. Assunto, público e tarefa | Briefing da trilha 1 | Página de matrícula, pais no celular, reservar a aula experimental | O agente propõe um assunto genérico e desenha para ele |
| 2. Arquivo de sistema | DESIGN.md do projeto ou vizinhos do Refero como leitura | Leia DESIGN.md antes de qualquer decisão visual | Cor, fonte e raio saem da memória de treino |
| 3. Restrições nomeadas | Do's and Don'ts do DESIGN.md e a lista da skill | Sem os cinco padrões genéricos; sem biblioteca de animação nova | O eixo livre se gasta num default |
| 4. Componentes do registro | 21st.dev, MCP do shadcn ou registro próprio | Use clave-hero e clave-card-turma com os tokens do DESIGN.md | O agente escreve o quarto botão da casa ou cola o azul do autor |
| 5. Assinatura de movimento | Cena do Unicorn Studio ou sequência de carga | Só a onda sonora no herói; nada de fade por seção | Movimento repetido sem função clara; revisar a intenção de cada animação |
| 6. Copy | Vocabulário do negócio | Botão: Reservar aula | Texto de preenchimento e botão que diz Enviar |
| 7. Crítica e cenário fixo | Print da tela e cenário congelado | Compare com matricula-01 e liste o que mudou | Cada rodada parte de outro lugar e ninguém mede a diferença |
A ordem ajuda a organizar as decisões. A aderência à marca é conferida na aplicação renderizada.
Fonte: Ordem de montagem definida pelo autor a partir da documentação da Aura, da Vercel (31/08/2026) e da skill frontend-design.
Comece pelo assunto e pelas regras da marca antes de selecionar componentes. Essa sequência facilita explicar por que cada peça foi escolhida. Depois de montar as sete camadas, confira na tela as cores, a tipografia, os espaços e a tarefa principal; registre o que ainda precisa de ajuste.
Ver como texto
Regras, peças e revisão. 1. Definir: Assunto, público e referências da marca; 2. Montar: Componentes compatíveis com as regras; 3. Conferir: Tela renderizada contra o briefing. Registrar divergências antes de aprovar.
Primeiro, o assunto, o público e o trabalho que a tela resolve. Segundo, o DESIGN.md do projeto, o arquivo que guarda os valores visuais e o motivo de cada um.
Se ele ainda não existe, dois ou três arquivos de projetos vizinhos entram como leitura de referência, nunca como cópia. Terceiro, as restrições nomeadas: os padrões proibidos pelo nome e o que o agente não pode instalar.
Quarto, os componentes do registro, que é o catálogo de peças de onde o código é copiado, como uma feira de fornecedores. Cite os nomes dos seus tokens, os valores de design guardados com nome, como a etiqueta na lata de tinta.
Quinto, uma assinatura de movimento, a única animação que a página terá. Sexto, o texto dos botões e títulos. Sétimo, a crítica com print da tela e um cenário fixo, repetido a cada mudança.
Contexto grande custa dinheiro e atenção, e o agente lê pior o que decide quando afoga no que só descreve. A Vercel resolveu isso proibindo o agente de ler a folha de estilo inteira: ele monta a página só com os nomes de classe documentados.
Copie a regra. Referencie o que decide, o DESIGN.md, dois componentes pelo nome e a restrição, e resuma o resto em uma linha. A skill frontend-design faz essa leitura de dentro do agente, instalada como a aula anterior mostrou, e é a mais instalada do catálogo.
O mesmo pedido de tela, em texto solto e em contêiner
Pedido em texto
Texto solto
- Crie uma página de matrícula moderna e limpa para a escola.
- Cores e fontes descritas de memória, diferentes a cada pedido.
- O agente escolhe o herói e o botão que mais viu no treino.
- Componente do registro colado com o azul e o raio do autor.
- Movimento de entrada em toda seção, porque ninguém limitou.
- Resultado julgado de olho, sem base para comparar com a rodada anterior.
Pedido em contêiner
Contêiner
- Assunto, público e tarefa em três linhas.
- Leia DESIGN.md antes de qualquer decisão visual.
- Padrões proibidos pelo nome; nenhuma biblioteca de animação nova.
- Dois componentes do registro pelo nome, adaptados aos tokens no mesmo passo.
- Uma cena de assinatura no herói; o resto responde à ação da pessoa.
- Cenário fixo e critério de aceite, comparáveis a cada rodada.
O pedido-modelo abaixo monta as sete camadas para a página de matrícula de uma escola de música. Ele aponta para o DESIGN.md em vez de repetir valores, cita dois componentes pelo nome, proíbe os padrões genéricos pelo nome e fecha com o critério de aceite. Troque os nomes pelos do seu projeto.
1. Assunto, público e tarefa
Página de matrícula da Escola de Música Clave, para pais no celular,
que querem reservar a aula experimental em três toques.
2. Sistema
Leia DESIGN.md antes de qualquer decisão visual. O vermelho do piano
(colors.primary) só no botão de reserva; fundo em colors.paper.
3. Restrições nomeadas
Sem os cinco padrões genéricos da skill frontend-design; a lista completa
está no DESIGN.md, seção Do's and Don'ts. Sem instalar biblioteca nova.
4. Componentes do registro
Use clave-hero e clave-card-turma, já instalados; mapeie cor, raio e
fonte para os tokens do DESIGN.md no mesmo passo.
5. Assinatura de movimento
Só a cena de onda sonora no herói, já configurada; nada de fade por seção.
6. Copy
Título: "Primeira aula com o professor, sem compromisso". Botão: "Reservar aula".
7. Crítica e aceite
Tire um print, compare com o cenário fixo matricula-01 e liste o que mudou.
Aceite: nenhum padrão da lista, botão de reserva visível sem rolar, uma só cor de ação.A escola que monta esse contêiner uma vez reduz o pedido de cada página nova a dez linhas, porque o contexto já mora nos arquivos. O DESIGN.md guarda o vermelho do piano e a regra de usá-lo só no botão de reserva.
Três componentes do catálogo ficam renomeados com o prefixo da escola e adaptados aos tokens dela. Se o pedido não cabe em dez linhas, algo que devia morar no arquivo continua solto no prompt.
Monte o contêiner do seu projeto uma vez: as regras primeiro, depois as restrições nomeadas, depois os componentes do catálogo e, por fim, um cenário congelado para comparar. Rode o primeiro pedido a partir dele. Se a página seguinte não couber num pedido de dez linhas, o contexto ainda está solto no prompt, e não no arquivo.
Guia prático: página de curso a partir do Figma, com o agente lendo o frame
A página de um curso tem seções previsíveis: promessa, programa, quem ensina, depoimentos, perguntas frequentes e matrícula. Quando o desenho já existe no Figma, o servidor MCP do Figma entrega ao agente o frame, as variáveis e a captura, e a tela deixa de ser reconstruída a partir de um print.
O servidor remoto fica em https://mcp.figma.com/mcp e trabalha por link: o pedido precisa trazer o endereço do frame ou da camada. A Figma informa que o uso pleno pede assento Full ou Dev; os demais assentos podem ter limite de uso. Em 24 de setembro de 2026 a empresa anunciou edição visual com painel de propriedades e anotações no Figma Make, e reforçou o Code Connect com o MCP para apontar ao agente qual componente do Figma corresponde a qual componente do código.
Ver como texto
Ilustração da central de ajuda do Figma com dois quadros lado a lado. À esquerda, o Figma aberto no navegador com um triângulo, um círculo e um quadrado no canvas. À direita, um quadro escuro chamado MCP server com uma caixa de mensagem, representando o agente que recebe o contexto do arquivo.
Do frame do Figma à página de curso publicada em prévia
Seis passos para Claude Code, Cursor ou Codex. O contêiner de contexto que você montou continua valendo: o Figma entra como a camada de referência.
Passo 1: Conecte o servidor do Figma ao agente
Claude Code: claude plugin install figma@claude-plugins-official, ou claude mcp add --scope user --transport http figma https://mcp.figma.com/mcp. Codex: codex mcp add figma --url https://mcp.figma.com/mcp. Cursor: /add-plugin figma.
Deu certo quando: O comando /mcp mostra o servidor figma autenticado na conta que tem acesso ao arquivo.
Erro comum: Instalar um servidor de nome parecido achado numa conversa. Use só o endereço da documentação da Figma.
Passo 2: Copie o link do frame, uma seção por vez
No Figma, selecione o frame da seção e copie o link. O servidor remoto não lê a seleção da tela; ele lê o endereço.
Deu certo quando: O agente responde citando o nome do frame que você enviou.
Erro comum: Mandar o link da página inteira e receber um arquivo único de mil linhas, difícil de revisar.
Passo 3: Peça as variáveis antes do código
A ferramenta get_variable_defs lista cor, espaço e tipografia usados no frame. Peça ao agente para casar cada variável com um token do seu DESIGN.md e apontar o que não tem par.
Deu certo quando: Uma tabela curta: variável do Figma, token do projeto e as sobras para você decidir.
Erro comum: Deixar o agente cravar valores em hexadecimal no componente, fora dos tokens.
Passo 4: Gere a seção com os componentes do projeto
A ferramenta get_design_context devolve React com Tailwind por padrão. Peça que ele use os componentes do seu catálogo pelo nome e compare o resultado com get_screenshot.
Deu certo quando: O agente entrega a seção, o print da tela montada e a lista do que difere do frame.
Erro comum: Aceitar botões e cartões novos quando o catálogo já tem os dois.
Passo 5: Preencha o conteúdo real do curso
Programa, carga horária, preço, datas e nome de quem ensina vêm da fonte oficial da escola. Texto de preenchimento do desenho não vai para a prévia.
Deu certo quando: Cada número da página tem dono e confere com o cadastro do curso.
Erro comum: Publicar a carga horária do protótipo, que ninguém atualizou.
Passo 6: Feche com o critério de aceite e um commit por seção
Escreva a frase do capítulo: esta tela deu certo se a matrícula começa em um toque no celular e o programa abre pelo teclado. Grave um commit a cada seção aprovada.
Deu certo quando: A prévia abre no celular, o botão de matrícula aparece sem rolagem e o histórico tem um ponto de retorno por seção.
Erro comum: Um commit único com a página inteira, sem ponto de retorno quando uma seção quebra.
No fim você tem: Uma página de curso fiel ao desenho, montada com os componentes e os tokens do projeto, com conteúdo conferido e um commit por seção.
Guia prático: skill recebida em zip, conector remoto e a lista do que está pronto
Boa parte das skills circula como arquivo compactado, e o erro mais comum de instalação é a pasta repetida: o zip descompacta em skills/nome/nome/SKILL.md e o agente não encontra nada. O curso estudado em 07/10/2026 ensina a pedir a instalação com a regra escrita: o SKILL.md fica direto dentro da pasta da skill. No Claude Code, a pasta pessoal é ~/.claude/skills/<nome>/ e a do projeto é .claude/skills/<nome>/. A documentação diz que a pasta é observada e a skill nova vale na sessão em andamento; se a pasta de skills não existia quando a sessão abriu, rode /reload-skills ou abra uma conversa nova.
O conector é o outro lado. Conector remoto é um servidor MCP acessado por endereço, com login pelo navegador (OAuth). No Claude Code, entra com claude mcp add --transport http <nome> <endereço> e a autenticação acontece pelo comando /mcp. No aplicativo, o curso usa Configurações, Conectores, Adicionar conector personalizado, com o mesmo endereço. Os conectores carregam quando a conversa começa: se ele não aparece, a conversa nova resolve antes de qualquer outra tentativa.
O fecho do curso é uma checagem de ambiente. Um script de 76 linhas marca cada item como pronto, falta ou opcional (ferramentas, versões, gravador de tela, chaves) e, em cada falta, diz o que fazer. A chave entra no .env aberto no editor e a checagem confirma que ela existe sem exibir o valor. Com a lista na mão, você sabe se pode começar antes de perder uma hora no primeiro erro.
Anexei o arquivo [NOME].zip. Instale esta skill:
1. Descompacte em ~/.claude/skills/[NOME]/.
O SKILL.md fica direto dentro dessa pasta, sem pasta repetida no meio.
2. Leia o cabeçalho do SKILL.md e a pasta de scripts e me diga, em 5 linhas,
o que ela faz e que comandos ela roda.
3. Diga se preciso de /reload-skills ou de conversa nova para ela carregar.
Depois rode a checagem de ambiente na pasta [PASTA DO PROJETO] e responda
com uma lista em três grupos: pronto, falta e opcional.
Para cada item que falta, diga o comando ou a página que resolve.
Chave de API: só confirme se existe no .env, sem mostrar o valor.Do zip recebido ao ambiente conferido
Cinco passos para instalar o que um curso, um colega ou um fornecedor mandou, e saber que está tudo pronto.
Passo 1: Instale a skill com a regra da pasta escrita
Use o pedido do bloco acima. O caminho final precisa ser pasta da skill, depois o SKILL.md, sem nível extra. Peça para listar a pasta depois de descompactar.
Deu certo quando: A listagem mostra o SKILL.md no primeiro nível da pasta da skill.
Erro comum: Descompactar com duplo clique e deixar skills/nome/nome, que o agente ignora sem avisar.
Passo 2: Leia o que ela roda antes de usar
Cabeçalho, corpo e pasta de scripts, como o capítulo ensina. Skill recebida por zip não passou por catálogo nenhum, então a leitura é a única portaria.
Deu certo quando: Você sabe dizer em uma frase quando ela dispara e quais scripts executa.
Erro comum: Confiar no nome do arquivo porque veio de um curso pago.
Passo 3: Ligue o conector remoto pelo endereço
No terminal, claude mcp add com --transport http, o nome e o endereço; depois /mcp para fazer o login no navegador. No aplicativo, o caminho é a tela de conectores. Escolha o escopo mais restrito que serve.
Deu certo quando: O conector aparece como conectado e lista as ferramentas dele.
Erro comum: Tentar de novo na mesma conversa quando o conector não aparece; ele só carrega no início.
Passo 4: Libere sem pergunta só o que lê
Nas permissões do conector, "sempre permitir" fica para ferramenta de consulta, como listar ou buscar. Ferramenta que cria, apaga, envia ou publica continua pedindo aprovação a cada uso.
Deu certo quando: Nenhuma ferramenta que escreve ou publica está liberada sem aprovação.
Erro comum: Clicar em sempre permitir em tudo no primeiro aviso para parar de ser interrompido.
Passo 5: Rode a checagem e guarde a lista
Peça a lista em pronto, falta e opcional, resolva cada falta e rode de novo. Guarde a última saída no projeto: ela é o primeiro passo quando você trocar de computador.
Deu certo quando: A checagem volta sem nenhum item em falta.
Erro comum: Começar o trabalho com uma falta "que depois resolvo" e descobrir no meio que era a chave de transcrição.
No fim você tem: Skill instalada no lugar certo, conector ligado com permissão mínima e uma lista que prova que o ambiente está pronto.
Guia prático: AGENTS.md nativo, MCP sem sessão e plugin com prova
Em setembro e outubro de 2026 o Claude Code passou a ler o AGENTS.md sozinho, a falar a revisão nova do MCP por padrão e a avaliar plugin contra casos de teste. O guia mostra cada função, como o repositório deste portal organiza instruções, plugins e ganchos, e como o servidor MCP público dele atende clientes novos e antigos no mesmo endereço. No fim, o pedido que monta o mesmo esqueleto num projeto de campanha.
Funções, casos de uso e aplicações
Funções
| Função ou recurso | O que faz | Quando usar | Desde |
|---|---|---|---|
| AGENTS.md lido de forma nativa (v2.1.277) | Num projeto sem CLAUDE.md, o Claude Code lê o AGENTS.md, o arquivo de instruções que Codex e outros agentes também leem. A escolha fica em Project instructions, no /config | Repositório usado por mais de um agente, para as regras não divergirem | 18/09/2026 |
| Revisão 2026-07-28 do MCP | Tira a sessão e o aperto de mão initialize: cada pedido leva a versão e as capacidades. Entra server/discover, todo resultado traz resultType e as listas trazem ttlMs e cacheScope, dicas de quanto tempo guardar a resposta | Servidor remoto novo, que fica mais simples de escalar porque não guarda estado entre pedidos | 28/07/2026 |
| Claude Code negocia a 2026-07-28 por padrão (v2.1.292) | Servidores locais passam a usar a revisão nova; MCP_PROTOCOL_NEGOTIATION=legacy volta à antiga | Testar o servidor antes que o cliente dos usuários troque de versão | 06/10/2026 |
| claude plugin install --marketplace <fonte> | Adiciona o catálogo de plugins se faltar, com as mesmas checagens de política, e instala o plugin dele num comando | Instruir um colega a instalar o plugin da equipe sem dois passos | 06/10/2026 |
| claude plugin eval | Roda o plugin contra uma bateria de casos, dá nota e compara com uma rodada sem o plugin; claude plugin eval init rascunha casos e avaliadores | Plugin em dúvida: melhora o resultado ou só ocupa contexto | Semana de 07/09/2026 |
| /skill-doctor | Mostra quanto contexto cada skill instalada ocupa e com que frequência ela é usada | Podar skills que custam em todo turno e quase nunca disparam | Semana de 31/08/2026 |
| Gancho com onFailure: "block" (v2.1.295) | Gancho de comando ou HTTP que não inicia, estoura o tempo ou sai com código inesperado passa a bloquear a ação em vez de deixá-la seguir | Guarda de marca ou de segredo que não pode falhar em silêncio | 08/10/2026 |
Fonte: Claude Code, changelog e What's new; especificação do MCP, revisão 2026-07-28; lidos em 12/10/2026
Casos de uso
Professor e dono de um cursinho online de redação em Belo Horizonte
Educação, páginas de turma feitas com agente
Dor
Ele instalou 12 skills e quatro plugins ao longo do semestre. As respostas do agente ficaram lentas, e ninguém sabia qual pacote ajudava de fato.
Solução
Rodou /skill-doctor para ver o custo de cada skill em contexto e a frequência de uso, e escreveu dez casos de teste de página de turma para o claude plugin eval comparar o plugin de design com a rodada sem plugin.
Resultado do exemplo
O que observar: depois da poda, o tempo de resposta nas sessões seguintes e a nota do eval com e sem o plugin. Plugin que não muda a nota sai da máquina.
Cenário construído para fins didáticos. Números não correspondem a cliente específico.
Analista de marketing de uma cooperativa de crédito em Chapecó
Serviços financeiros, catálogo de produtos para agentes de IA
Dor
O servidor MCP de leitura com as taxas e produtos da cooperativa só falava o aperto de mão antigo, e o time temia que clientes novos parassem de enxergar as ferramentas.
Solução
O servidor passou a atender as duas eras no mesmo endereço: server/discover e resultType para a revisão 2026-07-28, initialize para as antigas. Todas as ferramentas ficaram marcadas como somente leitura.
Resultado do exemplo
O que observar: no primeiro mês, nos registros de acesso, quantos pedidos chegam pela era nova e quantos pela antiga, e se algum cliente recebe erro de versão.
Cenário construído para fins didáticos. Números não correspondem a cliente específico.
Na prática
O repositório deste portal tem três peças que a trilha ensina. O CLAUDE.md da raiz começa com uma linha, @AGENTS.md, que importa as regras comuns a Claude Code, Codex e Gemini; abaixo dela entra só o que é próprio do Claude Code. O .claude/settings.json liga os plugins do projeto, entre eles frontend-design, playwright, context7 e chrome-devtools-mcp, e registra dois ganchos: um formata com Prettier todo arquivo TypeScript editado, outro grava um lembrete de decisão no fim da sessão.
A terceira peça é o servidor MCP público, em src/lib/public-mcp.ts, servido por /api/mcp. Ele declara as versões 2026-07-28, 2025-11-25 e 2025-06-18 e atende as duas eras no mesmo endereço: na nova responde server/discover e recusa initialize; na antiga negocia pelo aperto de mão. As listas trazem ttlMs de uma hora e cacheScope público, porque todas as ferramentas são de leitura.
export const MCP_VERSIONS = ["2026-07-28", "2025-11-25", "2025-06-18"] as const;
export const MCP_LIST_TTL_MS = 3_600_000;
// ...
const result = (value: Record<string, unknown>) =>
reply({ jsonrpc: "2.0", id, result: { resultType: "complete", ...value, ...resultMeta } }, 200, agent);
const cacheable = { ttlMs: MCP_LIST_TTL_MS, cacheScope: "public" as const };
switch (body.method) {
case "server/discover":
return result({
supportedVersions: MCP_VERSIONS,
capabilities: SERVER_CAPABILITIES,
instructions: instructionsFor(tools, release),
...cacheable,
});
case "initialize": {
if (modern) return mcpError(id, -32601, "initialize não existe na era moderna; use server/discover.", 404);
// era legada: negocia 2025-11-25 ou 2025-06-18
}
}Instruções, guardas e servidor em cinco passos
A ordem importa: primeiro as regras que todo agente lê, depois as guardas que as fazem valer, por último o que sai para o mundo.
Passo 1: Regras escritas uma vez, no AGENTS.md
Regra que vale para qualquer agente mora no AGENTS.md. O CLAUDE.md importa esse arquivo com @AGENTS.md e guarda só o que é do Claude Code. A importação aceita até quatro níveis.
Deu certo quando: Codex e Claude Code citam a mesma regra quando você pergunta.
Erro comum: Manter CLAUDE.md e AGENTS.md sem a importação: com os dois na pasta, o Claude Code lê só o CLAUDE.md.
Passo 2: Faça a guarda falhar fechada
Instrução é contexto; gancho é obrigação. Com onFailure: "block", um gancho que quebra impede a ação em vez de deixá-la passar.
Deu certo quando: Um botão fora da marca, criado de propósito, é barrado antes de ser gravado.
Erro comum: Gancho que sai com erro por falta de dependência e libera tudo sem ninguém notar.
Passo 3: Pode skills e plugins pelo número
Rode /skill-doctor e veja custo e uso de cada skill. Para plugin, escreva dez casos reais e rode claude plugin eval contra a rodada sem ele.
Deu certo quando: Cada pacote instalado tem um motivo medido para ficar.
Erro comum: Instalar tudo o que aparece numa lista de recomendações e pagar o contexto em todo turno.
Passo 4: Nas duas eras, publique o servidor MCP
Clientes migram em ritmos diferentes. Responda server/discover para a revisão nova e initialize para as antigas, no mesmo endereço.
Deu certo quando: O teste da era nova e o da era antiga passam no mesmo build.
Erro comum: Desligar o aperto de mão antigo no dia do lançamento e sumir dos conectores que ainda não migraram.
Passo 5: Marque o que só lê
Ferramenta de consulta leva readOnlyHint verdadeiro e destructiveHint falso; quem escreve fica fora do servidor público.
Deu certo quando: A lista de ferramentas mostra todas como somente leitura.
Erro comum: Expor uma ferramenta de cadastro no mesmo servidor aberto, sem autenticação.
No fim você tem: Um repositório em que todo agente lê as mesmas regras e as guardas não falham em silêncio, ligado a um servidor MCP que conversa com clientes novos e antigos.
Armadilhas
A regra escrita só vale com guarda e versão
Instrução orienta o agente; gancho que falha fechado e servidor que fala as duas versões fazem a regra valer.
- CLAUDE.md e AGENTS.md juntos sem @AGENTS.md: o Claude Code lê só o primeiro
- Gancho sem onFailure: "block" deixa passar a ação quando ele mesmo quebra
- Servidor só com initialize perde clientes que já falam a revisão 2026-07-28
- Plugin sem eval é opinião: compare a nota com a rodada sem ele
- Skill que nunca dispara ainda ocupa contexto em todo turno
O teste: Force um erro de marca e um cliente da era nova: os dois precisam ter resposta clara.
alexandrecaramaschi.com/educacao/frontends-com-vibecoding
O estado em outubro de 2026
O site do Model Context Protocol, o padrão aberto que liga agentes a sistemas externos, marca a versão de 28/07/2026 da especificação como a vigente. No Claude Code, os comandos personalizados foram incorporados às skills, que seguem o padrão aberto Agent Skills e só carregam o corpo quando são usadas. Instruções longas saem do arquivo de memória e passam a custar quase nada até alguém precisar delas.
Ver como texto
Página What is the Model Context Protocol (MCP)? do site oficial, com o seletor Version 2026-07-28 (latest) no topo. O texto define o MCP como padrão aberto para ligar aplicações de IA a sistemas externos e o compara a uma porta USB-C. Um diagrama mostra o MCP no centro, ligado de um lado a interfaces de chat, editores de código como Claude Code e outras aplicações de IA, e do outro a bancos de dados e arquivos, ferramentas de desenvolvimento como Git e Sentry e ferramentas de produtividade como Slack.
Ver como texto
Página Connect Claude Code to tools via MCP da documentação do Claude Code. O texto diz que o Claude Code se conecta a centenas de ferramentas e fontes de dados pelo MCP, que vale conectar um servidor quando a equipe se pega copiando dados de outra ferramenta para o chat, e lista exemplos: implementar um recurso descrito num chamado do JIRA, analisar dados do Sentry e consultar um banco PostgreSQL.
Ver como texto
Página Extend Claude with skills da documentação do Claude Code. O texto diz que uma skill é um arquivo SKILL.md com instruções, que o Claude usa quando é relevante ou quando alguém a chama pelo nome, e que vale criar uma quando a equipe cola as mesmas instruções várias vezes. Um destaque azul informa que comandos personalizados foram incorporados às skills, e o parágrafo final cita o padrão aberto Agent Skills.
Faça agora: revise o que está ligado ao agente do projeto
Faça com quem opera o Claude Code no projeto.
Passo 1: Peça para rodar o comando /mcp no projeto e mostrar a lista de servidores conectados.
Deu certo quando: Uma lista com o nome de cada servidor e o estado da conexão.
Passo 2: Para cada servidor, pergunte o que ele lê e o que ele pode alterar.
Deu certo quando: Cada linha marcada como "só leitura" ou "leitura e escrita".
Erro comum: Servidor de banco de produção com permissão de escrita, ligado para um teste e esquecido.
Passo 3: Abra a pasta de skills do projeto e leia a descrição no topo de cada SKILL.md.
Deu certo quando: Você sabe quando cada skill dispara e quem a instalou.
Passo 4: Desligue o que ninguém usou no último mês.
Deu certo quando: Uma lista menor, com dono para cada item que ficou.
No fim você tem: Um inventário de conectores e skills com permissão e dono de cada um.
Antes de autorizar um conector ou skill novo
Conector MCP
0/3Skill
0/2Aplicar os recursos ao projeto
Ver como texto
Realce visual preserva o texto copiável
A mesma linha de código é apresentada com distinção de sintaxe e depois em texto simples. A informação permanece idêntica mesmo quando a diferenciação por cor é removida.
Seu caderno neste capítulo
Abrir o caderno completoSelecione um trecho do capítulo para destacar ou anotar. Nos vídeos e áudios, use Anotar este momento. No teclado, selecione com Shift e as setas e use Alt+Shift+D para destacar ou Alt+Shift+N para anotar.
Salvo neste navegador. Entre na sua conta para levar o caderno a outros aparelhos.
Entre na sua conta para compartilhar o que aprendeu e convidar alguém para estudar com você.
Conexões deste capítulo
Veja o que estudar antes e para onde seguir depois, explore os conceitos e compare abordagens em outros cursos. Sugestões marcadas como “sugerido pelo grafo” vêm dos assuntos em comum, não do índice do curso.
Estude antes
- CursoClaude Code: do zero à prática
- Agent Skills e SKILL.md: instruções reutilizáveissugerido pelo grafoApresenta o conceito “Skill (Agent Skill)”, usado em “Configurar ambiente, skills e o contêiner de contexto”.
- Veja o que o Claude Code faz antes de instalarsugerido pelo grafoApresenta o conceito “Claude Code”, usado em “Configurar ambiente, skills e o contêiner de contexto”.
- Ponha dois agentes para revisar um ao outro, com limite de rodadassugerido pelo grafoApresenta o conceito “Codex”, usado em “Configurar ambiente, skills e o contêiner de contexto”.
Conceitos deste capítulo
O mesmo assunto em outros cursos
- Skills e delegação com IAAntes de instalar: confira origem, acessos e arquivosExaminar conexões de Antes de instalar: confira origem, acessos e arquivos
- Software e IA para executivosQuem publicou cada plugue que liga o agente aos sistemasExaminar conexões de Quem publicou cada plugue que liga o agente aos sistemas
- API Design: REST, GraphQL e o contrato com o fornecedorA documentação convence pessoas e agentes de IA?Examinar conexões de A documentação convence pessoas e agentes de IA?
- MCP para quem decideQuais servidores já rodam nas máquinas do timeExaminar conexões de Quais servidores já rodam nas máquinas do time
Terminou a leitura?
Leve uma ideia para a prática
Escolha uma atividade no painel e volte a este curso quando quiser.
Atividades e evolução ficam reunidas no painel da sua conta.
Laboratórios ao vivo deste curso
Cada laboratório monta a biblioteca real dentro da aula, com controles para você mexer e o código do exemplo para copiar. O texto de reserva descreve a demonstração para quem lê sem JavaScript. O link abre o capítulo já no ponto do laboratório.
Base UI
Prenda o foco num diálogo sem escrever o comportamento
Abra a janela Agendar visita, percorra os campos com Tab, feche com Esc e acompanhe no painel onde o foco está e para onde ele volta.
Pacote
Abrir no capítuloConstruir componentes, usar o registro e publicar o catálogo@base-ui/reactLucide e Iconify
Mantenha uma família de ícones coerente e nomeie cada botão
Mude tamanho, traço e cor da barra, veja o símbolo do Iconify acompanhar o Lucide e rode a auditoria de nomes acessíveis.
Pacote
Abrir no capítuloProjetar uma linguagem de ícones e ilustraçãolucide-react, @iconify/reactMotion
Testar os três sinais que autorizam o terceiro degrau
Reproduza a entrada em sequência, aperte o botão com mola e arraste o cartão; ajuste rigidez e amortecimento e veja o que muda.
Pacote
Abrir no capítuloProjetar movimento, assinatura e narrativas por rolagemmotionVidstack
Ver o que separa um player de um vídeo cru
Dê o play, troque a velocidade e ligue a legenda; o painel ao lado mostra o estado que o player publica e que a etiqueta crua esconde.
Pacote
Abrir no capítuloProjetar movimento, assinatura e narrativas por rolagem@vidstack/reactcmdk
Achar um destino entre quarenta digitando três letras
Abra a paleta, digite fat e escolha um item só pelo teclado; o painel embaixo conta o que o filtro deixou passar e quanto tempo levou.
Pacote
Abrir no capítuloConstruir formulários e estados de interaçãocmdknumber-flow
Animar indicadores que mudam ao vivo com formato pt-BR
Veja três indicadores fictícios rolarem a cada troca e compare com o número em texto puro. Pause, reinicie e observe o separador de milhar.
Pacote
Abrir no capítuloProjetar gráficos e painéis pela decisão@number-flow/reactApache ECharts
Medir o custo de desenhar 200 mil pontos com o ECharts
Troque o tipo de gráfico e o volume de pontos, leia o tempo de desenho e alterne o eixo em zero. Mude o tema do site e veja as cores refazerem.
Pacote
Abrir no capítuloProjetar gráficos e painéis pela decisãoechartsApache ECharts
Painel grande com visões coordenadas
Clique num canal para filtrar todas as visões, troque a densidade entre 6, 9 e 12 visões, alterne tema e movimento e abra a tela cheia.
Pacote
Abrir no capítuloProjetar gráficos e painéis pela decisãoechartssharp e svgo
Escolher a variante certa da imagem e conferir o teto de 150 KB
Arraste a largura da tela simulada, troque a densidade entre 1x e 2x e veja qual arquivo o navegador escolhe, quanto ele pesa e se cabe no orçamento.
Pacote
Abrir no capítuloValidar desempenho, autenticação e segurançasharp, svgoReact Flow (xyflow)
Disparar um pedido e ver o orquestrador distribuir, conferir e responder
Alterne paralelo e sequencial, ligue e desligue a verificação e use a medição real; observe o tempo de parede em cada combinação.
Pacote
Abrir no capítuloConstruir as cenas do orquestrador, do paralelismo e do robô@xyflow/reactGSAP, Web Workers e number-flow
Dividir mil tarefas entre trabalhadores reais e correr três ritmos de geração
Execute com um trabalhador, depois com quatro e oito, e compare o tempo; em seguida percorra a corrida e separe a espera inicial do ritmo.
Pacote
Abrir no capítuloConstruir as cenas do orquestrador, do paralelismo e do robôgsap, @number-flow/reactThree.js com React Three Fiber, drei, Rapier e XR
Carregar o braço robótico, ver a física trabalhar e entrar na cena com o visor
Carregue a cena pelo botão, inicie o ciclo, mostre os ângulos das juntas, troque a câmera e a velocidade; com visor, entre em realidade virtual.
Pacote
Abrir no capítuloConstruir as cenas do orquestrador, do paralelismo e do robôthree, @react-three/fiber, @react-three/drei, @react-three/rapier, @react-three/xrMotion
Ver quatro agentes em raias trocando mensagens e a revisão devolvendo um trecho
Reproduza os 60 s de modelo, percorra o tempo pelo controle e esconda as mensagens para comparar a leitura; repare no tempo de parede contra a soma.
Pacote
Abrir no capítuloEspecificar, medir e produzir as cenas da máquinamotionMediaRecorder, Canvas 2D e Long Animation Frames (plataforma)
Medir o quadro da cena e gravar seis segundos dela em vídeo
Suba as partículas, force um bloqueio de 300 ms e leia o medidor; depois grave seis segundos, veja o codec escolhido e baixe o arquivo.
Pacote
Abrir no capítuloEspecificar, medir e produzir as cenas da máquinasem pacotesigma.js, graphology com ForceAtlas2 e cosmos.gl
Ver o grafo real do curso e um grafo de milhares de nós se organizarem em aglomerados
Rode o layout no grafo real, passe o mouse pelos nós e busque uma entidade; troque para 20 mil nós e leia o medidor; depois carregue o modo massivo na placa de vídeo.
Pacote
Abrir no capítuloAnimar um grafo de conhecimento amplo em movimentosigma, graphology, graphology-layout-forceatlas2, graphology-generators, @cosmos.gl/graph