Configurar ambiente, skills e o contêiner de contexto

Um agente de codificação, o programa que edita e testa arquivos a partir de um pedido escrito, sugeriu um nome de pacote que não existia. Registrado por quem explorou a brecha, esse pacote já somou mais de 30 mil downloads em três meses.

A guarda cabe em quatro estações montadas na máquina e numa checagem antes de qualquer pedido sobre biblioteca grande: existe contexto oficial dela ligado ao agente. Quem cumpre a checagem na primeira sessão evita o comando inventado; quem pula descobre semanas depois, na revisão, qual sugestão veio da fonte errada.

A primeira estação é o agente, aberto no terminal dentro da pasta do projeto. A segunda é 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 navegador, que o próprio agente abre para ler erros e medir contraste. A quarta é o histórico de alterações (o registro de cada mudança, como o extrato de uma conta), que permite desfazer um erro sem refazer o trabalho todo.

Uma quinta peça, opcional, encurta o ciclo: o servidor de linguagem, o serviço que sublinha erro de tipo no editor. Ligado ao agente, ele devolve a lista de problemas após cada edição, e o agente conserta no mesmo turno.

Com a máquina digitando, o seu gargalo passa a ser descrever. 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: a instrução chegou incompleta.

Cada tela que funciona vira um commit (o ponto de retorno gravado no histórico, com uma mensagem dizendo o que mudou). Voltar ao estado anterior custa um comando, e meio dia de mudanças num registro só esconde qual delas quebrou a tela.

Confirme, antes de qualquer pedido sobre uma biblioteca grande, se existe contexto oficial dela conectado ao agente. Essa ligação é o MCP (o protocolo de contexto, o canal pelo qual o agente consulta uma fonte externa em vez da memória de treino).

A medida que sustenta esse cuidado é desconfortável. Numa pesquisa com 576 mil amostras de código, 5,2% dos nomes de pacote sugeridos por modelos comerciais não existiam; nos modelos abertos a proporção subiu para 21,7%.

Numa oficina que integra um meio de pagamento ao site, o método de cobrança inventado só aparece no primeiro teste com cartão de verdade. O critério, então, é o do fornecedor: sem contexto oficial ligado, o pedido espera.

O contexto oficial mais barato de ligar hoje é uma skill (a pasta de instruções que o agente lê quando a tarefa combina com a descrição dela). O repositório anthropics/skills reúne 19 delas, publicadas pela própria Anthropic, e tinha 173.551 estrelas e 20.593 forks em 3 de setembro de 2026.

A instalação universal é um comando: npx skills add https://github.com/anthropics/skills --skill frontend-design. Ele grava a pasta em ~/.agents/skills/ e cria um atalho em ~/.claude/skills/, o que serve a qualquer agente que leia esse diretório. A aula seguinte trata da portaria dessa instalação.

Quando o fornecedor da API não publicou contexto nenhum, a saída é construir o próprio servidor de contexto, e a skill mcp-builder do mesmo catálogo diz como. Ela recomenda TypeScript, transporte streamable HTTP sem estado para servidor remoto e stdio (a entrada e a saída padrão do terminal) para servidor local.

Duas regras dessa skill evitam a maior parte do retrabalho. Toda ferramenta exposta leva um prefixo consistente 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, como "faltou o parâmetro cliente_id", 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 anthropics/skills 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.

Instale plugin e skill sem cair no pacote de nome inventado

Um plugin instalado pelo nome sugerido numa conversa registra comandos e conexões que rodam com o seu privilégio na sua máquina. O alcance é o de admitir um fornecedor novo sem checar referência.

Pesquisadores da Universidade de Tel Aviv mostraram, em julho de 2026, que um assistente de IA gera, com consistência, 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 SKILL.md: instruções em texto que o agente lê quando a tarefa combina com a descrição dela, sem instalar programa nenhum. O plugin é o pacote maior, que pode trazer skills, comandos, conexões MCP e ganchos que rodam com o seu privilégio na sua máquina.

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

Três defesas cobrem a maior parte desse risco, cada uma limitando o que a anterior deixa passar. Instalar só de catálogo autorizado limita a origem. Ler o que o pacote adiciona limita a surpresa, e escolher o escopo mais restrito limita o estrago quando as duas primeiras falham.

O escopo é o alcance da instalação. A pasta do projeto vale só para aquele repositório; a 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. O universal é npx skills add https://github.com/anthropics/skills --skill frontend-design, que grava em ~/.agents/skills/ e cria um atalho em ~/.claude/skills/. No Claude Code existe também /plugin marketplace add anthropics/skills, seguido de /plugin install example-skills@anthropic-agent-skills.

O instalador avisa em inglês: "Review skills before use; they run with full agent permissions". A frase diz que a skill orienta o mesmo agente que grava arquivos e roda comandos, então uma instrução maliciosa no SKILL.md tem o alcance do próprio agente.

A frontend-design, a mais instalada do catálogo, somava 849,9 mil instalações no registro skills.sh em 3 de setembro de 2026.

O custo de uma skill se mede por turno, e a skill-creator do mesmo catálogo explica a conta pela divulgação progressiva em três níveis.

O nome e a descrição de toda skill instalada ficam sempre no contexto, cerca de 100 palavras. O corpo do SKILL.md 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 na tarefa que nenhuma delas atende. É por isso que a descrição precisa ser insistente 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 em YAML com name e description) diz quando ela dispara. O corpo diz o que ela manda o agente fazer. A pasta scripts/, quando existe, contém 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 repositório, é 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 chave costuma parar esquecida. O lugar dela é a variável de ambiente, fora do arquivo versionado.

Antes de confirmar qualquer instalação, decida o que o pedido exige: orientação em texto, a skill, ou comando e conexão novos, o plugin, que pede portaria mais rígida.

Instale pelo caminho oficial, leia frontmatter, corpo e 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.

O prompt como contêiner: DESIGN.md, registro e referência no mesmo pedido

O pedido de tela virou um contêiner de contexto. No mesmo prompt, o pedido escrito que você manda ao agente, entram o arquivo de sistema, o catálogo de componentes e as referências.

Na ferramenta de desenho por pedido Aura, uma referência com arroba acrescenta até 100 mil caracteres numa só mensagem, cerca de duas mil linhas. Um template inteiro cabe em 31 mil caracteres.

Quem monta essas sete camadas na ordem certa evita telas com o mesmo herói genérico do treino; quem inverte a ordem devolve o padrão do autor do componente. O pedido de cada página nova, depois da primeira montagem, cabe em dez linhas.

O exemplo da própria documentação troca "crie uma landing page" por "crie usando @hero-template-01 @pricing-cards e aplique o trecho @border-gradient"; a edição direcionada muda só a parte pedida. O catálogo tem mais de mil templates e 1.400 componentes.

O fornecedor passou a escrever para o agente do cliente. O Unicorn Studio, editor de cenas animadas, publica um unicornstudio-llms.txt, documento em que o agente lê como integrar a cena com segurança e desempenho.

O Refero MCP (MCP é o protocolo que dá ferramentas ao agente) pesquisa telas e fluxos reais antes de construir. O Refero Styles exporta o resultado como DESIGN.md. No 21st.dev cada componente é um prompt copiável, e os MCP do 21st e do shadcn dão ao agente busca e instalação.

A GetLayers vende o template de landing page como prompt, parte grátis e parte paga. O risco é o de sempre: template de prompt continua template.

A ordem de montagem decide se a tela sai com repertório ou com default. Componentes antes do sistema devolvem o padrão do autor do componente; sistema antes dos componentes devolve a marca. Monte o contêiner em sete camadas, nesta sequência.

Primeiro, o assunto, o público e a tarefa, como no briefing da trilha 1. Segundo, o DESIGN.md do projeto, o arquivo de sistema com valores e porquê.

Sem ele, dois ou três DESIGN.md de vizinhos do Refero entram como referência de leitura, 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 (o catálogo 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 etiquetas na lata de tinta) para a adaptação sair no mesmo passo.

Quinto, uma assinatura de movimento. Sexto, a copy. Sétimo, a crítica com print e um cenário fixo, repetido a cada mudança.

Contexto grande custa token e atenção, e o agente lê pior o que decide quando afoga no que só descreve. A Vercel faz o agente nunca ler a folha de estilo: 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, a restrição) e resuma o resto em uma linha. A skill frontend-design lê o contêiner de dentro do agente, instalada como a aula anterior mostrou.

Em 8 de setembro de 2026 ela era a mais instalada do catálogo, com cerca de 850,9 mil instalações no skills.sh, contra 834 mil em 30 de agosto.

O pedido-modelo abaixo monta as sete camadas para a página de matrícula de uma escola de música fictícia. Ele referencia o DESIGN.md em vez de repetir valores, cita dois componentes do registro pelo nome, proíbe os padrões pelo nome e fecha com o critério de aceite. Troque os nomes pelos do seu projeto.

A escola de música 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 de parede e a regra de usá-lo só no botão.

Três componentes do registro ficam renomeados com o prefixo da escola e adaptados aos tokens. 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: sistema, restrições nomeadas, componentes do registro escolhidos depois do sistema e um cenário congelado como cenario-01. 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, não no arquivo.