Uma skill começa pequena: objetivo, entradas, passos e entrega. Depois chegam novas regras, exemplos, modelos de relatório e comandos. Em pouco tempo, o arquivo principal parece um manual inteiro. Separar tudo em pastas pode aliviar a leitura, mas também cria outro problema: o procedimento passa a depender de documentos que ninguém sabe quando consultar.
Este capítulo trata dessa distribuição. Vamos distinguir instruções, referências, modelos e scripts, usando a revisão fictícia da prévia de importação em Delphi que acompanha a série. A proposta não é montar a maior estrutura possível. É organizar cada recurso conforme seu papel e manter visíveis as decisões essenciais, inclusive quando algum material estiver ausente.
Essa organização exige entender o trabalho antes de automatizá-lo. Em SDD em Delphi, a apresentação relaciona especificações, contratos e critérios de aceitação à construção de software. A página oferece uma degustação para avaliar o aprofundamento. A ligação com este artigo é concreta: um procedimento só pode buscar evidência útil quando sabe qual comportamento deve examinar.
Um arquivo principal não precisa conter tudo
Skill é um pacote reutilizável de instruções para uma tarefa, eventualmente acompanhado de materiais de apoio. O arquivo principal deve explicar o que fazer, quando o procedimento é pertinente, quais limites respeitar e como reconhecer a entrega. Os recursos adicionais existem para apoiar esse trabalho, não para esconder sua finalidade em uma sequência de links.
A documentação oficial de criação de skills apresenta SKILL.md como arquivo obrigatório e descreve pastas opcionais para documentação, scripts e recursos, como modelos. Também explica o carregamento progressivo: os metadados aparecem antes das instruções completas. Aqui, utilizaremos essa estrutura documentada como referência, distinguindo-a das convenções autorais propostas para nosso exemplo.
Carregamento progressivo significa disponibilizar detalhes conforme a necessidade, em vez de tratar toda informação como igualmente pertinente desde o início. Isso não quer dizer que uma referência deve ser lida parcialmente quando suas instruções são necessárias. A seleção acontece entre recursos e modos de trabalho; uma orientação essencial não pode desaparecer porque ficou em um arquivo pouco evidente.
Para quem programa em Delphi, a comparação com a separação de responsabilidades ajuda. Uma unidade pode ter uma função bem definida, em vez de reunir persistência, apresentação e todas as regras. A analogia tem limite: um documento de instruções não é um módulo compilado, e um link não impõe dependência técnica. Sua organização ainda precisa ser compreendida e verificada no ambiente do agente.
Separe pela função, não pelo tamanho

Infográfico ilustrativo gerado por IA. Organização autoral das funções; recursos opcionais, não etapas obrigatórias nem arquivos executados.
Uma referência é um documento consultado para compreender regras, contexto ou detalhes necessários. No exemplo, pode explicar como a prévia trata códigos vazios e espaços. Um modelo de saída organiza o resultado a produzir, como as seções de um relatório. Um script é um programa executável para uma operação definida. Instruções, por sua vez, coordenam o uso desses elementos na tarefa.
Não mova um trecho apenas porque ele aumentou o arquivo. Pergunte o que ele faz. A regra que impede a revisão de modificar dados pertence aos limites centrais. Um catálogo de formatos de importação pode ser uma referência, consultada quando o formato relevante estiver identificado. Um relatório vazio pode ser modelo, mas uma conclusão pronta de aprovação não é um modelo neutro.
Essa distinção evita confundir exemplo com obrigação. Uma amostra de relatório pode demonstrar como explicar um achado; não precisa impor os mesmos parágrafos em toda execução. Se a tarefa não teve acesso aos testes, a saída deve registrar a limitação, mesmo que o exemplo mostre um resultado de execução. O formato serve à evidência, não força uma evidência inexistente.
Também não coloque segredos em uma referência para facilitar a execução. Configuração e documentação podem indicar como o acesso é fornecido, sem conter credenciais. A presença de um arquivo dentro do pacote não torna seu conteúdo seguro para leitura, envio ou publicação. Distribuir recursos aumenta o que precisa ser revisado, inclusive sua procedência e sensibilidade.
Uma estrutura proporcional à revisão
Podemos imaginar a seguinte organização para uma versão ampliada da skill de revisão. A árvore é ilustrativa e não foi instalada neste projeto. Os nomes de pasta acompanham a documentação citada; os nomes e conteúdos dos arquivos são convenções fictícias do exercício.
revisar-previa-importacao/
SKILL.md
references/
contrato-da-previa.md
assets/
modelo-de-relatorio.md
scripts/
conferir-registros.mjsO contrato da prévia define os comportamentos a preservar. Contrato, neste contexto, é um acordo explícito sobre entradas, resultados e limites, não necessariamente um documento jurídico. O modelo do relatório organiza achados, verificações e limitações. O script, se vier a ser implementado e testado, poderá conferir uma propriedade mecânica dos registros sintéticos. Sua existência não substituiria a análise do código.
A pasta de scripts só deve aparecer quando houver uma operação concreta que justifique mantê-la. A árvore demonstra funções possíveis, não uma lista de arquivos obrigatórios. Uma skill que apenas orienta uma revisão pode continuar sem código executável. Acrescentar um programa para dar aparência de automação cria dependências e riscos sem garantir benefício.
No artigo sobre instruções de projeto e skills, a separação entre orientação permanente e procedimento é importante. Aqui ela se estende aos recursos: documentação geral do projeto não precisa ser copiada inteira para cada skill. Uma referência mantida em um lugar pode ser indicada, desde que o caminho e a condição de acesso sejam claros.
Diga quando consultar cada recurso
Um índice de links não basta. A instrução deve ligar uma situação a uma consulta e explicar o que fazer quando ela não for possível. Se a revisão depende do contrato da prévia, a consulta precisa acontecer antes da conclusão. Se o documento não estiver disponível, a entrega deverá registrar essa limitação, sem inventar as regras ausentes.
Um trecho ilustrativo das instruções poderia ser:
## Recursos da revisão
Antes de avaliar a mudança na prévia, leia
[o contrato da prévia](references/contrato-da-previa.md).
Os caminhos deste pacote são relativos à pasta da skill.
Para organizar a entrega, use
[o modelo de relatório](assets/modelo-de-relatorio.md),
preenchendo somente informações verificadas.
Se uma referência necessária estiver indisponível,
explique a limitação antes de concluir.O trecho define uma convenção explícita para caminhos relativos: o ponto de partida é a pasta da skill. Não presumimos que qualquer ferramenta resolverá automaticamente o link dessa maneira. Na aplicação real, confira como o ambiente acessa os arquivos. Um caminho que funciona em uma demonstração não comprova portabilidade para outra máquina ou instalação.
Para uma referência usada somente em um caso particular, indique esse caso. Por exemplo, um documento sobre cancelamento da importação não precisa orientar uma revisão restrita à identificação de campos vazios, a menos que a alteração também afete cancelamento. Ler tudo por padrão pode trazer regras de outro cenário; ler de menos pode eliminar uma condição necessária.
Essa seleção está relacionada à engenharia de contexto. A organização dos arquivos precisa responder à necessidade da tarefa. Não estamos buscando uma pasta elegante, mas informação suficiente e pertinente para sustentar as decisões do revisor.
Modelos devem abrir espaço para limitações
Um modelo útil facilita a entrega sem decidir seu conteúdo. Para nosso relatório, podemos reservar campos para alteração examinada, achados, evidências, testes executados e limitações. O campo de testes não começa com “todos passaram”. Ele permite registrar execução, leitura de testes existentes ou impossibilidade de execução, situações que produzem evidências diferentes.
Um modelo que exige uma conclusão positiva cria pressão para preencher algo que pode não ser verdadeiro. Prefira perguntas e campos que representem o trabalho realizado. “Quais verificações foram executadas?” permite responder com precisão. “Por que a mudança está aprovada?” presume uma decisão que talvez a revisão não sustente e que pode depender de outra pessoa.
Evite espalhar a mesma regra pelo modelo, pelo contrato e pelo arquivo principal. Se a condição para rejeitar código vazio estiver em três locais, uma atualização pode deixar versões incompatíveis. Mantenha a definição em um lugar e faça os demais recursos apontarem para ela. O modelo pede a evidência; a referência define a regra; o procedimento explica como examiná-la.
Scripts precisam de um contrato próprio
Um script pode ser adequado quando a operação precisa seguir uma regra definida e produzir resultado verificável, como conferir se um arquivo de teste contém os campos esperados. Isso não significa que todo trabalho mecânico merece um novo programa. Considere se uma ferramenta já existente resolve a necessidade com menos manutenção e se o ambiente dispõe das dependências exigidas.
Antes de executar, descreva entradas, saídas e efeitos. O script lê dados ou também grava? Precisa de rede? Como informa um erro? Onde cria arquivos? Essas perguntas são especialmente importantes quando o agente pode executar comandos. Uma orientação de revisão não deve autorizar silenciosamente um programa que modifica dados de produção.
O nome conferir-registros.mjs na árvore é apenas ilustrativo; nenhum programa com esse comportamento foi executado neste capítulo. Para uma implementação futura, utilize dados sintéticos e confira casos válidos, inválidos e arquivos inesperados. Informe o alcance do ensaio. Um verificador de estrutura dos registros não prova que o sistema Delphi preserva a transação nem que a skill foi acionada corretamente.
Essa distinção complementa os limites dos testes gerados por IA. Código executado produz evidência sobre a operação e os casos efetivamente examinados. Não transforma um relatório parcial em aprovação de toda a aplicação. O agente precisa interpretar o resultado sem ampliar a conclusão.
Mantenha o pacote pequeno e rastreável
Ao revisar a organização, percorra cada arquivo perguntando quem o utiliza e em qual situação. Um recurso sem ligação com o procedimento pode estar esquecido. Um arquivo utilizado por vários modos precisa preservar seu significado em todos eles. Antes de remover algo, examine seus consumidores; a ausência de referência evidente não garante que ele não seja usado por outro processo.
Registre mudanças relevantes na regra e nas condições do ambiente. Se o contrato mudou, os exemplos e ensaios podem precisar de atualização. Não basta trocar o arquivo principal e deixar um modelo que ainda presume o comportamento anterior. Organização é uma responsabilidade de manutenção, não uma etapa única na criação da skill.
Quando separar aumenta mais a navegação do que a clareza, simplifique. Um arquivo de poucas páginas não precisa virar uma biblioteca de fragmentos. O critério é tornar a tarefa compreensível, reduzir duplicações e permitir verificar as dependências. Se a estrutura não ajuda a responder onde a regra está e quando consultá-la, ela precisa ser revista.
Conclusão
Organizar uma skill é distribuir responsabilidades: instruções coordenam, referências explicam, modelos organizam a entrega e scripts executam operações delimitadas. Essa separação só ajuda quando os vínculos são claros e os limites continuam visíveis. Uma árvore de diretórios não garante que a informação necessária será consultada nem que um comando produzirá evidência suficiente.
Comece pelo procedimento que funciona e separe apenas o que tem função própria. Para aprofundar a definição dos comportamentos que uma revisão deve preservar, conheça SDD em Delphi. O aprendizado central é manter cada recurso subordinado à tarefa e à evidência: o pacote deve facilitar o trabalho, não criar uma nova camada de ambiguidades.
Referências
OPENAI. Build skills. ChatGPT Learn, [s. d.]. Disponível em: https://learn.chatgpt.com/docs/build-skills. Acesso em: 4 out. 2026.
SILVEIRA, Régys Borges da. AGENTS.md, instruções e skills: como orientar uma IA dentro do projeto. regys.com.br, 2026. Disponível em: https://regys.com.br/agents-md-instrucoes-e-skills-como-orientar-uma-ia-dentro-do-projeto/. Acesso em: 4 out. 2026. Rascunho agendado consultado no acervo editorial.
SILVEIRA, Régys Borges da. Como gerar testes com IA e descobrir quando eles não provam nada. regys.com.br, 2026. Disponível em: https://regys.com.br/como-gerar-testes-com-ia-e-descobrir-quando-eles-nao-provam-nada/. Acesso em: 4 out. 2026. Rascunho agendado consultado no acervo editorial.
SILVEIRA, Régys Borges da. Engenharia de contexto: por que um bom prompt não basta para programar com IA. regys.com.br, 2026. Disponível em: https://regys.com.br/engenharia-de-contexto-por-que-um-bom-prompt-nao-basta-para-programar-com-ia/. Acesso em: 4 out. 2026. Rascunho agendado consultado no acervo editorial.
SILVEIRA, Régys Borges da. SDD em Delphi. Livros de Régys Borges da Silveira, [s. d.]. Disponível em: https://livros.regys.com.br/sdd-em-delphi. Acesso em: 4 out. 2026.



0 comentário(s)