Com a ascensão de IDEs baseadas em IA como o Cursor e o Antigravity, muitos desenvolvedores Delphi sentem que as sugestões da ferramenta às vezes parecem “genéricas” demais ou focadas em padrões de outras linguagens. O segredo para transformar essas ferramentas em um verdadeiro braço direito é a criação de uma Agent Skill.

Neste artigo, vou te ensinar como criar um arquivo de Skill completo que define regras de arquitetura, padrões de codificação e até comportamentos específicos para o ecossistema Delphi.

O que é uma Agent Skill?

Uma Agent Skill (ou .cursorrules) é um arquivo de diretrizes persistentes que serve como o “manual de conduta” para a IA dentro do seu projeto. Em vez de repetir os seus padrões em cada chat, você os define uma única vez. Quando o agente (seja no Cursor ou Antigravity) lê esse arquivo, ele passa a gerar código que respeita desde a nomenclatura das suas variáveis até a gestão de memória manual do Delphi.

Estrutura de uma Skill de Alto Nível

Para que uma Skill seja eficiente, ela deve ser dividida em seções claras. Vamos detalhar cada uma delas:

1. Papel e Identidade (Role)

Aqui você define o nível de senioridade da IA. É a base de todo o comportamento subsequente.

• Por que usar: Define o tom da conversa e o rigor técnico das respostas.

2. Stack Tecnológica e Versões

O Delphi evoluiu muito. Uma IA precisa saber se pode usar variáveis inline (Delphi 10.3+), records avançados ou novos frameworks.

• Por que usar: Evita que a IA sugira sintaxe obsoleta ou bibliotecas que você não utiliza no projeto.

3. Padrões de Nomenclatura (Naming Conventions)

Essencial para manter a consistência do código, especialmente em equipes.

• Por que usar: Garante que o código gerado pareça ter sido escrito por você, respeitando os prefixos T, I, F, L, etc.

4. Gestão de Memória e Idiomatismos

Onde a maioria das IAs erra por estar acostumada com linguagens de Garbage Collection (Java/C#).

• Por que usar: Força a IA a usar try...finally, destruir objetos corretamente e evitar vazamentos de memória.

5. Regras de Arquitetura e Domínio

Aqui você define as “leis” do seu projeto, como o uso de Interfaces ou a proibição de lógica de negócio em formulários.

• Porque usar: Definir as restrições e leis do projeto, limita a IA ao que ela deve e pode fazer seguindo seus padrões e não extrapolando para padrões não esperados.

A Gramática das Skills: Entendendo os Marcadores

Para que o Agente de IA interprete seu arquivo de Skill corretamente, ele utiliza o padrão Markdown. Esses marcadores funcionam como um “mapa de calor” para a atenção da IA. Entender como usá-los evita que as regras se misturem.

1. O Título Principal (#)

O # (H1) deve ser usado apenas uma vez, no topo do arquivo. Ele define o objetivo global da Skill.

• Dica: Use nomes claros como # Delphi Development Skill. Isso diz à IA: “Tudo o que estiver abaixo deste título é a minha prioridade máxima agora”.

2. Seções e Subseções (## e ###)

As hashtags duplas ou triplas definem a hierarquia de importância.

• ## (H2): Use para categorias principais, como ## Memory Management ou ## Naming Conventions.
• ### (H3): Use para sub-regras específicas. Se você tem uma regra geral de nomenclatura, o H3 pode ser usado para ### Database Naming ou ### UI Components.

3. Listas com Marcadores (* ou -)

Os bullet points são interpretados pela IA como restrições (constraints) ou requisitos.

• Quando você usa uma lista, a IA entende que todos os itens ali têm o mesmo peso e devem ser validados antes de entregar o código.
• Exemplo:
  • • Use try...finally.
    • Sempre declare variáveis inline.

4. Citações ou Notas (>)

O símbolo de maior que cria um bloco de citação. No contexto de Skills, ele é excelente para passar contexto extra ou avisos de segurança.

• Exemplo: > IMPORTANTE: Nunca sugira o uso de componentes que exijam licenciamento externo sem o aval do arquiteto.

5. Blocos de Código (Triple Backticks: “`)

Este é o marcador mais importante para o desenvolvedor Delphi.

• Sempre especifique a linguagem após os primeiros três acentos graves: “`delphi.
• Isso força a IA a aplicar o syntax highlighting interno e garante que ela entenda que aquele trecho é um exemplo de código (Blueprint) e não uma instrução de texto.

Exemplo Prático: O Arquivo de Skill Perfeito

Abaixo, apresento um modelo completo que você pode copiar e adaptar para o seu projeto. Este modelo já contempla padrões modernos e boas práticas de Clean Code.

# Role: Senior Delphi Architect & Software Engineer

## 1. Contexto do Projeto
- **Linguagem:** Object Pascal (Delphi 12/13).
- **Frameworks Principais:** VCL (Desktop), FireDAC (Acesso a Dados), ACBr (Fiscal).
- **Arquitetura:** Baseada em Interfaces (SoC) e Injeção de Dependência.

## 2. Padrões de Nomenclatura
- **Classes:** Sempre começar com 'T' (ex: TUsuarioService).
- **Interfaces:** Sempre começar com 'I' (ex: IRepository).
- **Campos Privados:** Sempre começar com 'F' (ex: FQuery: TFDQuery).
- **Variáveis Locais:** Usar o prefixo 'L' (ex: LItem) e preferir declaração inline: `var LQuery := TFDQuery.Create(nil);`.
- **Parâmetros de Métodos:** Usar o prefixo 'A' (ex: procedure Processar(AValue: Integer)).

## 3. Gestão de Memória e Segurança
- **Segurança:** Todo objeto criado localmente DEVE ser destruído em um bloco `try...finally`.
- **Strings:** Usar sempre o tipo `string` (Unicode). Evite `AnsiString` ou `ShortString`.
- **Leaks:** Nunca sugira o uso de `FreeAndNil` para objetos que não serão reutilizados após a destruição; use apenas `.Free`.

## 4. Regras de Codificação (Clean Code)
- **Métodos:** Métodos devem ter uma única responsabilidade. Se passar de 50 linhas, sugira refatoração.
- **Dependency Injection:** Prefira passar dependências via Construtor.
- **Exceptions:** Nunca capture exceções vazias (`try...except end`). Sempre trate ou logue o erro.
- **UI:** Proibido escrever SQL ou lógica de negócio dentro de `TForm` ou `TDataModule`. Use classes de serviço.

## 5. Integração com ACBr e Terceiros
- Ao sugerir códigos para o ACBr, foque na utilização dos componentes em tempo de execução, garantindo que as propriedades de configuração (Schemas, Path, SSLLib) sejam setadas antes das operações.

Como Instalar e Ativar

No Cursor IDE

1. Na raiz do seu projeto, crie uma pasta chamada .cursor.
2. Dentro dela, crie o arquivo .cursorrules.
3. Cole o conteúdo da Skill acima.
4. O Cursor lerá este arquivo automaticamente. Você pode testar perguntando: “Quais são as regras de nomenclatura deste projeto?”

No Antigravity

1. Abra as configurações do seu Agente.
2. Localize a seção System Prompt ou Agent Instructions.
3. Cole o conteúdo do Markdown da Skill.
4. Se estiver usando a versão que suporta arquivos de contexto, faça o upload do arquivo .md para a Knowledge Base do agente.

O que é a Knowledge Base do Agente?

Enquanto o arquivo .cursorrules (no Cursor) é lido de forma automática a cada interação, em ferramentas como o Antigravity, você tem a opção de “treinar” o agente com documentos específicos.

Quando você faz o upload do seu arquivo .md de Skill para a Knowledge Base, acontece o seguinte:

1. Indexação RAG (Retrieval-Augmented Generation): A ferramenta processa o seu arquivo de texto e o transforma em vetores numéricos.
2. Busca Semântica: Sempre que você faz uma pergunta ou pede para gerar um código, o Agente faz uma “busca rápida” interna nesse arquivo para encontrar a regra que melhor se aplica àquela tarefa específica.
3. Economia de Contexto: Em vez de você colar 500 linhas de regras em todo prompt, a IA recupera apenas a parte necessária (ex: apenas a seção de “FireDAC” quando você estiver mexendo em banco de dados).

Passo a Passo para o Upload

Para quem utiliza o Antigravity ou interfaces de agentes baseadas em modelos como o Claude ou Gemini:

1. Localize as Configurações do Agente: Geralmente representado por um ícone de engrenagem ou “Configure Agent”.
2. Seção de Conhecimento (Knowledge/Files): Procure por uma área chamada “Add Knowledge”, “Reference Files” ou “Knowledge Base”.
3. Upload do Arquivo: Arraste o seu arquivo delphi-skills.md diretamente para lá.
4. Habilite a Consulta: Certifique-se de que a opção “Search Knowledge” ou “Consultar Base” esteja ativa para que o agente utilize aquele arquivo como fonte da verdade.

Por que usar arquivos .md em vez de texto puro?

Eu recomendo sempre usar o formato Markdown (.md) porque os Agentes de IA modernos são treinados para entender a hierarquia desse formato. Usar # para títulos e ## para subseções ajuda a IA a entender que:

• Um erro de Gestão de Memória (Subseção) é uma regra subordinada às Regras de Codificação (Seção Principal).

Isso evita que as regras se misturem e garante que a IA siga a prioridade correta na hora de escrever o seu código em Delphi.

Alimentando a Knowledge Base com Documentação Legada

Uma das maiores vantagens de utilizar a Knowledge Base no Antigravity (ou o @Context no Cursor) é a capacidade de “ensinar” à IA aquilo que ela não aprendeu no treinamento padrão.

Se o seu projeto utiliza uma API legada, um framework proprietário da sua empresa ou até mesmo manuais técnicos de hardware que não estão disponíveis publicamente na internet, o processo é o mesmo:

1. Converta para Markdown: Transforme manuais em PDF ou arquivos de ajuda antigos em arquivos .md simples.
2. Faça o Upload: Adicione esses arquivos à Knowledge Base junto com a sua Agent Skill.
3. Resultado: A IA passará a citar métodos e propriedades dessas bibliotecas internas com a mesma precisão que cita a VCL nativa do Delphi. Isso é um divisor de águas para quem mantém sistemas legados complexos ou integrações com hardwares específicos (como balanças, impressoras térmicas ou CLPs).

Expandindo o conhecimento e uso

1. Módulo Específico para o Dext Framework

Se você conhece o DEXT e deseja utilizá-lo, e como o DEXT é inspirado no ASP.NET Core, a IA precisa entender o conceito de injeção de dependência e rotas que ele utiliza.

## 6. Framework Dext (Web)
- **Controllers:** Devem herdar de `TDextController`.
- **Rotas:** Utilize os atributos `[Get]`, `[Post]`, `[Put]`, `[Delete]` nos métodos.
- **Injeção de Dependência:** Registre os serviços no `Startup` e receba-os no construtor do Controller.
- **Middleware:** Explique que middlewares devem implementar a interface `IDextMiddleware`.
- **JSON:** Use sempre `System.JSON.Serializers` para retorno de objetos DTO.

Especialização em FireDAC (Performance e Segurança)

Muitos desenvolvedores sofrem com IAs sugerindo TQuery antigo ou formas inseguras de concatenar strings SQL.

## 7. Persistência com FireDAC
- **Parâmetros:** OBRIGATÓRIO o uso de `.ParamByName` em todas as queries. Jamais concatene strings para SQL.
- **Macros:** Use Macros do FireDAC (`!VariableName`) apenas para nomes de tabelas ou campos dinâmicos.
- **Conexão:** Instrua a IA a sempre usar o `TFDConnection` definido no Singleton ou DataModule central.
- **Cursors:** Sempre defina `FetchOptions.Mode := fmAll` para pequenas consultas e use Paginação para grandes volumes.

Módulo de Componentes ACBr (Regras de Negócio Fiscal)

Se você utliza ACBr, informe como utilizá-los

## 8. Integração ACBr
- **Componentes:** Prefira instanciar os componentes (`TACBrNFe`, `TACBrCTe`) em tempo de execução dentro de Services.
- **Eventos:** Use Anonymous Methods ou procedures designadas para tratar os eventos `OnGerarLog` ou `OnRelatorio`.
- **Schemas:** Sempre sugira a verificação do caminho dos Schemas (XSD) antes da validação do XML.
- **DFE:** Ao consultar documentos fiscais, utilize sempre o tratamento de retorno 

Blueprints e Few-Shot Prompting: Ensinando pelo Exemplo

A teoria é fundamental, mas a IA atinge sua performance máxima quando fornecemos modelos reais de comparação. Esta seção do arquivo de Skill utiliza uma técnica chamada Few-Shot Prompting, que consiste em incluir blocos de código reais dentro das diretrizes. Ao ver como você estrutura um Controller no Dext, como instancia um componente ACBr ou como protege uma query FireDAC, o Agente deixa de ‘supor’ e passa a ‘espelhar’ a sua escrita. Isso elimina virtualmente qualquer inconsistência de estilo e garante que o código gerado esteja pronto para ser compilado.

Para isso basta adicionar blocos de exemplo de código ao final do seu arquivo .cursorrules ou .md. Ele serve para que a IA entenda a aplicação prática de todas as regras anteriores, alguns exemplos simples:

## 9. Exemplos de Referência (Siga este Estilo)

### Exemplo A: Estrutura de Service e FireDAC
Observe a indentação, o uso de try..finally e a nomenclatura.

```delphi
function TUsuarioService.AtualizarSaldo(const AUsuarioId: Integer; const AValor: Currency): Boolean;
var
  LQuery: TFDQuery;
begin
  Result := False;
  LQuery := TFDQuery.Create(nil);
  try
    LQuery.Connection := FConnection; // Injetado via construtor
    LQuery.SQL.Text := 'UPDATE USUARIOS SET SALDO = SALDO + :VALOR WHERE ID = :ID';
    LQuery.ParamByName('VALOR').AsCurrency := AValor;
    LQuery.ParamByName('ID').AsInteger := AUsuarioId;
    LQuery.ExecSQL;
    Result := LQuery.RowsAffected > 0;
  finally
    LQuery.Free;
  end;
end;

Exemplo B: Controller no Dext Framework

Como definir rotas e injeção de dependência de forma limpa no DEXT.

[ApiController('/v1/produtos')]
TProdutoController = class(TDextController)
private
  FService: IProdutoService;
public
  constructor Create(const AService: IProdutoService);
  
  [HttpGet]
  function ListarTodos: IDextResponse;
  
  [HttpPost]
  function Salvar: IDextResponse;
end;

implementation

constructor TProdutoController.Create(const AService: IProdutoService);
begin
  FService := AService;
end;

function TProdutoController.ListarTodos: IDextResponse;
begin
  Result := Results.Ok(FService.GetAll);
end;

Exemplo C: Manipulação de Componentes ACBr

Foco em legibilidade e configuração em tempo de execução.

procedure TNotaFiscalService.ConfigurarEmitente(const ACNPJ: string);
begin
  FACBrNFe.Configuracoes.Certificados.NumeroSerie := FConfig.CertificadoSerie;
  FACBrNFe.Configuracoes.Geral.SSLLib := libOpenSSL;
  
  with FACBrNFe.Configuracoes.Geral.Emitente do
  begin
    CNPJ := ACNPJ;
    // ... demais configurações
  end;
end;

Para aprender mais

• https://github.com/sickn33/antigravity-awesome-skills
• https://github.com/skillmatic-ai/awesome-agent-skills
• https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
• https://agentskills.io/home
• https://code.visualstudio.com/docs/copilot/customization/agent-skills
• https://developers.openai.com/codex/skills/
• https://cursor.com/pt-BR/docs/context/skills
• https://kiro.dev/docs/skills/

Conclusão

Criar uma Agent Skill não é apenas sobre “ajudar a IA”, é sobre proteger a integridade do seu código. Com essas definições, o Cursor e o Antigravity deixam de ser apenas assistentes e passam a agir como arquitetos que conhecem profundamente os seus padrões de desenvolvimento.

Referências

CANTÙ, Marco. Object Pascal Handbook: Delphi 12 Athens Edition. Piacenza: Wintech Italia, 2024.

CURSOR. Rules for AI: Project-specific instructions. Disponível em: https://docs.cursor.com/context/rules-for-ai. Acesso em: 9 fev. 2026.

MARTIN, Robert C. Clean Code: A Handbook of Agile Software Craftsmanship. Upper Saddle River: Prentice Hall, 2008.

REGYS. Padrões de Nomenclatura e Clean Code em Delphi. Disponível em: https://regys.com.br. Acesso em: 9 fev. 2026.

ANTIGRAVITY Awesome Skills. GitHub Repository. Disponível em: https://github.com/sickn33/antigravity-awesome-skills. Acesso em: 9 fev. 2026.

ANTHROPIC. Agent Skills Overview. Claude Platform Documentation. Disponível em: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview. Acesso em: 9 fev. 2026.

AGENT SKILLS. Home. Disponível em: https://agentskills.io/home. Acesso em: 9 fev. 2026.

AWESOME Agent Skills. GitHub Repository. Disponível em: https://github.com/skillmatic-ai/awesome-agent-skills. Acesso em: 9 fev. 2026.

CURSOR. Customizing Cursor with Skills. Cursor Documentation. Disponível em: https://cursor.com/pt-BR/docs/context/skills. Acesso em: 9 fev. 2026.

KIRO. Kiro Docs: Skills. Disponível em: https://kiro.dev/docs/skills/. Acesso em: 9 fev. 2026.

MICROSOFT. Customizing GitHub Copilot with Agent Skills. Visual Studio Code Documentation. Disponível em: https://code.visualstudio.com/docs/copilot/customization/agent-skills. Acesso em: 9 fev. 2026.

OPENAI. Codex Skills Documentation. OpenAI Developers. Disponível em: https://developers.openai.com/codex/skills/. Acesso em: 9 fev. 2026.