Criando sua primeira Skill no GitHub Copilot

Sejamos sinceros.

O nosso fluxo com IA nos últimos meses é basicamente abrir a IDE, escrever uma epopéia em forma de prompt, remover o limite do cartão de crédito e cruzar os dedos esperando que o Github Copilot não transforme seu projeto numa mistura de Clean Architecture, Blockchain, DDD, Kafka e astrologia orientada a eventos.

Você torce para que a IA adivinhe que seu projeto usa Clean Architecture, que o time odeia Fat Controllers, que existe um padrão de nomenclatura e que o trauma do vazamento de dados da última sprint ainda assombra o CTO que quase enfartou quando ouviu a frase: “Foi a IA que gerou".

Tem vezes que ela acerta.

Tem vezes que ela te entrega um código que faz o SonarQube entrar em posição fetal chorando no canto da pipeline.

E é nesse cenário que surgem as tais Skills.

Eu digo “surgem” porque o conceito ainda está amadurecendo e mudando rápido nas ferramentas modernas de IA. Mas depois de brincar bastante com isso, eu fiquei genuinamente otimista.

(Eu também fiquei otimista com Silverlight, WPF, WCF, Xamarin, Windows Phone e VB6. Então pondere minhas emoções com responsabilidade).

O que são Skills no GitHub Copilot?

As Skills são, essencialmente, mecanismos para fornecer contexto e instruções reutilizáveis para a IA. Pense nelas como especializações, regras, exemplos, restrições, convenções arquiteturais e o comportamento esperado de forma geral.

Elas ajudam a IA a entender os padrões do projeto, as convenções do time, a arquitetura desejada, as limitações do ecossistema e, principalmente, o que ela NÃO deve fazer.

Porque sejamos honestos: o maior problema da IA hoje não é falta de capacidade, é o excesso de "criatividade". IA com liberdade criativa é um perigo, pois afinal todos nós sabemos que não existe coisa mais nociva do que um idiota com iniciativa...

Ela olha pro seu projeto usando Clean Architecture e pensa:

Interessante… mas e se a gente colocasse um acesso direto ao banco na Controller usando Dapper, Entity Framework e um CSV vindo do SharePoint ao mesmo tempo?

E o pior: às vezes funciona.

O que as Skills realmente resolvem? (Ou tentam resolver)

Aqui existe um ponto importante. Skills NÃO são enforcement arquitetural. Elas não garantem a aderência à arquitetura, a qualidade da entrega, a separação de camadas, a ausência de acoplamento ou a sanidade mental da equipe.

Elas simplesmente aumentam a probabilidade da IA gerar algo alinhado ao contexto do projeto, e isso é MUITO diferente. Quem realmente faz o enforcement continua sendo o code review, os testes, os analyzers, o SonarQube, o CI/CD, ferramentas como Roslyn Analyzers, NetArchTest ou ArchUnitNET, e claro, aquele desenvolvedor sênior traumatizado que detecta um anti-pattern a 300 metros de distância.

As Skills funcionam mais como context engineering. Ou seja: elas ajudam a IA a entrar “nos conformes” do projeto. Elas reduzem a deriva contextual, melhoram a consistência das respostas e diminuem a geração de código fora do padrão esperado. Mas elas não são uma garantia absoluta. A IA ainda pode alucinar, ignorar as instruções ou simplesmente decidir que hoje é um dia de ser criativa demais.

O problema real que as Skills tentam resolver

Todo time tem padrões internos. Ok… isso talvez tenha sido otimista demais.

Vamos reformular: todo time possui ao menos uma tentativa de padrão arquitetural. Talvez seja Clean Architecture, Hexagonal, Vertical Slice, DDD, BOLOVO, NEM RELA, ou até aquela estrutura de pastas que ninguém entende mas todo mundo tem medo de questionar... afinal...

Quando eu cheguei já estava assim!

Sem Skills, toda interação vira uma sessão de terapia em formato de prompt:

Dona IA, gere esse CRUD.
Mas usa MediatR, Ok? 
Não coloca regra na Controller e não usa DateTime.Now.
Usa CancellationToken.
Não cria abstrações desnecessárias.
Não inventa uma classe chamada AbstractProductServiceFactoryProviderManager.
E pelo amor de Deus não acessa Infrastructure na camada de domínio.

Na décima vez digitando isso, deixa de ser engenharia de software e vira quase que uma ligação na empresa de TV por assinatura para pedir cancelamento do serviço. (Evitarei usar nomes para não ser processado por difamação, mas você sabe do que e de quem eu estou falando).

Skills não eliminam alucinação

Alucinação? Que diabos é isso?

Além de ser o nome do melhor disco do Belchior, a alucinação é uma resposta gerada pela IA que parece correta, coerente e convincente, mas que contém informações falsas, inventadas ou distorcidas. É tipo um coach motivacional que tenta te ensinar a ser mais produtivo, mas que na verdade só te dá dicas genéricas como “beba água”, “faça pausas regulares” e "não desista!".

Isso ocorre porque o modelo não “entende” fatos da mesma forma que um humano. Ele prevê probabilisticamente a próxima sequência de palavras com base nos padrões aprendidos durante o treinamento.

Como resultado, pode criar referências inexistentes, citar APIs que não existem, inventar funcionalidades, datas, links ou até gerar código tecnicamente inválido com extrema confiança. (Lembra do idiota com iniciativa? Pois é...).

Agora que sabemos razoalmente o que é alucinação, fica mais fácil entender o que as Skills fazem e o que elas não fazem.

Skills NÃO resolvem o problema da alucinação!

A alucinação em IA pode acontecer por diversos motivos, seja por falta de informação, contexto ruim ou excesso de contexto, ambiguidade, um modelo de LLM meia boca, instruções sem pé nem cabeça, limitação da janela de contexto, embeddings ruins ou porque a IA simplesmente acordou inspirada demais naquele dia.

O que as Skills fazem de fato é tentar manter a IA nos trilhos o máximo possível, melhorar a consistência das respostas e diminuir a geração de código fora do padrão esperado. Ou seja: existem menos chances da IA decidir que seu Repository Pattern agora usa SharePoint como banco de dados, Kafka como cache distribuído e o horóscopo do dia para a validação de negócio.

Agents vs Skills

Essa parte gera muita confusão porque o mercado ainda não padronizou esses conceitos. Dependendo da ferramenta, a palavra Agent pode significar um orquestrador, um planner, um executor, um workflow runner, um autonomous loop, um tool caller ou simplesmente um estagiário probabilístico muito caro.

Mas simplificando bastante a ideia: Agents executam tarefas, enquanto as Skills ajudam a orientar como essas tarefas devem ser executadas.

Um único agente pode usar várias Skills para criar APIs, gerar testes, validar a arquitetura, documentar o código ou revisar PRs. Mas tudo isso muda bastante conforme a ferramenta que você está usando, seja o VS Code, Antigravity, GitHub Copilot, Cursor, Claude Code, Windsurf, Open Code ou qualquer outra ferramenta que inventarem amanhã às 15h.

Esse ecossistema muda numa velocidade tão grande que faz aquele framework JavaScript lançado semana passada parecer estável e seguro.

Estrutura de uma Skill

A estrutura varia conforme ferramenta e versão. Isso é importante porque a documentação muda rapidamente. No ecossistema atual do GitHub Copilot, normalmente vemos algo próximo disso:

.github/
└── copilot/
    └── skills/
        └── create-api/
            ├── skill.md
            ├── examples.md
            └── resources/

A pasta .github fica na raiz do seu projeto. Talvez você já deva ter visto ela, pois é onde ficam os arquivos de workflow do GitHub Actions. Dentro dela, criamos uma subpasta chamada copilot, e dentro dela, outra subpasta chamada skills. A ideia é organizar as Skills de forma clara e hierárquica.

O arquivo principal geralmente é o skill.md. É nele que você define o comportamento esperado da IA, ditando as regras, passando o contexto adequado, definindo as convenções e restrições, além de fornecer exemplos. Ou seja: é o lugar onde você tenta impedir a IA de transformar seu backend num fanfic arquitetural (eu amo essa expressão hehehe...).

O conteúdo ideal de uma Skill

Uma Skills normalmente contém informações cruciais como seu nome, descrição, objetivo e contexto, acompanhados de regras e restrições claras. Além disso, é comum incluir as convenções adotadas, exemplos de uso, a estrutura esperada do código, anti-patterns que devem ser evitados, boas práticas e referências úteis.

A ideia é simples: transformar o “conhecimento do time” em contexto explícito. Porque a IA não lê a mente do arquiteto. E muitas vezes nem o próprio time...

Exemplo prático

Nós vamos usar o VS Code como exemplo, mas o processo é similar em outras ferramentas. O importante é entender a estrutura e o conteúdo da Skill, que são os elementos que realmente fazem a diferença na hora de orientar a IA.

Outro ponto: Usaremos .NET como exemplo, mas o processo é aplicável a qualquer linguagem ou framework. O que muda é o conteúdo da Skill, que deve ser adaptado ao contexto do projeto.

Abra o editor e selecione uma pasta. Crie a estrutura de pastas conforme o exemplo acima, e dentro da pasta create-api, crie um arquivo chamado skill.md.

Vamos criar uma Skill chamada create-api.

Essa skill é apenas para exemplo. Ela não é perfeita, não é definitiva e nem tem a responsabilidade de definir a melhor forma de como se criar uma API. O objetivo aqui é totalmente didático, feito para mostrar como estruturar uma Skill, o tipo de conteúdo que ela deve conter e como isso influencia a geração de código da IA. Use por conta e risco!

Edite o arquivo skill.md com o seguinte conteúdo:

---
name: create-api
description: Gera endpoints seguindo padrões arquiteturais do projeto
---

# Objetivo

Gerar endpoints REST utilizando: ASP.NET Core, MediatR e FluentValidation.

# Regras

Controllers devem conter apenas orquestração e nunca acessar o banco diretamente. Commands e Queries devem usar MediatR obrigatoriamente. É necessário utilizar CancellationToken em operações assíncronas IO-bound, garantir a validação com FluentValidation e evitar a adição de abstrações desnecessárias ao projeto.

# Restrições

Não é permitido usar lógica de negócio em Controllers, nem acessar a camada de Infrastructure diretamente. Além disso, não crie helpers estáticos genéricos e evite o uso do DateTime.Now.

O prompt:

Utilize a skill create-api para criar um endpoint POST /products. Os dados do produto são Name (string), Price (decimal).

Certifique-se de que você está no modo Agente, para isso, clique no ícone do Copilot no canto inferior esquerdo e selecione "Agent". Depois, basta usar o prompt acima para gerar o endpoint seguindo as regras definidas na skill.

Resultado esperado

Atenção, o resultado esperado pode e vai variar conforme a versão da IA, o modelo utilizado (aqui eu usei o Claude Sonnet 4.6), o contexto do projeto, as instruções passadas e até o humor da IA naquele dia. Mas, idealmente, algo próximo disso:

public sealed record CreateProductCommand(
    string Name,
    decimal Price
) : IRequest<Result<Guid>>;


public sealed class CreateProductValidator
    : AbstractValidator<CreateProductCommand>
{
    public CreateProductValidator()
    {
        RuleFor(x => x.Name)
            .NotEmpty();

        RuleFor(x => x.Price)
            .GreaterThan(0);
    }
}

public sealed class CreateProductValidator : AbstractValidator<CreateProductCommand>
{
    public CreateProductValidator()
    {
        RuleFor(x => x.Name).NotEmpty();
        RuleFor(x => x.Price).GreaterThan(0);
    }
}

public sealed class Product
{
    public Guid Id { get; init; } = Guid.NewGuid();
    public string Name { get; init; } = string.Empty;
    public decimal Price { get; init; }
}

public interface IProductRepository
{
    Task AddAsync(Product product, CancellationToken cancellationToken);
}

public sealed class AppDbContext(DbContextOptions<AppDbContext> options) : DbContext(options)
{
    public DbSet<Product> Products => Set<Product>();
}

public sealed class ProductRepository(AppDbContext db) : IProductRepository
{
    public async Task AddAsync(Product product, CancellationToken cancellationToken)
    {
        await db.Products.AddAsync(product, cancellationToken);
        await db.SaveChangesAsync(cancellationToken);
    }
}

public sealed class CreateProductHandler : IRequestHandler<CreateProductCommand, Result<Guid>>
{
    private readonly IProductRepository _repository;

    public CreateProductHandler(IProductRepository repository) => _repository = repository;

    public async Task<Result<Guid>> Handle(CreateProductCommand request, CancellationToken cancellationToken)
    {
        var product = new Product { Name = request.Name, Price = request.Price };
        await _repository.AddAsync(product, cancellationToken);
        return Result.Success(product.Id);
    }
}

[ApiController]
[Route("api/v1/products")]
public sealed class ProductsController : ControllerBase
{
    private readonly ISender _sender;

    public ProductsController(ISender sender) => _sender = sender;

    [HttpPost]
    public async Task<IActionResult> Post(CreateProductCommand command, CancellationToken cancellationToken)
    {
        var result = await _sender.Send(command, cancellationToken);
        return Ok(result);
    }
}

Ok, hoje temos o ASP NET Minimal API mas eu estou testando os prompts usados nesse post num projeto antigo que eu sei que funciona. Esse é o segredo de posts e palestras: Não inventar moda, se funciona, usa e segue o baile.

Eu coloquei boa parte do resultado num arquivo só para ficar fácil visualizar o que foi gerado. Mas a IA vai criar a estrutura de pastas e arquivos conforme o padrão do projeto. Ou seja: o comando, o handler, a validação, a entidade, o repositório e a controller devem ser criados em seus respectivos arquivos e pastas.

O que realmente acontece na prática?

Aqui vem a parte importante: a IA NÃO vai magicamente obedecer tudo. Mas, ao utilizar a Skill, ela terá mais contexto, mais consistência e mais alinhamento arquitetural, resultando em menos deriva e menos aleatoriedade no output.

Na prática, isso reduz a incidência de código fora do padrão, abstrações inúteis, boilerplate estranho, decisões arquiteturais aleatórias e o surgimento daquela famigerada classe chamada:

ProductBusinessRulesValidationFactoryManagerProvider

que ninguém sabe quem criou, mas todo mundo tem medo de apagar.

Skills não substituem revisão de código

Aliás: hoje a revisão de código é MAIS importante do que era antes. Porque agora o cenário inclui humanos cometendo bugs, IAs cometendo bugs e, o pior de todos, humanos aprovando irresponsavelmente os bugs gerados pela IA.

A revisão virou o verdadeiro guardião da sanidade coletiva do time. As Skills ajudam bastante a guiar o processo, mas a etapa de revisão continua sendo absolutamente obrigatória. Principalmente porque a IA tem a capacidade bizarra de gerar um código que soa plausível, é elegante, bonito, extremamente bem formatado e que, no final, está completamente errado. O que é honestamente impressionante, parecendo eu no início de carreira...

E o Ganho Real?

Sendo bem honesto: a vantagem disso não é "codar 10x mais rápido" como os tech-manja influencers (Deus me livre de um dia virar um) prometem no Instagram. Isso talvez se torne uma realidade no futuro, mas hoje resultado é outro.

O ganho real é você não perder 40 minutos num Pull Request discutindo (e tendo que se segurar para não perder o réu primário) por que diabos a regra de negócio do desconto de Black Friday foi parar dentro de um arquivo chamado Utils.cs.

Aliás, toda vez que eu vejo uma pasta ou arquivo chamado Utils eu me pergunto se tudo que está fora dessa pasta ou arquivo é inútil. E se for, por que não deletar tudo e deixar só o Utils? Fica a reflexão...

Nisso, é possível notar que as Skills trazem uma certa padronização. Menos decisões repetitivas significam menos debates filosóficos exaustivos de sexta-feira à tarde sobre onde colocar um arquivo.

A gente foca no que importa: entregar valor, resolver problemas reais, criar features que os usuários amam, e não ficar discutindo se o DbContext pode ser instanciado na controller ou se o nome do comando deveria ser CreateProductCommand ou AddProductCommand.

Mas não se engane achando que é só mandar a IA seguir as regras e pronto! O processo de criação e manutenção das Skills é contínuo. Você precisa revisar, atualizar e adaptar as Skills conforme a evolução do projeto e da equipe.

O que as pessoas precisam entender é que hoje devemos ser mais engenheiros de software e menos digitadores de código. A gente precisa resolver problemas reais. Sem vaidade mas com foco e qualidade!

A IA é uma ferramenta poderosa, mas ela precisa ser guiada e controlada para entregar valor real. As Skills são um dos mecanismos para isso, mas elas não são uma solução mágica. Elas exigem esforço, disciplina e colaboração para serem eficazes.

Outro ponto crucial é a revisão de código!

Eu já citei isso?

Já?

Ok, mas não custa repetir:

Esse processo hoje é simplesmente FUNDAMENTAL! MAIS DO QUE NUNCA!

Ele é o guardião da qualidade do código gerado pela IA. Ele é o momento onde a equipe pode garantir que as Skills estão sendo seguidas, que o código gerado é alinhado com os padrões do projeto e que não estamos introduzindo bugs ou problemas de manutenção.

Acho que deu para entender a importância desse projeto, certo?

Boas práticas de sobrevivência

1. Skills pequenas e específicas

Não crie uma Skill monstruosa do tipo enterprise-master-skill-final-v12-definitivo-agora-vai. Em vez disso, prefira dividir o contexto em habilidades menores e focadas, como create-api, generate-tests, validate-command e create-handler.

2. Seja absurdamente explícito

Lembre-se de que a IA não possui bom senso arquitetural. Se você não falar expressamente como as coisas funcionam, ela fatalmente usará DateTime.Now, vai instanciar seu DbContext no meio da controller, criará abstrações desnecessárias, inventará um generic repository do zero e, de quebra, vai criar a factory da factory da factory. (Eu sei que você se identificou com isso, não se preocupe, é normal... ou não...).

3. Defina o que NÃO fazer

Essa talvez seja a parte mais importante na hora de escrever uma Skill. Por exemplo, deixe registrado de forma clara que é NUNCA permitido acessar o banco diretamente na controller, que é PROIBIDO instanciar o DbContext manualmente e que a IA NÃO deve criar helpers estáticos genéricos. A IA responde de forma excelente a restrições explícitas, agindo quase como um desenvolvedor júnior assustado no seu primeiro deploy pra produção numa sexta-feira.

4. Versione suas Skills

A arquitetura de um projeto evolui com o tempo, logo, as Skills também precisam evoluir e acompanhar as mudanças. Senão, daqui a seis meses, você terá metade do time usando Minimal API, a outra metade usando Controller tradicional, alguém subindo um serviço SOAP ironicamente e, do nada, surge um endpoint gRPC que nobody asked for (saudades do WCF...).

5. Não transforme a Skill num romance russo

Se a sua Skill tiver 50 mil linhas e começar a parecer um capítulo de Os Irmãos Karamázov do Dostoiévski, pode ter certeza de que ninguém vai manter aquilo, a IA vai ignorar metade das instruções e a janela de contexto do modelo vai explodir. Um contexto útil de verdade precisa ser específico, altamente relevante e direto ao ponto.

Passando a régua

As Skills representam um avanço extremamente importante na evolução da IA aplicada ao desenvolvimento de software. Elas não transformam a IA num arquiteto de software autônomo. Pelo menos não ainda. E nem sei se vão... Mas elas ajudam bastante a tornar a geração de código um processo muito mais consistente, muito mais previsível, bem menos caótico e intimamente alinhado ao contexto real daquele projeto específico.

No fim das contas, a IA continua sendo uma ferramenta probabilística. Ela é extremamente poderosa, assustadoramente convincente, ocasionalmente genial e frequentemente criativa até demais. E é exatamente por esse motivo que ela precisa de contexto sólido, de restrições severas, de direção clara e de engenharia de verdade por trás dos panos. Porque se existe algo no mundo mais perigoso do que um código ruim… é um código ruim gerado de forma extremamente rápida.

Quer testar no seu projeto?

Dá uma olhada na documentação oficial: Customize Copilot with Skills

Aliás, quer um lugar bacanudo com milhares de skills prontas para usar? Dá uma olhada no Awesome Copilot Skills.

Era isso.