Configurar ambiente, skills e o contêiner de contexto

Um agente de programação, o programa que escreve e testa os arquivos do site a partir de um pedido em português, chega a sugerir um pacote inexistente. Alguém registra esse nome inventado antes de você, e o pacote falso já somou mais de 30 mil downloads em três meses.

A defesa cabe em quatro estações montadas na sua máquina e numa pergunta feita antes de cada pedido. A pergunta é simples: existe contexto oficial desta biblioteca, o pacote de código pronto que outra empresa mantém, ligado ao agente? Quem responde na primeira sessão evita o comando inventado; quem pula descobre semanas depois qual sugestão veio da fonte errada.

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.

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.

Antes de qualquer pedido sobre uma biblioteca grande, confirme se existe contexto oficial dela conectado ao agente. Essa ligação é o MCP, o protocolo de contexto, o canal por onde o agente consulta a documentação do fornecedor em vez da memória de treino.

O motivo é medido. Numa pesquisa sobre código gerado, 5,2% dos nomes de pacote sugeridos por modelos comerciais não existiam, e nos modelos abertos a proporção subiu para 21,7%. Um em cada cinco nomes inventados já basta para você conferir antes de instalar.

Numa oficina mecânica que liga um meio de pagamento ao site, o comando de cobrança inventado só aparece no primeiro teste com cartão de verdade. O critério vira o do fornecedor: sem contexto oficial ligado, o pedido espera.

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.

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 instalado pelo nome que apareceu numa conversa roda comandos na sua máquina com o seu privilégio de usuário. Plugin é o pacote que adiciona funções novas ao assistente, e admitir um sem conferir a origem equivale a contratar um fornecedor sem pedir referência.

Pesquisadores da Universidade de Tel Aviv mostraram, em julho de 2026, que um assistente de IA repete o nome de um pacote que não existe. Quem registra esse nome antes recebe a instalação de todo mundo que confiou na sugestão.

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.

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.

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.

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.

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.

Quem monta essas sete camadas na ordem certa evita a tela genérica que o modelo viu no treino. Quem inverte a ordem recebe o padrão do autor da peça copiada. Depois da primeira montagem, o pedido de cada página nova cabe em dez linhas.

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.

A ordem de montagem decide se a tela sai com a sua marca ou com o padrão do treino. Peças antes das regras devolvem o estilo do autor da peça; regras antes das peças devolvem a sua marca. Monte o contêiner em sete camadas, nesta sequência.

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 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.

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.

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.

Aplicar os recursos ao projeto