engineer-copilot-agent

# Engineer Copilot Agent Use this skill to create or improve GitHub Copilot custom agents. Treat triggering, routing, handoffs, and prompt size as separate concerns. Keep the top-level agent contract lean. Read `references/copilot-agent-standard.md` for the baseline contract and `references/context-minimization-loop.md` before editing. ## When to use this skill Use it when the user wants to: - create a new Copilot custom agent - improve an existing `.agent.md` file - remove stale tool, skill, or agent names - tighten tool-calling or MCP skill routing - clarify subagent handoffs and ownership - trim a bloated agent prompt - add eval coverage for routing regressions Do not use this skill for prompt-only or skill-only work unless the target artifact is a Copilot custom agent contract or the user explicitly wants to design one. ## Required inputs - Target `.agent.md` path, or a description of the agent to create - Repo root when runtime surface discovery matters - Improvement focus: triggering, routing, handoffs, structure, evals, or all - Known failure modes such as under-triggering, over-triggering, stale names, bad handoffs, or prompt bloat ## Core workflow Follow this order: 1. Run `python scripts/discover_runtime_surface.py --repo-root <repo-root> --json`. 2. Reconcile discovered repo surfaces against the live session inventory. If they differ, trust the live session. 3. Run `python scripts/validate_agent.py <agent-path> --repo-root <repo-root> --json`. 4. Run `python scripts/analyze_agent_body.py <agent-path> --repo-root <repo-root> --json`. 5. Fix validation errors before rewriting for style. 6. Fix stale or invented routing next. 7. Trim prompt body last by moving standards to `references/` and mechanical checks to `scripts/`. 8. Re-run discovery, validation, and analysis after each meaningful revision. ## Four concern separation ### Frontmatter Optimize discoverability and fit: - keep `name`, `description`, and hints specific - expose only real tools and handoff surfaces - avoid body-level execution detail in frontmatter ### Routing Name only tools, skills, helpers, and agents that actually exist in the workspace or live session. - Discover before naming helpers. - When names drift, live inventory overrides stale repo text. - Do not invent MCP routing, helper names, or handoff targets. ### Handoffs Make ownership explicit: - state what the agent should do directly - state what should be handed off - avoid overlapping ownership across agents - avoid handoffs that are wasteful, circular, or unsupported ### Minimization Keep the `.agent.md` file as a routing layer. - put standards and examples in `references/` - put deterministic checks and repeated summaries in `scripts/` - remove prose that only duplicates deeper assets ## Recursive minimization loop Use a recursive pass until the prompt is only as large as needed: 1. Draft or repair the routing layer. 2. Move standards, examples, and extended guidance into focused references. 3. Move mechanical checks and inventory logic into scripts. 4. Delete duplicated prose from the agent body. 5. Re-read the remaining prompt and trim again. Stop when each remaining section is necessary for triggering, routing, handoffs, or bounded execution. ## Evals guidance When the user asks for evals, prefer coverage that catches: - invented tools, skills, or handoff targets - stale helper names - missing discovery before concrete helper naming - missing discovery-to-load-to-run ordering for MCP skill usage - prompt bloat that should have been pushed into references or scripts ## Output contract When improving a custom agent, return: 1. Runtime surface summary 2. Validation results 3. Analysis results 4. Improvement plan 5. Changes made 6. Re-validation status and remaining risks