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

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, and alwaysApply. 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 — the skill loads on every interaction regardless of context. Appropriate for cross-cutting concerns like brand rules, security standards, or coding conventions. High power, but high token cost — use 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 — 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 treated as 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:

1. Identity and persona — name, role, tone, domain
2. Tool manifest — exclusive MCP servers, CLIs, and APIs (not shared by default)
3. Scope and boundaries — what the agent handles, and what it explicitly refuses
4. Input/output contracts — the handoff payload accepted and the typed artifact returned
5. Skills loaded — which SKILL.md files this agent loads for domain knowledge
6. 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:

1. Entry — the orchestrator receives the request, loads its own .agent.md identity, and classifies the task type.
2. 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).
3. Execution — skills are loaded, domain knowledge is injected, .instructions.md is applied automatically, and the task runs with full context.
4. 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:

1. Does the task require exclusive tool access (MCP, API, CLI)? If yes → custom agent + skill.
2. Does the task require a distinct identity or tone? If yes → custom agent + skill.
3. Is this a multi-stage pipeline with handoffs between agents? If yes → custom agent pipeline.
4. 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:

1. Do you know every skill active in your workspace right now?
2. Do all custom agents have a .agent.md with an explicit tool list?
3. Can you trace which skill was loaded for any given task output?
4. Is there a routing decision tree, or does each team member decide ad hoc?
5. Are all skills version-controlled and reviewed before distribution?
6. 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.