Regras automáticas
.instructions.md define guardrails que o agente NUNCA pode ignorar. São aplicadas automaticamente.
Ato I: a arquitetura de arquivos, onde vivem agents, skills, instructions e prompts, e como o GitHub Copilot os descobre. Ato II: a árvore de decisão para escolher entre Agente Customizado, Generalista com Skill e Generalista Simples em qualquer tarefa.
Cada arquivo é uma camada de contexto para o agente. Sem arquitetura, agentes operam sem regras, sem identidade e sem expertise.
.instructions.md define guardrails que o agente NUNCA pode ignorar. São aplicadas automaticamente.
.github/agents/*.md define QUEM o agente é, seu escopo, ferramentas e para quem delega.
SKILL.md codifica expertise do domínio: templates, workflows, checklists e exemplos.
.prompt.md armazena prompts reutilizáveis que podem ser invocados sob demanda.
Sem arquitetura de arquivos, agentes operam sem regras, sem identidade e sem expertise. O resultado é comportamento inconsistente que ninguém consegue auditar.
Estes 6 tipos formam o ecossistema completo. Cada um é carregado em um momento diferente e com um escopo diferente.
my-project/ ├── .github/ │ ├── copilot-instructions.md # regras globais │ ├── agents/ │ │ ├── code-reviewer.md │ │ ├── security-auditor.md │ │ └── docs-writer.md │ └── skill/ │ └── code-review/ │ ├── SKILL.md │ └── references/ ├── .vscode/ │ └── mcp.json # servidores MCP ├── .instructions.md # regras da raiz └── src/ ├── .instructions.md # regras TypeScript └── components/ └── .instructions.md # regras React
.github/ concentra a configuração do GitHub Copilot: regras globais, agentes e skills do repositório.
Arquivos .instructions.md em subpastas herdam e podem sobrescrever regras do pai. O mais próximo do arquivo vence.
Esta é a estrutura de um repositório bem organizado. Novos devs entendem as regras desde o primeiro dia.
Anatomia de um agent file, o campo que decide tudo, skills com ciclo de vida, e a diferença entre automático e sob demanda.
--- name: Code Reviewer description: Reviews PRs for quality, security, and best practices tools: - name: github-mcp-server - name: codeql-scanner --- # Code Reviewer Agent You are a senior code reviewer focused on: - Code quality and maintainability - Security vulnerabilities ## Scope Only review code changes. Do NOT modify code. ## Handoffs Architecture questions → @architect
name, description e tools: os metadados estruturados que o orquestrador lê.
Instruções detalhadas, persona, escopo e limites do agente.
O frontmatter tools conecta o agente aos MCP servers definidos em .vscode/mcp.json. Ele só usa o que está listado.
Para quem o agente delega tarefas fora do seu escopo.
description: Helps with code
O orquestrador não consegue distinguir este agente dos outros. Descrições vagas = agente ignorado.
description: Reviews pull requests for code quality, security vulnerabilities and test coverage gaps. Triggered when user asks to review code or PRs.
Diz O QUE o agente faz e QUANDO deve ser ativado. O orquestrador compara isso com a intenção do usuário.
Se a descrição não especifica QUANDO o agente deve ser ativado, o orquestrador pode escolher o agente errado, ou nenhum.
No corpo do agent file, a seção Handoffs declara as rotas: tarefas de implementação para @code-reviewer, schemas para @db-specialist, revisão de segurança para @security-auditor.
--- name: Code Review Skill description: Expert code review methodology including security scanning and best practice validation. trigger: when user asks to review code, analyze PR, or check code quality --- # Code Review Methodology ## Steps 1. Read the diff and understand context 2. Check for security vulnerabilities 3. Verify naming conventions 4. Analyze performance implications ## Checklist - [ ] No secrets in code - [ ] Tests cover the change
Define quando o skill é ativado. O orquestrador compara a intenção do usuário com os triggers registrados.
Passos sequenciais para execução e validação automática do resultado.
Templates, exemplos e dados que o skill injeta no contexto quando ativado.
Dica de performance: mantenha references/ enxuto. Arquivos grandes consomem tokens, e desde junho tokens são AI Credits na fatura. Use apenas o essencial.
Regras automáticas por diretório. Guardrails que o agente NÃO pode ignorar. Filhos herdam do pai.
applyTo: "**/*.ts" # glob define quais arquivos
Um único arquivo em .github/ que se aplica a todo o repositório: stack, convenções e arquitetura.
## Code Style
- TypeScript strict mode
- Tailwind CSS, Vitest
Prompts reutilizáveis sob demanda: invocados manualmente, não aplicados automaticamente.
mode: agent # usa ferramentas mode: ask # só texto
.instructions.md é automático e sempre ativo. .prompt.md é sob demanda, invocado pelo usuário. O campo mode: agent permite que o prompt use ferramentas; mode: ask gera apenas texto sem side effects.
Como o GitHub Copilot carrega seu contexto passo a passo. Cada camada adiciona inteligência ao agente.
Cada camada adiciona contexto. Quanto melhores os seus arquivos, mais inteligente o agente se comporta.
O orquestrador comparou a intenção com as descriptions e selecionou sozinho.
Regras globais, regras locais, identidade do agente e skill: tudo mergeado antes de agir.
Todo o Ato I está nesta tela: arquivos bem escritos viram um agente que age certo.
Custom Agent, Generalista com Skill ou Generalista Simples. Escolher a configuração errada gera frustração nos dois sentidos.
Arquivo .agent.md com identidade, ferramentas exclusivas via MCP, escopo definido e personalidade única. Ideal para domínios críticos.
GitHub Copilot padrão turbinado com SKILL.md que traz conhecimento de domínio. Sem personalidade customizada, mas com expertise sob demanda.
GitHub Copilot padrão sem configuração extra. Para tarefas simples, brainstorming, perguntas factuais e conversas gerais.
Escolher a configuração errada gera frustração: agentes simples demais para tarefas complexas, ou complexidade desnecessária para pedidos triviais.
A tarefa precisa de MCP servers, APIs dedicadas ou CLIs especializadas?
O agente precisa de tom rigoroso (segurança) ou amigável (documentação)?
Envolve orquestração complexa com handoff entre agentes?
Há um SKILL.md pré-existente com conhecimento do domínio?
Nem toda tarefa requer a mesma abordagem. Responda cada pergunta para encontrar o caminho ideal.
Dica rápida: se qualquer uma das 3 primeiras perguntas for SIM, você provavelmente precisa de um Agente Customizado.
Quando o Custom Agent é essencial, onde o Generalista brilha, e a comparação lado a lado que resolve qualquer dúvida.
MCP vault, compliance rules, auditoria automatizada. Tom rigoroso e sem tolerância a falhas.
CI/CD tools, test runners, relatórios de cobertura. Acesso a pipelines e ambientes de staging.
Terraform, guias de refactoring, análise de dependências. Converte legacy para cloud-native.
Templates legais, banco de compliance, revisão de contratos. Tom formal e preciso.
Atenção à complexidade: agentes customizados exigem manutenção de instruções, ferramentas e escopo. Crie apenas quando os critérios justificarem. O .agent.md é o DNA do agente: instruções, ferramentas, escopo e personalidade em um único arquivo.
Arquivos .prompt.md são atalhos reutilizáveis para tarefas comuns. Não são agentes, mas facilitam muito o uso do Generalista no dia a dia.
Não existe "melhor" absoluto. Existe o mais adequado para cada cenário.
Regra de ouro: SIM para ferramentas, personalidade OU múltiplos estágios = Custom Agent. Apenas skill existe = Generalista + Skill. Tudo não = Generalista Simples.
Três pedidos, três rotas. A árvore de decisão funciona nos dois sentidos: você escolhe melhor, e o orquestrador também.
Três cenários reais que cobrem os três caminhos, as boas práticas de organização, e o resumo para levar.
Agent .md com tom rigoroso, vault MCP + CodeQL + Snyk, skill pci-compliance. Dispara em cada PR via workflow.
copilot-instructions.md com as convenções e 5 prompt files para tarefas repetitivas: componente, API, teste, migration, doc.
Audita 23 skills em 5 repos, define template padrão de SKILL.md, repo central compartilhado e naming domain-action.
Os três caminhos da árvore, cada um no cenário onde é a resposta certa. Não existe melhor absoluto: existe o mais adequado.
O ciclo de vida de um skill no time: identifique padrões repetitivos (3+ pessoas fazendo o mesmo), documente, teste com cenários reais, publique em .github/skill/ e itere com feedback.
Agents, skills, instructions, copilot-instructions, prompts e mcp.json. Cada um com seu escopo e momento.
O orquestrador escolhe agentes e skills por ela. Diga O QUE faz e QUANDO ativar.
.instructions.md herdam do pai e o mais próximo do arquivo vence. Merge automático em camadas.
Ferramentas? Personalidade? Multi-estágio? Skill existe? A árvore inteira em uma linha.
Qualquer SIM nas 3 primeiras: Custom Agent. Só skill existe: Generalista + Skill. Tudo não: Simples.
Reutilizáveis entre agentes e times. Identifique, documente, teste, publique, itere.
# Project Instructions for GitHub Copilot ## Code Style - TypeScript strict mode - Tailwind CSS, Vitest ## Architecture - Services in /src/services/ # e todo agente do repo já nasce sabendo
Publicado em 2026-06-11 · v1