A equipe pede que a IA preserve assinaturas públicas, evite dependências novas e execute os testes existentes. Na tarefa seguinte, repete as mesmas orientações. Algumas ficam esquecidas; outras aparecem em mensagens diferentes e passam a se contradizer. O problema não é apenas escrever melhor o pedido, mas manter um lugar confiável para o conhecimento que deve acompanhar o trabalho.
Este é o terceiro artigo da série IA na prática: do protótipo à operação responsável. Depois de organizar o contexto, vamos separar instruções de projeto, procedimentos reutilizáveis e a solicitação específica de cada tarefa. O objetivo é entender AGENTS.md e skills sem tratá-los como mecanismos mágicos de controle ou autorização.
Um arquivo de instruções ganha utilidade quando suas orientações podem ser ligadas a requisitos, código e evidência de revisão. SDD em Delphi desenvolve essa ligação por meio de especificações, contratos, critérios de aceite e rastreabilidade, inclusive no trabalho com apoio de IA. Conheça a proposta e leia a degustação gratuita para avaliar como organizar o método no seu projeto, em vez de apenas acumular regras em arquivos. Para estudar as camadas de contexto, ferramentas e operação que cercam essas instruções, a leitura complementar é IA Além da Conversa.
Três conceitos antes dos arquivos
Uma instrução de projeto descreve como trabalhar naquela base: ambiente, convenções, limites e verificações. Uma solicitação de tarefa descreve o resultado desejado em um caso concreto. Uma habilidade reutilizável, chamada skill, organiza um procedimento que pode ser aplicado quando determinada situação aparece. Esses elementos se complementam, mas não devem disputar a mesma responsabilidade.
Um agente de programação combina um modelo de linguagem com ferramentas para realizar etapas de trabalho. O modelo interpreta instruções e informações; o aplicativo ao redor decide quais arquivos e ferramentas ficam disponíveis. Uma regra escrita orienta o comportamento, mas não cria, sozinha, uma restrição técnica de acesso.
AGENTS.md é um arquivo Markdown, formato textual usado para organizar títulos, parágrafos e listas. O site do formato o apresenta como um local previsível para fornecer contexto e instruções a agentes de programação. A ideia é complementar a documentação do projeto com orientações voltadas a esse modo de colaboração.
A compatibilidade precisa ser conferida na ferramenta escolhida. Não presuma que qualquer aplicativo lê o arquivo automaticamente ou aplica as mesmas regras de descoberta e precedência. Precedência é a ordem usada para resolver instruções concorrentes. Um padrão comum não elimina diferenças de implementação, configuração e autoridade.
AGENTS.md: o que vale para o projeto
Como proposta editorial, um arquivo inicial pode explicar o produto, o ambiente de desenvolvimento, o modo de compilar e testar e as mudanças que exigem revisão. A finalidade é dar ao agente condições de localizar o trabalho e reconhecer limites. Não é necessário copiar toda a documentação técnica para esse arquivo.
Em uma aplicação Delphi, registre a versão usada pela equipe, componentes que fazem parte do ambiente e convenções relevantes. Informe quais projetos devem ser compilados, quando essa operação está disponível e como identificar seus resultados. Não transforme “o projeto costuma compilar” em evidência de que a alteração atual foi compilada.
Declare também situações que exigem parada. Uma mudança no esquema do banco, uma dependência nova ou a alteração de uma interface pública pode requerer autorização específica. Se essa é a regra da equipe, escreva o critério e o que fazer quando ele aparece: apresentar a necessidade e aguardar decisão.
O site do formato admite arquivos em diferentes partes de um repositório. Repositório é o conjunto de arquivos e histórico mantido pelo controle de versões. Para evitar extrapolações, confirme como seu agente combina orientações gerais e locais. Não deduza que o arquivo mais próximo sempre supera qualquer instrução do produto ou regra de segurança.
Minha recomendação é começar com uma orientação geral e acrescentar regras locais somente quando houver uma diferença real. Dois arquivos que repetem a mesma regra com palavras distintas podem divergir depois de uma atualização. A estrutura deve reduzir ambiguidades, não criar um regulamento difícil de manter.
Skills: procedimentos carregados quando fazem sentido
Uma skill é um pacote de instruções e recursos para uma finalidade específica. A especificação Agent Skills descreve uma pasta com um arquivo SKILL.md e, opcionalmente, scripts, referências e outros materiais. O nome identifica a habilidade; a descrição informa o que ela faz e quando deve ser usada.
Nesse formato, o arquivo começa com metadados em YAML, uma representação textual de campos e valores, seguidos de instruções em Markdown. Os campos obrigatórios incluem name e description. Esse é o contrato documentado do formato consultado em 2 de outubro de 2026, não uma regra para qualquer recurso chamado “skill” em outro produto.
A especificação apresenta carregamento progressivo: o agente pode identificar a habilidade por seus metadados, ler as instruções quando necessário e consultar recursos relacionados durante a tarefa. Isso não significa que todo conteúdo de toda habilidade permanece simultaneamente no contexto, nem que os recursos serão utilizados corretamente em qualquer situação.
A apresentação da Anthropic sobre Agent Skills explica a proposta de reunir conhecimento procedural em arquivos e recursos. A mesma publicação recomenda examinar habilidades de origem não confiável, especialmente scripts e acessos externos. Instalar um procedimento pronto também é uma decisão de confiança.
Um exemplo: revisar a prévia de importação
Retomemos a prévia fictícia de importação de pedidos usada nos capítulos anteriores. O demonstrador recebe registros inventados, preserva sua ordem e identifica informações ausentes. Agora a equipe precisa revisar alterações nessa rotina com frequência. Esse procedimento é um candidato à organização em uma habilidade reutilizável.
No AGENTS.md, ficam as regras gerais: ambiente Delphi declarado, proibição de dados reais nos exercícios e necessidade de informar quais verificações foram executadas. Na solicitação atual, fica o problema específico: a prévia está classificando um campo com espaços como preenchido. A skill, se adotada, orienta a revisão desse tipo de alteração.
O procedimento pode começar pedindo a identificação da regra afetada e dos pontos que a utilizam. Depois solicita comparação entre comportamento anterior e proposto, exame de casos de fronteira e verificação de mensagens apresentadas. Casos de fronteira são entradas próximas dos limites definidos, como um campo vazio ou preenchido somente com espaços.
A entrega esperada pode ser uma revisão com evidências, riscos e testes pendentes. A habilidade não deve inventar a regra comercial: precisa receber a especificação válida. Também não deve autorizar gravação de pedidos, instalação de bibliotecas ou modificação de rotinas não relacionadas. Sua finalidade é revisar um fluxo delimitado.
Esse desenho é ilustrativo e não foi instalado ou executado em um agente nesta produção. A proposta permite avaliar se um procedimento recorrente merece ser empacotado. Se a equipe ainda não conhece as etapas de revisão, escrever uma skill não substitui construir e conferir esse entendimento.
Não confunda arquivo, ferramenta e permissão
Uma ferramenta é uma capacidade exposta pelo aplicativo: consultar arquivos, executar um teste ou acessar uma API, interface de comunicação entre programas. A instrução pode explicar quando utilizá-la. A permissão determina se a operação é autorizada. Misturar essas camadas torna difícil avaliar o que o agente realmente pode fazer.
Uma skill que contém um script não garante que sua execução será permitida, segura ou compatível com o ambiente. Script é código executável para realizar uma tarefa. Revise a origem, as dependências e as operações antes de conceder acesso, sobretudo quando houver rede, arquivos sensíveis ou mudanças em dados.
A especificação Agent Skills contém um campo experimental relacionado às ferramentas permitidas e avisa que o suporte pode variar. Não o apresente como uma barreira universal. A aplicação deve aplicar seus próprios controles e explicar ao usuário o alcance efetivo das permissões, em vez de depender de uma declaração dentro do pacote.
MCP, protocolo de integração entre aplicações de IA e capacidades externas, será tratado mais adiante na trilha. Aqui basta distinguir seu papel: conectar uma capacidade não é o mesmo que ensinar um procedimento. Uma equipe pode precisar de instruções para uma ferramenta, mas essa orientação não substitui o contrato e a autorização da ferramenta.
Figura: organização autoral das responsabilidades. Orientações textuais não substituem controles técnicos de autorização.
Como escrever regras que possam ser verificadas
Prefira uma regra que descreva uma ação observável. “Mantenha a qualidade” é uma intenção legítima, mas não explica como conferi-la. “Informe o resultado da compilação e dos testes, distinguindo execução de sugestão” permite verificar se a entrega representa corretamente o trabalho realizado.
Evite absolutos que o ambiente não consegue cumprir. Se o compilador não estiver disponível, o agente deve registrar a limitação e indicar a verificação pendente. Isso é diferente de dispensar o teste silenciosamente. A regra precisa contemplar tanto a condição ideal quanto o comportamento seguro quando ela não existe.
Use exemplos para esclarecer diferenças reais, não para transformar o arquivo em uma coleção de casos sem estrutura. Para a importação, um exemplo de campo obrigatório ausente ajuda a entender o procedimento. Já uma lista extensa de regras comerciais pertence à especificação do fluxo, com origem e versão identificadas.
Também declare o que não deve ser decidido pelo agente. Quando duas interpretações alteram o comportamento de clientes, ele pode apresentar alternativas, mas não escolher silenciosamente uma regra nova. Uma instrução útil protege a decisão humana e preserva a rastreabilidade do motivo da mudança.
Avalie o procedimento antes de multiplicá-lo
Escolha uma tarefa conhecida e observe como as instruções são utilizadas. O agente encontrou o arquivo esperado? A habilidade foi identificada pela descrição? A resposta respeitou o escopo? Os recursos consultados tinham relação com o problema? Esse acompanhamento é uma proposta de avaliação, não uma garantia oferecida pelo formato.
Inclua um caso em que a skill não deveria ser acionada. Uma habilidade de revisão de importação não precisa participar de uma alteração puramente visual sem relação com esse fluxo. Se for ativada indiscriminadamente, sua descrição pode estar ampla demais ou a integração pode não distinguir bem os contextos.
Inclua também uma informação ausente. O comportamento correto pode ser pedir a regra necessária, em vez de propor uma implementação presumida. Quando o procedimento estimula respostas confiantes em situações incompletas, ele precisa ser revisado. Formalizar uma instrução não torna sua orientação adequada automaticamente.
Acompanhe o custo de manutenção. Uma mudança na versão do compilador ou nos comandos de teste precisa chegar ao arquivo relevante. Defina um responsável pela atualização e revise orientações junto com as mudanças do projeto. Um manual desatualizado pode ser mais convincente que uma lacuna explícita, justamente porque parece oficial.
Cuidados com pacotes de terceiros e instruções conflitantes
Não instale uma habilidade apenas porque foi recomendada em uma conversa. Leia os arquivos e examine o código que pode ser executado. Uma descrição promissora não demonstra que os recursos fazem somente aquilo. Se não houver condições de revisar o pacote, mantenha a integração sem ele até obter evidência suficiente.
Uma instrução incorporada a um documento consultado também não deve receber autoridade automática. A OWASP trata a injeção de instruções em conteúdo externo como um risco. Essa fronteira precisa aparecer na revisão de materiais que serão carregados como parte de uma tarefa.
Quando orientações oficiais do projeto entram em conflito, torne a divergência visível. Se uma regra permite alterar uma interface e outra exige autorização, a equipe deve resolver o caso antes da mudança. O agente não deve ocultar a escolha nem usar a ambiguidade para ampliar seu escopo.
Como esta etapa se conecta à trilha
O artigo sobre engenharia de contexto mostrou como selecionar informações para uma tarefa. AGENTS.md e skills ajudam a organizar parte desse material, mas não substituem os trechos relevantes, os resultados de ferramentas e o estado atual da investigação.
A abertura sobre vibe coding estabeleceu a diferença entre explorar e assumir responsabilidade por um resultado. As instruções são uma continuação dessa postura: transformam acordos em referências que podem ser examinadas e atualizadas, sem abandonar a revisão da implementação.
No próximo capítulo, a série aplicará esses cuidados a um projeto Delphi existente. A tarefa será escolher uma alteração pequena, preservar comportamentos e registrar evidências. Ter instruções bem organizadas ajuda a começar, mas a decisão final dependerá do que o ambiente e os testes efetivamente demonstrarem.
Conclusão
AGENTS.md organiza orientações do projeto; a solicitação descreve o objetivo atual; uma skill reúne um procedimento reutilizável. Separar esses papéis ajuda a manter contexto e a reduzir repetição, desde que a ferramenta realmente suporte os formatos e que as instruções sejam mantidas como parte do trabalho.
Comece pelas regras que mais se repetem e pelos procedimentos que a equipe já consegue explicar. Escreva critérios observáveis, teste situações relevantes e registre limitações. Não multiplique arquivos apenas para parecer que o projeto está preparado para agentes.
A principal fronteira permanece fora do texto: instrução não é autorização. Ferramentas, scripts e integrações precisam de controles próprios, revisão e escopo. Quando essa separação fica clara, arquivos de orientação deixam de ser um conjunto de promessas e passam a apoiar uma colaboração verificável.
Transformar orientações em prática exige ligar cada regra a uma decisão verificável, não apenas manter mais arquivos. SDD em Delphi aprofunda especificações, critérios de aceite e rastreabilidade entre requisitos, código e testes. A página apresenta sumário e degustação gratuita para quem deseja estruturar essa disciplina em uma equipe Delphi.
Referências
AGENT SKILLS. Specification. Publicação online, [s. d.]. Disponível em: https://agentskills.io/specification. Acesso em: 2 out. 2026.
AGENTIC AI FOUNDATION. AGENTS.md. Publicação online, [s. d.]. Disponível em: https://agents.md/. Acesso em: 2 out. 2026.
ANTHROPIC. Equipping agents for the real world with Agent Skills. Publicação online, 16 out. 2025. Disponível em: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills. Acesso em: 2 out. 2026.
OWASP. LLM01:2025 Prompt Injection. Publicação online, [s. d.]. Disponível em: https://genai.owasp.org/llmrisk/llm01-prompt-injection/. Acesso em: 2 out. 2026.
SILVEIRA, Régys Borges da. Engenharia de contexto: por que um bom prompt não basta para programar com IA. regys.com.br, [s. d.]. Disponível em: https://regys.com.br/engenharia-de-contexto-por-que-um-bom-prompt-nao-basta-para-programar-com-ia/. Acesso em: 2 out. 2026.
SILVEIRA, Régys Borges da. IA Além da Conversa. Livros Régys Borges da Silveira, [s. d.]. Disponível em: https://livros.regys.com.br/ia-alem-da-conversa. Acesso em: 2 out. 2026.
SILVEIRA, Régys Borges da. SDD em Delphi. Livros Régys Borges da Silveira, [s. d.]. Disponível em: https://livros.regys.com.br/sdd-em-delphi. Acesso em: 2 out. 2026.
SILVEIRA, Régys Borges da. Vibe coding: o que é, quando ajuda e quando vira um problema. regys.com.br, [s. d.]. Disponível em: https://regys.com.br/vibe-coding-o-que-e-quando-ajuda-e-quando-vira-um-problema/. Acesso em: 2 out. 2026.
0 comentário(s)