Copilot Customization Advisor

Copilot Customization Advisor

Recommend the right customization type for a user's intent by applying the decision framework below.

Decision Flow

Walk through these questions in order. Stop at the first "yes."

1. Is this a rule that should ALWAYS apply? -> Instructions (inspect scope first: AGENTS.md default, .github/instructions/*.instructions.md for applyTo globs; see Shared Instruction Precedence)
2. Is this a repeatable recipe the user will invoke by name? -> Prompt file (.prompt.md)
3. Is this a capability that any agent should be able to use? -> Skill (SKILL.md)
4. Does it need its own identity, persona, or tool set? -> Agent (.agent.md)
5. Does an agent need to delegate focused work with context isolation? -> Sub-agent (same .agent.md, spawned by another agent)
6. Must something deterministically happen at a lifecycle point (no AI discretion)? -> Hook (.json in .github/hooks/)

Quick Reference

Rules of Thumb

Use these to validate your recommendation:

• Instructions: "If violating it would cause a code review rejection, it belongs in instructions."
• Prompt files: "If you'd save it as a snippet or template you invoke by name, it's a prompt file."
• Skills: "If it teaches the agent a new ability with project-specific knowledge, it's a skill."
• Agents: "If you'd assign it to a specific person on your team, it's an agent."
• Sub-agents: "If you'd CC someone on the email vs. assign them a separate ticket, that's the difference between sharing context and spawning a sub-agent."
• Hooks: "Instructions tell the agent what to think. Hooks control what actually happens."
• Handoffs vs. sub-agents: "Start with handoffs (user in the loop) to learn the workflow. Graduate to sub-agents once the flow is proven."

Distinguishing Close Calls

When two types seem equally valid, use these tiebreakers:

Skill vs. Agent: Does it need its own identity? If the default Copilot agent could do the task once it has the knowledge, it's a skill. If the task requires a distinct persona, constrained tool set, or model preference, it's an agent.

Instruction vs. Skill: Is it a constraint or a capability? "Always use Zod for validation" is an instruction. "Here's how to create a Zod schema including the template, the test, and the registration" is a skill.

Prompt file vs. Skill: Does the user invoke it explicitly by name, or should the agent discover it by task match? Explicit invocation with / is a prompt file. Auto-discovery is a skill.

Instruction vs. Hook: Is compliance optional or mandatory? Instructions guide the AI (non-deterministic). Hooks execute shell commands (deterministic, guaranteed). If the agent might forget or skip it, use a hook.

Shared Instruction Precedence

When recommending or creating shared repository instructions, inspect the repository hierarchy for existing instruction files before choosing a destination:

1. Inspect Existing Files: Check the applicable directory hierarchy (starting from the target directory up to the repository root) for existing cross-agent instruction files (AGENTS.md or CLAUDE.md) and .github/copilot-instructions.md.
2. Single Format Exists:
   • If only AGENTS.md (or CLAUDE.md) exists in scope, merge new guidance into that existing cross-agent instruction file.
   • If only .github/copilot-instructions.md exists in scope, merge new guidance in place into .github/copilot-instructions.md rather than creating AGENTS.md.
3. Neither Exists: Default to creating AGENTS.md at the repository root.
4. Both Exist (Mixed Format):
   • Treat AGENTS.md as the canonical consolidation destination.
   • Recommend consolidating overlapping shared cross-agent guidance into AGENTS.md.
   • Keep intentionally product-specific rules or features (e.g., #file: references or VS Code Copilot-specific syntax) in .github/copilot-instructions.md.
5. Conflict Resolution:
   • Surface conflicting existing guidance to the user for explicit resolution rather than silently choosing or overwriting rules.
   • Preserve headings, comments, and unrelated instructions while merging.
6. Path-Specific Scoping:
   • Continue recommending .github/instructions/*.instructions.md when path-specific applyTo glob matching is required (these are scoped instruction files, not competing shared-file formats).

Responding to the User

When advising, follow this pattern:

1. Restate the user's intent in one sentence
2. Walk the decision flow, showing which questions apply
3. Name the recommended type and explain why
4. If relevant, note what the file structure would look like
5. If the intent spans multiple types, recommend layering (e.g., an instruction for the rule plus a skill for the how-to)

For detailed reference on each type including anatomy, frontmatter fields, directory structure, and real-world examples, read copilot-customization-reference.md in this skill directory.

User-Scoped Copilot Home (CLI)

For user-scoped customizations, use the Copilot home directory:

• Windows example: C:\Users\<username>\.copilot (or %USERPROFILE%\.copilot)
• Generic home form: ~/.copilot
• Local always-on instructions: ~/.copilot/copilot-instructions.md
• User path-specific instructions: for each directory listed in COPILOT_CUSTOM_INSTRUCTIONS_DIRS, place files at <that-dir>/.github/instructions/*.instructions.md
• User skills: ~/.copilot/skills/{skill-name}/SKILL.md