GitHub Copilot Skills & Agents: Routing Work to the Right ToolGitHub Copilot Skills & Agents: Roteando o Trabalho para a Ferramenta CertaGitHub Copilot Skills & Agents: Enrutando el Trabajo a la Herramienta Correcta
A comprehensive guide to GitHub Copilot's skill anatomy, agent decision tree, custom agent contracts, and multi-agent orchestration pipelines. Built for engineering teams that need to scale beyond a single chat box.Um guia completo sobre anatomia de skills, árvore de decisão de agentes, contratos de custom agents e pipelines de orquestração multi-agente. Desenvolvido para equipes de engenharia que precisam escalar além de uma única caixa de chat.Una guía completa sobre la anatomía de skills, el árbol de decisión de agentes, los contratos de custom agents y los pipelines de orquestación multi-agente. Construida para equipos de ingeniería que necesitan escalar más allá de una única ventana de chat.
Read the article below, present the deck, or go deep with the playbook. The same thesis, calibrated to how you need to engage with it. Leia o artigo abaixo, apresente o deck ou aprofunde com o playbook. A mesma tese, calibrada para a forma como você precisa engajar. Lee el artículo abajo, presenta el deck o profundiza con el playbook. La misma tesis, calibrada para cómo necesitas interactuar.
Six pillars of the agentic workspace.Seis pilares do workspace agêntico.Seis pilares del espacio agéntico.
Read this page in pillars. Each pillar maps to one source document in the playbook and to a section in the companion decks. The order matches how a task actually flows through the system: arrival, routing, knowledge, tools, gates, configuration.Leia esta página em pilares. Cada pilar mapeia para um documento-fonte no playbook e para uma seção nos decks companheiros. A ordem segue como uma tarefa realmente flui pelo sistema: chegada, roteamento, conhecimento, ferramentas, gates, configuração.Lee esta página por pilares. Cada pilar mapea a un documento fuente del playbook y a una sección de los decks acompañantes. El orden sigue el flujo real de una tarea por el sistema: llegada, ruteo, conocimiento, herramientas, gates, configuración.
Skill anatomy and lifecycleAnatomia e ciclo de vida de skillAnatomía y ciclo de vida de skill
A SKILL.md is more than a prompt. It is a versioned bundle: frontmatter, body, scripts, references. The lifecycle covers discovery, activation, execution, expiration. Get this right and skills compound.Um SKILL.md é mais que um prompt. É um bundle versionado: frontmatter, corpo, scripts, referências. O ciclo cobre descoberta, ativação, execução, expiração. Acerte isso e skills compõem.Un SKILL.md es más que un prompt. Es un bundle versionado: frontmatter, cuerpo, scripts, referencias. El ciclo cubre descubrimiento, activación, ejecución, expiración. Aciértalo y las skills componen.
Agent vs skill decision treeÁrvore de decisão: agente vs skillÁrbol de decisión: agente vs skill
Four sequential questions: specific tools, specific personality, multi-stage handoff, existing SKILL.md. Three terminal outcomes: custom agent + skill, generalist + skill, generalist alone. Stop over-engineering.Quatro perguntas sequenciais: ferramentas específicas, personalidade específica, handoff multietapa, SKILL.md existente. Três saídas terminais: agente custom + skill, generalista + skill, generalista só. Pare de superengenheirar.Cuatro preguntas secuenciales: herramientas específicas, personalidad específica, handoff multietapa, SKILL.md existente. Tres salidas terminales: agente custom + skill, generalista + skill, generalista solo. Deja de sobre-ingenierizar.
Plugins and MCP serversPlugins e servidores MCPPlugins y servidores MCP
Plugins extend the IDE. MCP servers expose external systems as typed tools. Together they are the bridge from the model to your real environment: repos, databases, dashboards, queues, secrets.Plugins estendem o IDE. Servidores MCP expõem sistemas externos como ferramentas tipadas. Juntos são a ponte do modelo para seu ambiente real: repos, bancos, dashboards, filas, segredos.Los plugins extienden el IDE. Los servidores MCP exponen sistemas externos como herramientas tipadas. Juntos son el puente del modelo a tu entorno real: repos, bases, dashboards, colas, secretos.
Hooks lifecycleCiclo de vida dos hooksCiclo de vida de los hooks
PreToolUse, PostToolUse, UserPromptSubmit, Stop, Notification, SubagentStop. Hooks make the assistant deterministic where it must be: secrets blocking, formatters, audit logs, policy gates.PreToolUse, PostToolUse, UserPromptSubmit, Stop, Notification, SubagentStop. Hooks tornam o assistente determinístico onde precisa ser: bloqueio de segredos, formatadores, logs de auditoria, gates de política.PreToolUse, PostToolUse, UserPromptSubmit, Stop, Notification, SubagentStop. Los hooks hacen al asistente determinista donde debe serlo: bloqueo de secretos, formateadores, logs de auditoría, gates de política.
Orchestration flow and 6 prompt layersFluxo de orquestração e 6 camadas de promptFlujo de orquestración y 6 capas de prompt
A task enters, the router selects an agent, the agent loads skills, MCP tools, and runs through six prompt-integration layers: system, project, user, session, skill, tool. Knowing the order is half the win.Uma tarefa entra, o roteador seleciona um agente, o agente carrega skills, ferramentas MCP, e passa por seis camadas de integração de prompt: sistema, projeto, usuário, sessão, skill, ferramenta. Saber a ordem é metade da vitória.Una tarea entra, el router selecciona un agente, el agente carga skills, herramientas MCP, y atraviesa seis capas de integración de prompt: sistema, proyecto, usuario, sesión, skill, herramienta. Saber el orden es media victoria.
Configuration hierarchyHierarquia de configuraçãoJerarquía de configuración
Enterprise, project, user. Three tiers, last-write-wins with explicit precedence. Centralize policy at the top, ship developer freedom at the bottom, document the override rules in the middle.Enterprise, projeto, usuário. Três tiers, com último escreve vence e precedência explícita. Centralize política no topo, libere o desenvolvedor na base, documente overrides no meio.Enterprise, proyecto, usuario. Tres tiers, con último escribe gana y precedencia explícita. Centraliza política arriba, libera al desarrollador abajo, documenta los overrides en medio.
Why Routing Is the First Engineering Decision
The most common mistake teams make when adopting GitHub Copilot is treating it as a single generalist chat interface. Every task goes to the same agent. Every response draws on the same context window. Over time, this creates a predictable bottleneck: token overhead grows, output quality drifts, and the productivity gains promised by Copilot fail to materialize at scale.
The data is unambiguous. Production telemetry from GitHub Copilot Enterprise in Q1 2026 shows that a generalist agent handling tasks a specialized skill could answer directly consumes 3× more context tokens per task. At the individual developer level, this is noise. Across a team of dozens, it becomes a measurable cost driver.
The capability gap is equally stark. On SWE-bench, Claude Opus 4.5 resolves 74.4% of well-scoped bug fixes (tasks with tight, isolated requirements). On FeatureBench, representing real-world feature work, the same model without domain context drops to 11%. Add skill context (architecture patterns, coding conventions, domain vocabulary) and that figure climbs to approximately 38%. Skills close roughly 27 percentage points of the gap. The remaining distance requires custom agents with dedicated tool access.
The implication is direct: routing decisions, made deliberately and early, determine whether Copilot accelerates or stalls an engineering team.
Two Agent Types, One Fundamental Difference
GitHub Copilot’s runtime operates with two distinct agent types. Understanding the difference is the foundation of every routing decision.
A generalist agent is the default orchestrator. It handles 70-80% of tasks in a mature workspace, augmented by SKILL.md files when domain knowledge is required. It uses workspace-level shared tools and carries no dedicated identity file. It is the right choice for the majority of developer tasks: anything that benefits from domain knowledge injection without requiring exclusive tool access or a distinct operational identity.
A custom agent is a software component. It is defined by a .agent.md file that establishes its identity, exclusive tool connections, bounded scope, input/output contracts, and escalation rules. Custom agents connect to MCP servers, CLIs, and APIs that are not shared with other agents. They handle the 20-30% of tasks that require exclusive tool access, a distinct tone and identity (such as rigorous security review), or participation in a multi-stage pipeline with typed handoffs.
The ratio that signals a healthy workspace: approximately 1 custom agent per 8-12 skills. More custom agents than that suggests over-engineering. Fewer skills suggest under-specialization.
SKILL.md: Anatomy, Activation, and Maturity
A SKILL.md is not a prompt, not a config file, and not a script. It is a domain-specific knowledge artifact with a defined structure, a lifecycle, and three activation modes.
Every skill has five sections, no exceptions:
- Section 01, Description + SFA test: YAML frontmatter declaring
name,description,globs, andalwaysApply. The SFA test requires that Scope, Format, and Audience be explicit before the skill is used in production. - Section 02, Domain rules: Non-negotiable constraints, naming conventions, anti-patterns. The hard knowledge of the domain.
- Section 03, Step-by-step workflow: Numbered sequential steps explicit enough to be reproducible, with references to tools and scripts.
- Section 04, Output templates: Concrete examples of format, structure, and file naming. The agent matches templates, not imagination.
- Section 05, Validation checklist: Pass/fail criteria applied before delivery. If any item fails, the agent revises. This is a quality gate built directly into the skill.
Three activation modes govern when a skill loads:
- Glob match: a file enters context, the glob pattern matches, and the skill loads automatically. Efficient, requires no human action. Best for file-type specialization.
- alwaysApply: true loads the skill on every interaction regardless of context. Appropriate for cross-cutting concerns like brand rules, security standards, or coding conventions. It applies broadly but costs tokens, so use it sparingly.
- Explicit invoke: the orchestrator or user references the skill by name on demand. Precise and suitable for composite tasks involving multiple skills, but requires routing awareness.
The skill maturity model runs from level 1 to level 5. Level 1 is a ~40-line SKILL.md covering description and workflow. It is usable but fragile. Level 3 (the target for most enterprise skills) includes all five sections, scripts, portal references, enriched content, and tuned glob patterns. Level 4 adds automated tests and a CI gate. Level 5 is a version-pinned, cross-workspace registry entry with automated CI promotion. The skill becomes a first-class software asset.
Most teams ship level 1 skills that work. The cost appears later, when level 1 skills proliferate without promotion: inconsistent outputs, duplicate domain knowledge, and no quality gate.
Custom Agents: The .agent.md Contract
A custom agent is defined entirely by its .agent.md file, a six-section contract with the orchestrator:
- Identity and persona: name, role, tone, domain
- Tool manifest: exclusive MCP servers, CLIs, and APIs (not shared by default)
- Scope and boundaries: what the agent handles, and what it explicitly refuses
- Input/output contracts: the handoff payload accepted and the typed artifact returned
- Skills loaded: which SKILL.md files this agent loads for domain knowledge
- Escalation rules: conditions that trigger return to the orchestrator without completion
Four concrete agent examples from production workspaces illustrate the pattern:
| Agent | Exclusive Tools | Returns | Escalates On |
|---|---|---|---|
| Security agent | Vault MCP, Semgrep CLI, Snyk API | security-report.md (CVSS scores) | Critical CVE, credential exposure |
| Test agent | GitHub Actions MCP, Jest, coverage tool | Test suite + execution results | Flaky tests |
| Modernization agent | Terraform MCP, Azure SDK | Migration plan + diff | Data loss risk |
| Documentation agent | Confluence MCP, brand style guide | Published structured docs | Out-of-scope code review |
Each agent handles one bounded domain. Boundaries are explicit, not emergent. The orchestrator knows which agent to invoke based on task type detected during routing.
Orchestration: Four Phases, One Decision Point
Every request to a Copilot workspace passes through four phases:
- Entry: the orchestrator receives the request, loads its own
.agent.mdidentity, and classifies the task type. - Analysis + routing: the decision tree is evaluated. A skill search determines whether a SKILL.md exists for the domain. The outcome is either Path A (custom agent + skill) or Path B (generalist + skill).
- Execution: skills are loaded, domain knowledge is injected,
.instructions.mdis applied automatically, and the task runs with full context. - Validation + delivery: output is validated against the skill checklist; the quality gate checks format, content, and conventions before the final response reaches the user.
The routing decision is made once, in Phase 2, using a four-question decision tree:
- Does the task require exclusive tool access (MCP, API, CLI)? If yes → custom agent + skill.
- Does the task require a distinct identity or tone? If yes → custom agent + skill.
- Is this a multi-stage pipeline with handoffs between agents? If yes → custom agent pipeline.
- Does a SKILL.md exist that covers this domain? If yes → generalist + skill. If no → generalist only, or create the skill first.
The orchestrator is the only agent the user interacts with directly. All sub-agents operate behind it. Every handoff returns to the orchestrator. Agents never communicate directly with each other.
Context accumulates intentionally at every handoff. In a Plan → Code → Test → Security pipeline: Planning receives the user request. Coding receives the request plus the plan. Testing receives the request, plan, and code. Security receives the complete picture: request, plan, code, and test results. The security agent can only do its job if it sees everything upstream produced. No handoff loses prior work.
Anti-Patterns and Diagnostics
Four anti-patterns appear consistently before any best practice takes hold:
- Skill-as-megaprompt: a 2,000-line SKILL.md covering everything, activating on every glob. Token overhead per call exceeds the value of the knowledge. Fix: split into three targeted skills, each passing the SFA test.
- Agent-for-everything: a single custom agent with all permissions and no bounded scope. The first incident compromises the entire workspace. RBAC and scope boundaries are non-negotiable.
- Skills never versioned: SKILL.md files edited in place without version control. Output quality changes silently, with no rollback and no change log. Every SKILL.md should be treated as code: version, review, test, promote.
- Routing by intuition: per-call decisions based on feel, with no decision tree and no routing logic. Inconsistent results, inconsistent cost, no measurement baseline. The four-question tree takes one hour to implement.
Six diagnostic questions surface gaps in any workspace. A “no” to any of them is worth addressing:
- Do you know every skill active in your workspace right now?
- Do all custom agents have a
.agent.mdwith an explicit tool list? - Can you trace which skill was loaded for any given task output?
- Is there a routing decision tree, or does each team member decide ad hoc?
- Are all skills version-controlled and reviewed before distribution?
- Is the ratio of custom agents to skills at 1:8 or better?
The 90-Day Playbook
Teams that consistently scale Copilot value follow a structured progression:
Days 1-30 (Foundation): Complete a full skill inventory with SFA scores. Adopt the decision tree as a team. Review all custom agents’ .agent.md files. Enable skill activation logging. Outcome: a routing baseline.
Days 31-60 (Contract): Promote the top five skills to maturity level 3. Add scripts to automation-eligible skills. Stand up the first pipeline: plan, code, and test handoff live. Measure token consumption per task. Outcome: first pipeline delivering typed artifacts.
Days 61-90 (Measure): Publish a shared skill library. Apply the decision tree to 80%+ of tasks. Track token efficiency weekly per skill. Document a replicable playbook for adding new skills. Outcome: skill library operational, quality measurable.
The goal of 90 days is not perfect skills. It is a repeatable process for making skills better. One hour of routing design (implementing the four-question decision tree) can reduce average token spend by 30% and improve output consistency across the entire team.
Por Que o Roteamento É a Primeira Decisão de Engenharia
O erro mais comum que equipes cometem ao adotar o GitHub Copilot é tratá-lo como uma única interface de chat generalista. Toda tarefa vai para o mesmo agente. Toda resposta consome a mesma janela de contexto. Com o tempo, isso cria um gargalo previsível: o overhead de tokens cresce, a qualidade das saídas oscila e os ganhos de produtividade prometidos pelo Copilot deixam de se materializar em escala.
Os dados são inequívocos. A telemetria de produção do GitHub Copilot Enterprise no primeiro trimestre de 2026 mostra que um agente generalista lidando com tarefas que uma skill especializada poderia responder diretamente consome 3× mais tokens de contexto por tarefa. No nível individual, isso é ruído. Numa equipe de dezenas de desenvolvedores, torna-se um driver de custo mensurável.
O gap de capacidade é igualmente expressivo. No SWE-bench, o Claude Opus 4.5 resolve 74,4% dos bugs bem delimitados (tarefas com requisitos precisos e isolados). No FeatureBench, que representa trabalho de feature do mundo real, o mesmo modelo sem contexto de domínio cai para 11%. Com contexto de skill (padrões de arquitetura, convenções de código, vocabulário de domínio), esse número sobe para aproximadamente 38%. Skills fecham cerca de 27 pontos percentuais desse gap. A distância restante exige custom agents com acesso exclusivo a ferramentas.
A implicação é direta: decisões de roteamento, tomadas de forma deliberada e antecipada, determinam se o Copilot acelera ou paralisa uma equipe de engenharia.
Dois Tipos de Agente, Uma Diferença Fundamental
O runtime do GitHub Copilot opera com dois tipos distintos de agente. Compreender essa diferença é a base de toda decisão de roteamento.
Um agente generalista é o orquestrador padrão. Ele lida com 70-80% das tarefas em um workspace maduro, potencializado por arquivos SKILL.md quando conhecimento de domínio é necessário. Ele utiliza ferramentas compartilhadas no nível do workspace e não possui arquivo de identidade dedicado. É a escolha certa para a maioria das tarefas de desenvolvimento: qualquer coisa que se beneficie da injeção de conhecimento de domínio sem exigir acesso exclusivo a ferramentas ou uma identidade operacional distinta.
Um custom agent é um componente de software. Ele é definido por um arquivo .agent.md que estabelece sua identidade, conexões exclusivas com ferramentas, escopo delimitado, contratos de entrada/saída e regras de escalação. Custom agents se conectam a servidores MCP, CLIs e APIs que não são compartilhados com outros agentes. Eles lidam com os 20-30% de tarefas que exigem acesso exclusivo a ferramentas, um tom e identidade distintos (como revisão de segurança rigorosa) ou participação em um pipeline multi-etapa com handoffs tipados.
A proporção que indica um workspace saudável: aproximadamente 1 custom agent para cada 8-12 skills. Mais custom agents do que isso sinaliza over-engineering. Menos skills sinaliza subespecialização.
SKILL.md: Anatomia, Ativação e Maturidade
Um SKILL.md não é um prompt, não é um arquivo de configuração e não é um script. É um artefato de conhecimento de domínio com uma estrutura definida, um ciclo de vida e três modos de ativação.
Toda skill tem cinco seções, sem exceções:
- Seção 01, Descrição + teste SFA: Frontmatter YAML declarando
name,description,globsealwaysApply. O teste SFA exige que Scope (Escopo), Format (Formato) e Audience (Público) sejam explícitos antes de a skill ser usada em produção. - Seção 02, Regras de domínio: Restrições inegociáveis, convenções de nomenclatura, anti-padrões. O conhecimento duro do domínio.
- Seção 03, Fluxo de trabalho passo a passo: Etapas numeradas e sequenciais explícitas o suficiente para serem reproduzíveis, com referências a ferramentas e scripts.
- Seção 04, Templates de saída: Exemplos concretos de formato, estrutura e nomenclatura de arquivos. O agente segue os templates, não a imaginação.
- Seção 05, Checklist de validação: Critérios de aprovação/reprovação aplicados antes da entrega. Se algum item falhar, o agente revisa. Este é um quality gate embutido diretamente na skill.
Três modos de ativação governam quando uma skill é carregada:
- Glob match: um arquivo entra no contexto, o padrão glob é correspondido e a skill é carregada automaticamente. Eficiente, não requer ação humana. Ideal para especialização por tipo de arquivo.
- alwaysApply: true carrega a skill em toda interação, independentemente do contexto. Apropriado para preocupações transversais como regras de marca, padrões de segurança ou convenções de código. Aplica-se de forma ampla, mas custa tokens, então use com parcimônia.
- Invocação explícita: o orquestrador ou usuário referencia a skill pelo nome sob demanda. Precisa e adequada para tarefas compostas envolvendo múltiplas skills, mas requer consciência de roteamento.
O modelo de maturidade de skills vai do nível 1 ao nível 5. O nível 1 é um SKILL.md de ~40 linhas cobrindo descrição e fluxo de trabalho. É utilizável, mas frágil. O nível 3 (o alvo para a maioria das skills enterprise) inclui todas as cinco seções, scripts, referências a portais, conteúdo enriquecido e padrões glob ajustados. O nível 4 adiciona testes automatizados e um gate de CI. O nível 5 é uma entrada de registro cross-workspace com versão fixada e promoção automatizada via CI. A skill passa a ser tratada como um ativo de software de primeira classe.
A maioria das equipes começa com skills de nível 1 que funcionam. O custo aparece depois, quando skills de nível 1 se proliferam sem promoção: saídas inconsistentes, conhecimento de domínio duplicado e nenhum quality gate.
Custom Agents: O Contrato .agent.md
Um custom agent é definido inteiramente pelo seu arquivo .agent.md, um contrato de seis seções com o orquestrador:
- Identidade e persona: nome, papel, tom, domínio
- Manifesto de ferramentas: servidores MCP exclusivos, CLIs e APIs (não compartilhados por padrão)
- Escopo e limites: o que o agente trata e o que ele explicitamente recusa
- Contratos de entrada/saída: o payload de handoff aceito e o artefato tipado retornado
- Skills carregadas: quais arquivos SKILL.md este agente carrega para conhecimento de domínio
- Regras de escalação: condições que acionam retorno ao orquestrador sem conclusão
Quatro exemplos concretos de agentes em workspaces de produção ilustram o padrão:
| Agente | Ferramentas Exclusivas | Retorna | Escala Em |
|---|---|---|---|
| Security agent | Vault MCP, Semgrep CLI, Snyk API | security-report.md (scores CVSS) | CVE crítico, exposição de credenciais |
| Test agent | GitHub Actions MCP, Jest, ferramenta de cobertura | Suite de testes + resultados de execução | Testes instáveis (flaky) |
| Modernization agent | Terraform MCP, Azure SDK | Plano de migração + diff | Risco de perda de dados |
| Documentation agent | Confluence MCP, guia de estilo de marca | Documentação estruturada publicada | Revisão de código fora do escopo |
Cada agente trata um domínio delimitado. Os limites são explícitos, não emergentes. O orquestrador sabe qual agente invocar com base no tipo de tarefa detectado durante o roteamento.
Orquestração: Quatro Fases, Um Ponto de Decisão
Toda requisição a um workspace Copilot passa por quatro fases:
- Entrada: o orquestrador recebe a requisição, carrega sua própria identidade
.agent.mde classifica o tipo de tarefa. - Análise + roteamento: a árvore de decisão é avaliada. Uma busca de skills determina se existe um SKILL.md para o domínio. O resultado é o Caminho A (custom agent + skill) ou o Caminho B (generalista + skill).
- Execução: skills são carregadas, conhecimento de domínio é injetado,
.instructions.mdé aplicado automaticamente e a tarefa executa com contexto completo. - Validação + entrega: a saída é validada contra o checklist da skill; o quality gate verifica formato, conteúdo e convenções antes de a resposta final chegar ao usuário.
A decisão de roteamento é tomada uma única vez, na Fase 2, usando uma árvore de decisão com quatro perguntas:
- A tarefa requer acesso exclusivo a ferramentas (MCP, API, CLI)? Se sim → custom agent + skill.
- A tarefa requer identidade ou tom distintos? Se sim → custom agent + skill.
- É um pipeline multi-etapa com handoffs entre agentes? Se sim → pipeline de custom agents.
- Existe um SKILL.md que cobre este domínio? Se sim → generalista + skill. Se não → apenas generalista, ou criar a skill primeiro.
O orquestrador é o único agente com quem o usuário interage diretamente. Todos os sub-agentes operam por trás dele. Todo handoff retorna ao orquestrador. Agentes nunca se comunicam diretamente entre si.
O contexto se acumula intencionalmente a cada handoff. Em um pipeline Plan → Code → Test → Security: Planning recebe a requisição do usuário. Coding recebe a requisição mais o plano. Testing recebe requisição, plano e código. Security recebe o quadro completo: requisição, plano, código e resultados de teste. O agente de segurança só pode fazer seu trabalho se tiver acesso a tudo que foi produzido anteriormente. Nenhum handoff perde trabalho prévio.
Anti-Padrões e Diagnósticos
Quatro anti-padrões aparecem consistentemente antes de qualquer boa prática se consolidar:
- Skill-como-megaprompt: um SKILL.md de 2.000 linhas cobrindo tudo, ativando em cada glob. O overhead de tokens por chamada supera o valor do conhecimento. Solução: dividir em três skills focadas, cada uma passando no teste SFA.
- Agente-para-tudo: um único custom agent com todas as permissões e nenhum escopo delimitado. O primeiro incidente compromete todo o workspace. RBAC e limites de escopo são inegociáveis.
- Skills nunca versionadas: arquivos SKILL.md editados in place sem controle de versão. A qualidade das saídas muda silenciosamente, sem rollback e sem changelog. Todo SKILL.md deve ser tratado como código: versionar, revisar, testar e promover.
- Roteamento por intuição: decisões por chamada baseadas em feeling, sem árvore de decisão e sem lógica de roteamento. Resultados inconsistentes, custos inconsistentes, nenhuma baseline de medição. A árvore com quatro perguntas leva uma hora para implementar.
Seis perguntas diagnósticas revelam lacunas em qualquer workspace. Um “não” a qualquer uma delas vale ser endereçado:
- Você conhece todas as skills ativas no seu workspace agora?
- Todos os custom agents têm um
.agent.mdcom lista explícita de ferramentas? - Você consegue rastrear qual skill foi carregada para qualquer saída de tarefa?
- Existe uma árvore de decisão de roteamento, ou cada membro da equipe decide de forma ad hoc?
- Todas as skills são versionadas e revisadas antes da distribuição?
- A proporção de custom agents para skills está em 1:8 ou melhor?
O Playbook de 90 Dias
Equipes que escalam o valor do Copilot de forma consistente seguem uma progressão estruturada:
Dias 1-30 (Fundação): Inventário completo de skills com scores SFA. Adoção da árvore de decisão pela equipe. Revisão dos arquivos .agent.md de todos os custom agents. Habilitação do log de ativação de skills. Resultado: baseline de roteamento estabelecida.
Dias 31-60 (Contrato): Promoção das cinco principais skills para o nível de maturidade 3. Adição de scripts às skills elegíveis para automação. Primeiro pipeline ao vivo: handoff de plan, code e test funcionando. Medição do consumo de tokens por tarefa. Resultado: primeiro pipeline entregando artefatos tipados.
Dias 61-90 (Medição): Publicação de uma biblioteca compartilhada de skills. Aplicação da árvore de decisão em 80%+ das tarefas. Rastreamento semanal da eficiência de tokens por skill. Documentação de um playbook replicável para adicionar novas skills. Resultado: biblioteca de skills operacional e qualidade mensurável.
O objetivo dos 90 dias não é ter skills perfeitas. É ter um processo repetível para torná-las melhores. Uma hora de design de roteamento (implementando a árvore de decisão com quatro perguntas) pode reduzir o gasto médio de tokens em 30% e melhorar a consistência de saída em toda a equipe.
Por Qué el Enrutamiento Es la Primera Decisión de Ingeniería
El error más común que cometen los equipos al adoptar GitHub Copilot es tratarlo como una única interfaz de chat generalista. Cada tarea va al mismo agente. Cada respuesta consume la misma ventana de contexto. Con el tiempo, esto genera un cuello de botella predecible: el overhead de tokens crece, la calidad de los resultados se deteriora y las ganancias de productividad prometidas por Copilot no llegan a materializarse a escala.
Los datos son inequívocos. La telemetría de producción de GitHub Copilot Enterprise en el primer trimestre de 2026 muestra que un agente generalista manejando tareas que una skill especializada podría responder directamente consume 3× más tokens de contexto por tarea. A nivel individual, esto es ruido. En un equipo de decenas de desarrolladores, se convierte en un driver de costos medible.
La brecha de capacidad es igualmente marcada. En SWE-bench, Claude Opus 4.5 resuelve 74,4% de los bugs bien delimitados (tareas con requisitos precisos y aislados). En FeatureBench, que representa trabajo de features del mundo real, el mismo modelo sin contexto de dominio cae a 11%. Al añadir contexto de skill (patrones de arquitectura, convenciones de código, vocabulario de dominio), esa cifra sube a aproximadamente 38%. Las skills cierran alrededor de 27 puntos porcentuales de esa brecha. La distancia restante requiere custom agents con acceso exclusivo a herramientas.
La implicación es directa: las decisiones de enrutamiento, tomadas de forma deliberada y temprana, determinan si Copilot acelera o paraliza a un equipo de ingeniería.
Dos Tipos de Agente, Una Diferencia Fundamental
El runtime de GitHub Copilot opera con dos tipos distintos de agente. Comprender la diferencia es la base de toda decisión de enrutamiento.
Un agente generalista es el orquestador predeterminado. Maneja 70-80% de las tareas en un workspace maduro, potenciado por archivos SKILL.md cuando se necesita conocimiento de dominio. Utiliza herramientas compartidas a nivel del workspace y no tiene archivo de identidad dedicado. Es la elección correcta para la mayoría de las tareas de desarrollo: cualquier cosa que se beneficie de la inyección de conocimiento de dominio sin requerir acceso exclusivo a herramientas ni una identidad operacional distinta.
Un custom agent es un componente de software. Está definido por un archivo .agent.md que establece su identidad, conexiones exclusivas con herramientas, alcance delimitado, contratos de entrada/salida y reglas de escalación. Los custom agents se conectan a servidores MCP, CLIs y APIs que no se comparten con otros agentes. Manejan el 20-30% de las tareas que requieren acceso exclusivo a herramientas, un tono e identidad distintos (como la revisión rigurosa de seguridad) o participación en un pipeline de múltiples etapas con handoffs tipados.
La proporción que indica un workspace saludable: aproximadamente 1 custom agent por cada 8-12 skills. Más custom agents que eso sugiere over-engineering. Menos skills sugiere subespecialización.
SKILL.md: Anatomía, Activación y Madurez
Un SKILL.md no es un prompt, no es un archivo de configuración y no es un script. Es un artefato de conocimiento de dominio con una estructura definida, un ciclo de vida y tres modos de activación.
Toda skill tiene cinco secciones, sin excepciones:
- Sección 01, Descripción + prueba SFA: Frontmatter YAML declarando
name,description,globsyalwaysApply. La prueba SFA requiere que Scope (Alcance), Format (Formato) y Audience (Audiencia) sean explícitos antes de que la skill se use en producción. - Sección 02, Reglas de dominio: Restricciones no negociables, convenciones de nomenclatura, anti-patrones. El conocimiento duro del dominio.
- Sección 03, Flujo de trabajo paso a paso: Pasos numerados y secuenciales, suficientemente explícitos para ser reproducibles, con referencias a herramientas y scripts.
- Sección 04, Plantillas de salida: Ejemplos concretos de formato, estructura y nomenclatura de archivos. El agente sigue las plantillas, no la imaginación.
- Sección 05, Lista de verificación de validación: Criterios de aprobación/rechazo aplicados antes de la entrega. Si algún elemento falla, el agente revisa. Este es un quality gate integrado directamente en la skill.
Tres modos de activación gobiernan cuándo se carga una skill:
- Glob match: un archivo entra al contexto, el patrón glob coincide y la skill se carga automáticamente. Eficiente, no requiere acción humana. Ideal para especialización por tipo de archivo.
- alwaysApply: true carga la skill en cada interacción independientemente del contexto. Apropiado para preocupaciones transversales como reglas de marca, estándares de seguridad o convenciones de código. Se aplica de forma amplia, pero cuesta tokens, así que úsalo con moderación.
- Invocación explícita: el orquestrador o el usuario referencia la skill por nombre bajo demanda. Precisa y adecuada para tareas compuestas que involucran múltiples skills, pero requiere conciencia de enrutamiento.
El modelo de madurez de skills va del nivel 1 al nivel 5. El nivel 1 es un SKILL.md de ~40 líneas cubriendo descripción y flujo de trabajo. Es utilizable, pero frágil. El nivel 3 (el objetivo para la mayoría de las skills enterprise) incluye las cinco secciones, scripts, referencias a portales, contenido enriquecido y patrones glob ajustados. El nivel 4 agrega pruebas automatizadas y un gate de CI. El nivel 5 es una entrada en un registro cross-workspace con versión fija y promoción automatizada vía CI. La skill pasa a tratarse como un activo de software de primera clase.
La mayoría de los equipos comienza con skills de nivel 1 que funcionan. El costo aparece después, cuando las skills de nivel 1 proliferan sin promoción: resultados inconsistentes, conocimiento de dominio duplicado y ningún quality gate.
Custom Agents: El Contrato .agent.md
Un custom agent está definido en su totalidad por su archivo .agent.md, un contrato de seis secciones con el orquestrador:
- Identidad y persona: nombre, rol, tono, dominio
- Manifiesto de herramientas: servidores MCP exclusivos, CLIs y APIs (no compartidos por defecto)
- Alcance y límites: qué maneja el agente y qué rechaza explícitamente
- Contratos de entrada/salida: el payload de handoff aceptado y el artefato tipado retornado
- Skills cargadas: qué archivos SKILL.md carga este agente para el conocimiento de dominio
- Reglas de escalación: condiciones que activan el retorno al orquestrador sin completar
Cuatro ejemplos concretos de agentes en workspaces de producción ilustran el patrón:
| Agente | Herramientas Exclusivas | Retorna | Escala En |
|---|---|---|---|
| Security agent | Vault MCP, Semgrep CLI, Snyk API | security-report.md (puntajes CVSS) | CVE crítico, exposición de credenciales |
| Test agent | GitHub Actions MCP, Jest, herramienta de cobertura | Suite de pruebas + resultados de ejecución | Pruebas inestables (flaky) |
| Modernization agent | Terraform MCP, Azure SDK | Plan de migración + diff | Riesgo de pérdida de datos |
| Documentation agent | Confluence MCP, guía de estilo de marca | Documentación estructurada publicada | Revisión de código fuera del alcance |
Cada agente maneja un dominio delimitado. Los límites son explícitos, no emergentes. El orquestrador sabe qué agente invocar según el tipo de tarea detectado durante el enrutamiento.
Orquestación: Cuatro Fases, Un Punto de Decisión
Cada solicitud a un workspace de Copilot pasa por cuatro fases:
- Entrada: el orquestrador recibe la solicitud, carga su propia identidad
.agent.mdy clasifica el tipo de tarea. - Análisis + enrutamiento: se evalúa el árbol de decisión. Una búsqueda de skills determina si existe un SKILL.md para el dominio. El resultado es la Ruta A (custom agent + skill) o la Ruta B (generalista + skill).
- Ejecución: se cargan las skills, se inyecta el conocimiento de dominio, se aplica automáticamente
.instructions.mdy la tarea se ejecuta con contexto completo. - Validación + entrega: la salida se valida contra la lista de verificación de la skill; el quality gate verifica formato, contenido y convenciones antes de que la respuesta final llegue al usuario.
La decisión de enrutamiento se toma una única vez, en la Fase 2, usando un árbol de decisión con cuatro preguntas:
- ¿La tarea requiere acceso exclusivo a herramientas (MCP, API, CLI)? Si sí → custom agent + skill.
- ¿La tarea requiere identidad o tono distintos? Si sí → custom agent + skill.
- ¿Es un pipeline de múltiples etapas con handoffs entre agentes? Si sí → pipeline de custom agents.
- ¿Existe un SKILL.md que cubra este dominio? Si sí → generalista + skill. Si no → solo generalista, o crear la skill primero.
El orquestrador es el único agente con el que el usuario interactúa directamente. Todos los sub-agentes operan detrás de él. Cada handoff regresa al orquestrador. Los agentes nunca se comunican directamente entre sí.
El contexto se acumula intencionalmente en cada handoff. En un pipeline Plan → Code → Test → Security: Planning recibe la solicitud del usuario. Coding recibe la solicitud más el plan. Testing recibe solicitud, plan y código. Security recibe el panorama completo: solicitud, plan, código y resultados de pruebas. El agente de seguridad solo puede hacer su trabajo si ve todo lo que se produjo anteriormente. Ningún handoff pierde trabajo previo.
Anti-Patrones y Diagnósticos
Cuatro anti-patrones aparecen consistentemente antes de que se establezca cualquier buena práctica:
- Skill-como-megaprompt: un SKILL.md de 2.000 líneas cubriendo todo, activándose en cada glob. El overhead de tokens por llamada supera el valor del conocimiento. Solución: dividir en tres skills enfocadas, cada una pasando la prueba SFA.
- Agente-para-todo: un único custom agent con todos los permisos y ningún alcance delimitado. El primer incidente compromete todo el workspace. RBAC y límites de alcance son no negociables.
- Skills nunca versionadas: archivos SKILL.md editados in place sin control de versiones. La calidad de las salidas cambia silenciosamente, sin rollback y sin registro de cambios. Todo SKILL.md debe tratarse como código: versionar, revisar, probar y promover.
- Enrutamiento por intuición: decisiones por llamada basadas en el instinto, sin árbol de decisión y sin lógica de enrutamiento. Resultados inconsistentes, costos inconsistentes, ninguna línea base de medición. El árbol de cuatro preguntas tarda una hora en implementarse.
Seis preguntas diagnósticas revelan brechas en cualquier workspace. Un “no” a cualquiera de ellas vale la pena abordarlo:
- ¿Conoces todas las skills activas en tu workspace ahora mismo?
- ¿Todos los custom agents tienen un
.agent.mdcon lista explícita de herramientas? - ¿Puedes rastrear qué skill se cargó para cualquier salida de tarea?
- ¿Existe un árbol de decisión de enrutamiento, o cada miembro del equipo decide de forma ad hoc?
- ¿Todas las skills están bajo control de versiones y son revisadas antes de la distribución?
- ¿La proporción de custom agents a skills está en 1:8 o mejor?
El Playbook de 90 Días
Los equipos que escalan el valor de Copilot de forma consistente siguen una progresión estructurada:
Días 1-30 (Fundación): Inventario completo de skills con puntajes SFA. Adopción del árbol de decisión por el equipo. Revisión de los archivos .agent.md de todos los custom agents. Habilitación del log de activación de skills. Resultado: baseline de enrutamiento establecida.
Días 31-60 (Contrato): Promoción de las cinco principales skills al nivel de madurez 3. Adición de scripts a las skills elegibles para automatización. Primer pipeline en vivo: handoff de plan, code y test funcionando. Medición del consumo de tokens por tarea. Resultado: primer pipeline entregando artefatos tipados.
Días 61-90 (Medición): Publicación de una biblioteca compartida de skills. Aplicación del árbol de decisión en el 80%+ de las tareas. Seguimiento semanal de la eficiencia de tokens por skill. Documentación de un playbook replicable para agregar nuevas skills. Resultado: biblioteca de skills operativa y calidad medible.
El objetivo de los 90 días no es tener skills perfectas. Es tener un proceso repetible para hacerlas mejores. Una hora de diseño de enrutamiento (implementando el árbol de decisión de cuatro preguntas) puede reducir el gasto promedio de tokens en 30% y mejorar la consistencia de salida en todo el equipo.
Three workspace metrics, three sources.Três métricas do workspace, três fontes.Tres métricas del workspace, tres fuentes.
Anchor every claim to a number that survives a security review. These three baselines come from observed Copilot Enterprise rollouts and the GitHub Octoverse 2025 telemetry.Ancore toda alegação a um número que sobreviva à revisão de segurança. Estes três baselines vêm de rollouts observados de Copilot Enterprise e telemetria Octoverse 2025 do GitHub.Ancla cada afirmación a un número que sobreviva la revisión de seguridad. Estos tres baselines vienen de rollouts observados de Copilot Enterprise y la telemetría Octoverse 2025 de GitHub.
The exact order in which Copilot composes the active prompt at every turn. Knowing the order is what lets a platform team move policy from the system layer to the project layer without breaking developer flow. Misordering it is the most common cause of leaked guardrails.A ordem exata em que o Copilot compõe o prompt ativo em cada turn. Saber a ordem permite ao time de plataforma mover política da camada sistema para a de projeto sem quebrar o flow do dev. Errar a ordem é a causa mais comum de guardrail vazado.El orden exacto en que Copilot compone el prompt activo en cada turno. Saber el orden permite al equipo de plataforma mover política de la capa sistema a la de proyecto sin romper el flujo del dev. Errar el orden es la causa más común de guardrail filtrado.
PreToolUse, PostToolUse, UserPromptSubmit, Stop, Notification, SubagentStop. The six events at which a deterministic hook can run. Secrets blocking, formatter, audit log, and policy gate are the four hooks every enterprise rollout should ship on day one.PreToolUse, PostToolUse, UserPromptSubmit, Stop, Notification, SubagentStop. Os seis eventos onde um hook determinístico pode rodar. Bloqueio de segredos, formatter, log de auditoria e gate de política são os quatro hooks que todo rollout corporativo entrega no dia 1.PreToolUse, PostToolUse, UserPromptSubmit, Stop, Notification, SubagentStop. Los seis eventos donde puede correr un hook determinista. Bloqueo de secretos, formatter, log de auditoría y gate de política son los cuatro hooks que todo rollout corporativo entrega el día 1.
The three configuration tiers with explicit precedence. Enterprise locks policy and security defaults. Project sets repo-specific behavior. User personalizes inside what the upper tiers allow. The override rules belong in the project tier, documented as a table the security team can audit.Três tiers de configuração com precedência explícita. Enterprise tranca política e defaults de segurança. Projeto define comportamento por repo. Usuário personaliza dentro do que as camadas superiores permitem. As regras de override ficam no tier de projeto, documentadas em tabela auditável.Tres tiers de configuración con precedencia explícita. Enterprise bloquea política y defaults de seguridad. Proyecto define comportamiento por repo. Usuario personaliza dentro de lo que permiten las capas superiores. Las reglas de override viven en el tier de proyecto, documentadas en tabla auditable.
The sources behind the claims on this page. Every link is public and verifiable. As fontes por trás das afirmações desta página. Todos os links são públicos e verificáveis. Las fuentes detrás de las afirmaciones de esta página. Todos los enlaces son públicos y verificables.