Instructions and Agent Customization
Purpose and Scope
Agent customization is the VS Code mechanism for making Copilot behave as if it already understands a team, repository, or workflow before the user repeats that context in chat. The repository reference assets describe a related set of Markdown and JSON primitives rather than one large configuration file. Always-on instructions set the baseline, file instructions narrow guidance to relevant tasks or files, prompts package repeatable requests, skills package reusable workflows, agents define specialized roles, and hooks provide deterministic automation. Use this page to choose the smallest primitive that fits the job. Sources: extensions/copilot/assets/prompts/skills/agent-customization/references/agent-instructions.md, extensions/copilot/assets/prompts/skills/agent-customization/references/instructions.md
The most important design choice is activation. Some customization is included in every chat request, some is discovered from descriptions, some attaches only when files match a pattern, and some runs only when a user selects a command or when an agent reaches a lifecycle event. Treat that activation model as part of the feature contract. If guidance applies to every request, keep it in always-on instructions. If the rule is specific to migrations, tests, documentation, a framework, or a folder, use a targeted instruction file, prompt, skill, agent, or hook instead. Sources: extensions/copilot/assets/prompts/skills/agent-customization/references/prompts.md, extensions/copilot/assets/prompts/skills/agent-customization/references/skills.md, extensions/copilot/assets/prompts/skills/agent-customization/references/hooks.md
Relevant Source Files
extensions/copilot/assets/prompts/skills/agent-customization/references/agent-instructions.md— Defines always-on instruction files, the recommendation to choose one project-wide format, a project-guidelines template, and anti-patterns for global guidance.extensions/copilot/assets/prompts/skills/agent-customization/references/instructions.md— Defines workspace and profile instruction locations, frontmatter fields, discovery modes, file matching behavior, templates, and authoring principles.extensions/copilot/assets/prompts/skills/agent-customization/references/agents.md— Defines custom agent locations, frontmatter fields, model fallback, tool aliases, subagent controls, handoffs, inline hooks, and role-design guidance.extensions/copilot/assets/prompts/skills/agent-customization/references/hooks.md— Defines hook locations, lifecycle events, command configuration, stdin and stdout contracts, permission decisions, exit codes, and hook anti-patterns.extensions/copilot/assets/prompts/skills/agent-customization/references/prompts.md— Defines prompt file locations, frontmatter fields, invocation paths, context references, model fallback, tool priority, and prompt anti-patterns.extensions/copilot/assets/prompts/skills/agent-customization/references/skills.md— Defines agent skill folder structure,SKILL.mdmetadata, supported locations, progressive loading, slash command behavior, and skill anti-patterns.
Core Primitives
Always-on instructions are for guidance that is genuinely true across the workspace. The reference offers two project-wide choices and explicitly says to use only one: a Copilot instructions file under the GitHub folder, or agent instructions files at the root or in subfolders when an open-standard hierarchy is useful. The suggested content is practical rather than exhaustive: code style, architecture, build and test commands, and conventions that differ from common practice. Good always-on guidance links to detailed documentation instead of copying it, because copied policy drifts and consumes chat context. Sources: extensions/copilot/assets/prompts/skills/agent-customization/references/agent-instructions.md
File-specific instructions are the next layer down. Workspace instructions live in the repository, while profile instructions are personal to a user. Their required description is not cosmetic; it is the signal used for on-demand discovery, so it should include trigger words such as when writing migrations, when changing API routes, or when updating documentation. An optional file-matching field changes the behavior from task discovery to automatic attachment for matching files. The reference also warns that matching applies when creating or modifying files, not during purely read-only exploration. Sources: extensions/copilot/assets/prompts/skills/agent-customization/references/instructions.md
Prompts and skills both help avoid repeating task instructions, but they are not interchangeable. A prompt is a single focused chat task with optional metadata for discoverability, argument hints, model choice, agent selection, and tools. A skill is a folder with a required skill document plus optional scripts, references, and assets. This distinction matters when a workflow grows: a prompt should remain a concise request template, while a skill can carry procedures, examples, scripts, and templates that load progressively only when relevant to the task. Sources: extensions/copilot/assets/prompts/skills/agent-customization/references/prompts.md, extensions/copilot/assets/prompts/skills/agent-customization/references/skills.md
Custom agents should be introduced when the customization is a role with boundaries, not merely another page of guidance. The agent reference supports fields for description, tool lists, model fallback, argument hints, subagent restrictions, invocation visibility, handoffs, and inline lifecycle hooks. Tool selection is central to the model: a research agent might have read and search access, an editing agent might add file edits, and a conversational agent can have no tools. Agents can also refer to MCP server tools, so external integrations should be declared deliberately rather than hidden in prose. Sources: extensions/copilot/assets/prompts/skills/agent-customization/references/agents.md
Hooks are different because they execute commands during the agent lifecycle instead of merely guiding the model. The hook reference defines team-shared, local workspace, workspace settings, and user settings locations, then lists events such as session start, prompt submission, pre-tool use, post-tool use, compaction, subagent start and stop, and session stop. Hook commands receive JSON input and may return JSON output. For pre-tool use, a hook can allow, ask, or deny the tool call, which makes hooks appropriate for enforceable policy and validation. Sources: extensions/copilot/assets/prompts/skills/agent-customization/references/hooks.md
System-to-Code Mapping
| Need | Use | Primary workspace location | Activation model |
|---|---|---|---|
| Project-wide coding standards | Always-on instructions | .github/copilot-instructions.md or AGENTS.md | Included in every chat request |
| Task-specific or file-specific guidance | File instructions | .github/instructions/*.instructions.md | Description discovery, applyTo, or manual attachment |
| Repeatable single task | Prompt file | .github/prompts/*.prompt.md | Slash command, command palette, or editor play button |
| Workflow with scripts and resources | Agent Skill | .github/skills/<name>/SKILL.md | Slash command and automatic relevance-based loading |
| Role with tool boundaries | Custom agent | .github/agents/*.agent.md | Agent picker or subagent delegation |
| Runtime enforcement | Hook | .github/hooks/*.json | Lifecycle event command execution |
The mapping is also a maintenance model. Keep permanent repository standards near the repository, keep personal preferences in profile locations, and avoid mixing team policy with private automation. A workspace instruction, skill, or agent should be reviewable by teammates because it can influence future Copilot behavior for the project. A profile prompt or hook is better for personal habits that should not affect everyone. This separation is especially important for hooks because commands can block workflow, request confirmation, or inject runtime context into the session. Sources: extensions/copilot/assets/prompts/skills/agent-customization/references/hooks.md, extensions/copilot/assets/prompts/skills/agent-customization/references/instructions.md
API and Configuration Reference
| Primitive | Important names or fields | Source-level behavior |
|---|---|---|
| Always-on instructions | .github/copilot-instructions.md, AGENTS.md | Choose one format; include only guidance useful to every task. |
| File instructions | description, name, applyTo | Description drives discovery; file matching supports glob strings and arrays. |
| Prompt files | description, name, argument-hint, agent, model, tools | Prompt tools take priority over tools from a referenced custom agent, then defaults apply. |
| Custom agents | description, tools, model, agents, user-invocable, disable-model-invocation, handoffs, hooks | Use minimal tools, clear role boundaries, and keyword-rich descriptions for delegation. |
| Agent skills | name, description, argument-hint, user-invocable, disable-model-invocation | Skill names must match folders and use lowercase alphanumeric characters plus hyphens. |
| Hooks | hooks, type, command, windows, linux, osx, cwd, env, timeout | Commands receive JSON on standard input and can return blocking or permission output. |
Authoring Flow and Edge Cases
Start with the smallest customization that solves the user problem. Add one always-on instruction file only after identifying rules that apply to every request, such as required test commands, architecture boundaries, or conventions that differ from common practice. For narrower concerns, create separate instruction files with one concern per file and descriptions that use the words a developer is likely to type. When the user should intentionally start a repeatable operation, create a prompt. When the operation needs scripts, templates, reference documents, or bundled examples, promote it to a skill. Sources: extensions/copilot/assets/prompts/skills/agent-customization/references/agent-instructions.md, extensions/copilot/assets/prompts/skills/agent-customization/references/instructions.md, extensions/copilot/assets/prompts/skills/agent-customization/references/prompts.md, extensions/copilot/assets/prompts/skills/agent-customization/references/skills.md
Several edge cases recur across the references. Do not create both always-on project formats in the same workspace. Avoid broad file patterns that make specialized guidance effectively global. Do not turn a prompt into a deployment, testing, documentation, and refactoring workflow; split the concern or use a skill. Do not create a custom agent with every tool enabled just because it is convenient, because broad tools weaken the role boundary. Do not use hooks where guidance is sufficient, and do not let agents freely edit the scripts that enforce permissions. Sources: extensions/copilot/assets/prompts/skills/agent-customization/references/agents.md, extensions/copilot/assets/prompts/skills/agent-customization/references/hooks.md
A healthy customization set is layered and testable. Always-on instructions define shared expectations, file-specific instructions add targeted rules, prompts provide deliberate shortcuts, skills provide portable workflows, agents provide role isolation, and hooks provide deterministic enforcement. After creating or editing these files, test them with representative chat tasks rather than only checking syntax. Confirm that descriptions cause the right files, skills, or agents to be discovered; that tool lists permit intended work without unnecessary access; and that hooks fail safely with clear messages when they block progress. Sources: extensions/copilot/assets/prompts/skills/agent-customization/references/instructions.md, extensions/copilot/assets/prompts/skills/agent-customization/references/agents.md, extensions/copilot/assets/prompts/skills/agent-customization/references/hooks.md
Next Steps
Use this page as the decision point before adding more customization to a repository. If the task is about reusable workflows with bundled resources, continue to custom agents, skills, and prompts. If the task requires deterministic lifecycle enforcement, continue to hooks and plugins. If the agent needs external APIs, databases, or remote tools, continue to MCP servers and tool approval documentation. For operational failures, use AI troubleshooting to inspect logs, disabled states, model configuration, and automation coverage before changing the customization files again.