You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/copilot/concepts/customization.md
+32-22Lines changed: 32 additions & 22 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -24,61 +24,71 @@ This article explains the different customization options and when to use each o
24
24
25
25
## Customization options at a glance
26
26
27
-
| Goal | Use | When it activates |
28
-
|------|-----|-------------------|
29
-
| Apply coding standards everywhere |[Always-on instructions](#custom-instructions)| Automatically included in every request |
30
-
| Different rules for different file types |[File-based instructions](#custom-instructions)| When files match a pattern or description |
31
-
| Reusable task I run repeatedly |[Prompt files](#prompt-files)| When you invoke a slash command |
32
-
| Package multi-step workflow with scripts |[Agent skills](#agent-skills)| When the task matches the skill description |
33
-
| Specialized AI persona with tool restrictions |[Custom agents](#custom-agents)| When you select it or another agent delegates to it |
34
-
| Connect to external APIs or databases |[MCP](#mcp)| When the task matches a tool description |
35
-
| Automate tasks at agent lifecycle points |[Hooks](#hooks)| When the agent reaches a matching lifecycle event |
36
-
| Install pre-packaged customizations |[Agent plugins](#agent-plugins)| When you install a plugin |
27
+
| Goal | Use | Example | When it activates |
28
+
|------|-----|---------|-------------------|
29
+
| Apply coding standards everywhere |[Always-on instructions](#custom-instructions)| Enforce ESLint rules, require JSDoc comments | Automatically included in every request |
30
+
| Different rules for different file types |[File-based instructions](#custom-instructions)| React patterns for `.tsx` files | When files match a pattern or description |
31
+
| Reusable task I run repeatedly |[Prompt files](#prompt-files)| Scaffold a React component | When you invoke a slash command |
32
+
| Package multi-step workflow with scripts |[Agent skills](#agent-skills)| Test, lint, and deploy pipeline | When the task matches the skill description |
33
+
| Specialized AI persona with tool restrictions |[Custom agents](#custom-agents)| Security reviewer, database admin | When you select it or another agent delegates to it |
34
+
| Connect to external APIs or databases |[MCP](#mcp)| Query a PostgreSQL database | When the task matches a tool description |
35
+
| Automate tasks at agent lifecycle points |[Hooks](#hooks)| Run formatter after every file edit | When the agent reaches a matching lifecycle event |
36
+
| Install pre-packaged customizations |[Agent plugins](#agent-plugins)| Install a community testing plugin | When you install a plugin |
37
+
38
+
Start with custom instructions for project-wide standards. Add prompt files when you have repeatable tasks. Use MCP when you need external data. Create custom agents for specialized personas. You can combine multiple customization types as your needs grow.
37
39
38
40
## Custom instructions
39
41
40
-
Custom instructions define coding standards and project context in Markdown files that are automatically included in chat requests. There are two types:
42
+
Custom instructions are Markdown files that define coding standards and project context. The AI includes them automatically in chat requests, so you don't need to repeat rules in every prompt. Instructions are the simplest customization to set up and the best place to start.
41
43
42
-
***Always-on instructions**: project-wide rules defined in `.github/copilot-instructions.md` that apply to every request.
43
-
***File-based instructions**: guidelines in `.instructions.md` files that apply based on file path patterns or task descriptions.
44
+
There are two types:
45
+
46
+
***Always-on instructions**: project-wide rules defined in `.github/copilot-instructions.md` that apply to every request. Use these for conventions the whole team follows, like code style, naming patterns, or preferred libraries.
47
+
***File-based instructions**: guidelines in `.instructions.md` files that apply based on file path patterns or task descriptions. Use these when different parts of your codebase need different rules, such as React patterns for `.tsx` files or API conventions for your backend.
44
48
45
49
Learn more about [creating custom instructions](/docs/copilot/customization/custom-instructions.md).
46
50
47
51
## Prompt files
48
52
49
-
Prompt files encode common tasks as Markdown files you invoke as slash commands in chat. Use them for repeatable workflows like scaffolding components, running tests, or preparing pull requests. Each prompt file defines a task with optional tool references and context attachments.
53
+
Prompt files are reusable Markdown files that encode a specific task and appear as slash commands in chat. When you find yourself typing the same kind of prompt repeatedly, a prompt file turns it into a one-step command. Each prompt file can reference specific files, tools, and context to give the AI everything it needs for that task.
54
+
55
+
Prompt files are useful for tasks like scaffolding a new component, generating test cases for a module, or preparing a pull request description.
50
56
51
57
Learn more about [creating prompt files](/docs/copilot/customization/prompt-files.md).
52
58
53
59
## Agent skills
54
60
55
-
Agent skills package specialized capabilities as folders of instructions, scripts, and resources that load on demand. Built on an [open standard](https://agentskills.io), skills work across VS Code, GitHub Copilot CLI, and GitHub Copilot coding agent. Skills let you teach the agent domain-specific tasks, like generating API documentation or running security audits.
61
+
Agent skills package multi-step capabilities as folders containing instructions, scripts, and resources. Unlike prompt files, which provide a single prompt, skills give the AI a complete toolkit for a domain-specific task such as generating API documentation, running security audits, or performing database migrations.
62
+
63
+
Skills load on demand when the task matches their description. They are built on an [open standard](https://agentskills.io), so the same skill works across different agent types.
56
64
57
65
Learn more about [creating agent skills](/docs/copilot/customization/agent-skills.md).
58
66
59
67
## Custom agents
60
68
61
-
Custom agents let the AI adopt different personas for specific roles, such as security reviewer, database admin, or planner. Each agent defines its own behavior, available tools, and language model preferences in a `.agent.md` file. Custom agents can also hand off to other agents for multi-step workflows.
69
+
Custom agents give the AI a specific persona and constrained set of tools for a particular role. For example, a security reviewer agent only has access to code analysis tools and follows security-focused instructions, while a database admin agent connects to your database through MCP and follows your schema conventions.
70
+
71
+
Each agent is defined in a `.agent.md` file that specifies its behavior, available tools, and language model preferences. Agents can also delegate to other agents, which enables multi-step workflows where different specialists handle different parts of a task.
62
72
63
73
Learn more about [creating custom agents](/docs/copilot/customization/custom-agents.md).
64
74
65
75
## MCP
66
76
67
-
[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open standard for connecting AI models to external tools and data sources. MCP servers provide [tools](/docs/copilot/concepts/tools.md) for tasks like querying databases, calling APIs, or interacting with external services. MCP servers can run locally or remotely, and can also provide resources, prompts, and interactive apps.
77
+
[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open standard for connecting the AI to external tools and data sources. Without MCP, the AI can only work with code and the terminal. MCP servers extend its reach by providing [tools](/docs/copilot/concepts/tools.md) that query databases, call APIs, interact with cloud services, or access any other external system.
78
+
79
+
MCP servers run locally or remotely and can also provide resources, prompts, and interactive apps.
68
80
69
81
Learn more about [adding and managing MCP servers](/docs/copilot/customization/mcp-servers.md).
70
82
71
83
## Hooks
72
84
73
-
Hooks run custom shell commands at key lifecycle points during agent sessions. Unlike instructions or custom prompts that guide agent behavior, hooks execute your code at specific lifecycle points with guaranteed outcomes. Use hooks to enforce security policies, run formatters after edits, create audit trails, or inject context.
74
-
75
-
VS Code supports eight hook events: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `SubagentStart`, `SubagentStop`, and `Stop`.
85
+
Hooks run custom shell commands at specific points during an agent session. While instructions and prompts guide what the AI does, hooks guarantee that your code runs at defined lifecycle points. This makes hooks the right choice when you need deterministic outcomes, such as running a formatter after every file edit, blocking commits that fail a lint check, or logging every tool invocation for an audit trail.
76
86
77
87
Learn more about [configuring hooks](/docs/copilot/customization/hooks.md).
78
88
79
89
## Agent plugins
80
90
81
-
Agent plugins are pre-packaged bundles of customizations you discover and install from plugin marketplaces. A single plugin can provide slash commands, skills, custom agents, hooks, and MCP servers.
91
+
Agent plugins are pre-packaged bundles of customizations you discover and install from plugin marketplaces. Instead of building everything yourself, you can install a plugin that provides a ready-made combination of slash commands, skills, custom agents, hooks, and MCP servers. Plugins are useful for adopting community best practices or sharing internal tooling across teams.
82
92
83
93
> [!NOTE]
84
94
> Agent plugins are currently in preview.
@@ -87,6 +97,6 @@ Learn more about [agent plugins](/docs/copilot/customization/agent-plugins.md).
87
97
88
98
## Related resources
89
99
90
-
*[Customize AI in VS Code](/docs/copilot/customization/overview.md)
100
+
*[Get started with customization](/docs/copilot/customization/overview.md)
MetaDescription: Learn how to customize chat in VS Code with custom instructions, reusable prompt files, and custom agentsto align AI responses with your coding practices and project requirements.
4
+
MetaDescription: Get started customizing AI in VS Code with custom instructions, prompt files, custom agents, MCP servers, and more to align AI responses with your coding practices.
AI models have broad general knowledge but don't know your codebase or team practices. Customization is how you share that context, so responses match your coding standards, project structure, and workflows.
21
+
Visual Studio Code gives you several ways to teach the AI about your codebase, coding standards, and workflows. This article introduces the customization options and helps you get started.
22
22
23
-
For background on the different customization types and when to use each one, see [Customization concepts](/docs/copilot/concepts/customization.md).
Learn about the different customization types and when to use each one.
24
25
25
-
This article covers the customization options in VS Code and how to set up your project for AI. To access customizations, select the **Configure Chat (gear icon)** in the Chat view.
| Apply coding standards everywhere |[Always-on instructions](#custom-instructions)| Enforce ESLint rules, require JSDoc comments | Automatically included in every request |
32
-
| Different rules for different file types |[File-based instructions](#custom-instructions)| React patterns for `.tsx` files | When files match a pattern or description |
33
-
| Reusable task I run repeatedly |[Prompt files](#prompt-files)| Scaffold a React component | When you invoke a slash command |
34
-
| Package multi-step workflow with scripts |[Agent skills](#agent-skills)| Test, lint, and deploy pipeline | When the task matches the skill description |
35
-
| Specialized AI persona with tool restrictions |[Custom agents](#custom-agents)| Security reviewer, database admin | When you select it or another agent delegates to it |
36
-
| Connect to external APIs or databases |[MCP](#mcp-and-tools)| Query a PostgreSQL database | When the task matches a tool description |
37
-
| Automate tasks at agent lifecycle points |[Hooks](#hooks)| Run formatter after every file edit | When the agent reaches a matching lifecycle event |
38
-
| Install pre-packaged customizations from marketplaces |[Agent plugins](#agent-plugins) (Preview) | Install a community testing plugin | When you install a plugin |
39
-
40
-
## Customization options
41
-
42
-
### Custom instructions
43
-
44
-
[Custom instructions](/docs/copilot/customization/custom-instructions.md) define coding standards and project context in Markdown files that are automatically included in chat requests. Use always-on instructions for project-wide rules, or file-based instructions to apply different guidelines based on file path patterns.
45
-
46
-
### Agent skills
28
+
</div>
47
29
48
-
[Agent skills](/docs/copilot/customization/agent-skills.md) package specialized capabilities as folders of instructions, scripts, and resources that load on demand. Built on an [open standard](https://agentskills.io), skills work across VS Code, GitHub Copilot CLI, and GitHub Copilot coding agent.
Follow a hands-on walkthrough to customize AI for your project.
49
32
50
-
### Prompt files
33
+
*[Customize AI for your project](/docs/copilot/guides/customize-copilot-guide.md)
51
34
52
-
[Prompt files](/docs/copilot/customization/prompt-files.md) encode common tasks as Markdown files you invoke as slash commands in chat. Use them for repeatable workflows like scaffolding components, running tests, or preparing pull requests.
35
+
</div>
53
36
54
-
### Custom agents
37
+
To access customizations, select the **Configure Chat (gear icon)** in the Chat view.
55
38
56
-
[Custom agents](/docs/copilot/customization/custom-agents.md) let the AI adopt different personas for specific roles, such as security reviewer, database admin, or planner. Each agent defines its own behavior, available tools, and language model preferences in a Markdown file.
39
+
## Customization scenarios
57
40
58
-
### MCP and tools
41
+
The following sections describe common customization scenarios and which options to use for each one.
59
42
60
-
[MCP and tools](/docs/copilot/customization/mcp-servers.md) extend the agent beyond code and the terminal by connecting to external services through the [Model Context Protocol](https://modelcontextprotocol.io/). Use MCP servers to interact with databases, APIs, and other development tools.
43
+
### Define coding standards
61
44
62
-
### Hooks
45
+
Use [custom instructions](/docs/copilot/customization/custom-instructions.md) to share project-wide rules and conventions with the AI. Always-on instructions apply to every request, while file-based instructions target specific file types or folders. For example, enforce ESLint rules across all files and apply React patterns only in `.tsx` files.
63
46
64
-
[Hooks](/docs/copilot/customization/hooks.md) run custom shell commands at key lifecycle points during agent sessions. Use them to enforce security policies, run formatters after edits, or create audit trails.
47
+
### Automate tasks and workflows
65
48
66
-
### Agent plugins
49
+
Create [prompt files](/docs/copilot/customization/prompt-files.md) for repeatable tasks you run often, like scaffolding a component or preparing a pull request.
67
50
68
-
> [!NOTE]
69
-
> Agent Plugins are currently in preview.
51
+
For more complex multi-step workflows that involve scripts and external tools, package them as [agent skills](/docs/copilot/customization/agent-skills.md).
70
52
71
-
[Agent plugins](/docs/copilot/customization/agent-plugins.md) are pre-packaged bundles of customizations you discover and install from plugin marketplaces. A single plugin can provide slash commands, skills, custom agents, hooks, and MCP servers.
53
+
### Specialize the AI
72
54
73
-
### Language models
55
+
Create [custom agents](/docs/copilot/customization/custom-agents.md) that adopt specific personas, such as security reviewer, database admin, or planner. Each agent defines its own behavior, available tools, and language model preferences. Choose different [language models](/docs/copilot/customization/language-models.md) for different tasks, or bring your own API key to access additional models.
74
56
75
-
[Language models](/docs/copilot/customization/language-models.md) let you switch between AI models optimized for different tasks. Use a fast model for quick suggestions, or a more capable model for complex architectural decisions. Bring your own API key to access additional or locally hosted models.
57
+
### Discover and install plugins
76
58
77
-
## Set up your project for AI
59
+
Install [agent plugins](/docs/copilot/customization/agent-plugins.md) (preview) to add pre-packaged bundles of customizations from plugin marketplaces. A single plugin can provide slash commands, skills, custom agents, hooks, and MCP servers.
Set up your project for AI with `/init` to generate custom instructions tailored to your project.
61
+
### Connect external tools and data
81
62
82
-
*[Open in VS Code](vscode://GitHub.Copilot-Chat/chat?prompt=%2Finit)
63
+
Add [MCP servers](/docs/copilot/customization/mcp-servers.md) to give the AI access to databases, APIs, and other services through the [Model Context Protocol](https://modelcontextprotocol.io/). Use [hooks](/docs/copilot/customization/hooks.md) to run shell commands at key lifecycle points, such as running a formatter after every file edit or enforcing security policies.
83
64
84
-
</div>
65
+
## Get started
85
66
86
67
Implement AI customizations incrementally. Start with the basics and add more as needed. For a hands-on walkthrough, see the [Customize AI for your project](/docs/copilot/guides/customize-copilot-guide.md) guide.
87
68
@@ -112,11 +93,5 @@ If your customizations aren't being applied or cause unexpected behavior, select
0 commit comments