GitHub Copilot Best Practices

Use this file for GitHub Copilot-specific operating practice. Use ../routing.md for host-neutral owner selection and codex.md/claude.md/qwen.md for other host references. Do not copy Copilot-only workflow advice into shared docs unless there is matching surface evidence.

Operating Frame

Treat Copilot as a configured teammate across two surfaces: Copilot CLI and the IDE agent. Both read the same repository instruction and Skill locations, so durable guidance placed under .github/ and AGENTS.md serves every surface. Move repeated guidance into instructions, configure Copilot for the real workflow, connect external systems through MCP, turn repeated work into Skills, and automate only stable workflows through hooks.

Prompt Shape

A strong first prompt has four parts:

• Goal: the change, bug, review, artifact, or decision needed.
• Context: files, folders, docs, examples, logs, errors, or other material Copilot should inspect.
• Constraints: architecture rules, safety limits, review standards, platform requirements, and do-not-touch boundaries.
• Done when: tests, checks, behavior, output files, or review evidence that prove the task is complete.

Durable Guidance

Copilot combines every matching instruction file rather than choosing one, so keep each file scoped and non-contradictory:

• AGENTS.md for repo layout, commands, conventions, and what "done" means.
• .github/copilot-instructions.md for Copilot-specific repository guidance.
• .github/instructions/*.instructions.md for path-scoped guidance. A file with no applyTo glob is never auto-applied.
• ~/.copilot/copilot-instructions.md and ~/.copilot/instructions/ for personal defaults that should not live in the repository.

Keep context files short and practical. Put large or conditional detail in linked references. When Copilot repeats a mistake, update durable guidance only when the lesson is reusable.

Configuration

Copilot settings cascade, with later layers overriding earlier ones: built-in defaults, managed policy, ~/.copilot/settings.json, .github/copilot/settings.json, then environment variables and command flags.

• Keep permission and approval settings tight until a trusted workflow needs more access.
• Use COPILOT_HOME to isolate a Copilot home for testing.
• ~/.copilot/config.json is automatically managed application state, not user configuration. Read it for installed-plugin metadata only.

Skills, Agents, and Plugins

Turn a repeated workflow into a Skill when it has stable triggers, inputs, steps, outputs, and validation. Skill and Agent resolution is first-found-wins, and plugin-provided assets are the lowest local tier, so a project or personal asset always wins over a plugin asset of the same name.

• Project Skills: .github/skills/, .agents/skills/, .claude/skills/.
• Personal Skills: ~/.copilot/skills/, ~/.agents/skills/.
• Custom Agents: .github/agents/*.agent.md and ~/.copilot/agents/.
• Plugins resolve a manifest from .plugin/plugin.json, plugin.json, .github/plugin/plugin.json, or .claude-plugin/plugin.json, in that order. Marketplaces resolve marketplace.json from the equivalent roots.

Prefer marketplace installs. Direct repository, URL, and local-path installs are deprecated in favor of plugin@marketplace installs.

External Context

Use MCP when Copilot needs context or actions outside the repository. MCP servers are configured in ~/.copilot/mcp-config.json (user) or .mcp.json and .github/mcp.json (project). MCP resolution is last-wins, so a plugin server overrides a user server of the same name. Start with one or two MCP tools that remove a real repeated cost.

Automation

Copilot hooks load from .github/hooks/*.json, ~/.copilot/hooks/, inline hooks in settings, and plugin hook files. Event names accept a camelCase form (sessionStart, preToolUse, agentStop) and a PascalCase form (SessionStart, PreToolUse, Stop) that matches the IDE format. Command hooks accept bash and powershell variants, so keep automation cross-platform.

Automate only stable workflows, and prefer a prompt reminder when a blocking hook would be disproportionate.

Evidence Boundaries

• Configured Skills, Agents, hooks, MCP servers, and installed Plugins prove a mechanism exists. They never prove it ran.
• Copilot CLI transcripts live at