Merge pull request #9616 from microsoft/ntrogh/fix-customization-location

Remove misleading language about customization locations

Author: ntrogh

docs/copilot/customization/agent-skills.md

@@ -66,11 +66,10 @@ Skills are stored in directories with a `SKILL.md` file that defines the skill's
 | Project skills, stored in your repository | `.github/skills/`, `.claude/skills/`, `.agents/skills/` |
 | Personal skills, stored in your user profile | `~/.copilot/skills/`, `~/.claude/skills/`, `~/.agents/skills/` |
 
-> [!TIP]
-> In a monorepo, enable `setting(chat.useCustomizationsInParentRepositories)` to discover skills from the parent repository root. Learn more about [parent repository discovery](/docs/copilot/customization/overview.md#parent-repository-discovery).
+You can configure additional file locations for project skills with the `setting(chat.skillsLocations)` setting. This is useful if you want to organize skills in a different folder structure or have multiple skill directories.
 
 > [!TIP]
-> You can configure additional locations where VS Code searches for skills by using the `setting(chat.agentSkillsLocations)` setting. This is useful for sharing skills across projects or keeping them in a central location.
+> In a monorepo, enable `setting(chat.useCustomizationsInParentRepositories)` to discover skills from the parent repository root. Learn more about [parent repository discovery](/docs/copilot/customization/overview.md#parent-repository-discovery).
 
 To create a skill:
 

docs/copilot/customization/custom-agents.md

@@ -76,18 +76,18 @@ When users see the handoff button and select it, they switch to the target agent
 
 ## Custom agent file locations
 
-You can define custom agents for a specific workspace or at the user level, where they are available across all your workspaces.
-
-> [!TIP]
-> In a monorepo, enable `setting(chat.useCustomizationsInParentRepositories)` to discover custom agents from the parent repository root. Learn more about [parent repository discovery](/docs/copilot/customization/overview.md#parent-repository-discovery).
+You can define custom agents for a specific workspace or at the user level, where they are available across all your workspaces. The following table lists the default file locations for custom agents based on their scope. You can configure additional file locations for workspace custom agent files with the `setting(chat.agentFilesLocations)` setting.
 
 | Scope | Default file location |
 |-------|-----------------------|
 | Workspace | `.github/agents` folder |
 | Workspace (Claude format) | `.claude/agents` folder |
-| User profile | `~/.copilot/agents`, `agents` folder of the current [VS Code profile](/docs/configure/profiles.md) |
+| User profile | `~/.copilot/agents` or your user data (specific to your VS Code profile) |
 
-You can configure additional file locations for workspace custom agent files with the `setting(chat.agentFilesLocations)` setting.
+To create a custom agent in user data, use the Chat Customizations editor or use the **Chat: New Custom Agent** command.
+
+> [!TIP]
+> In a monorepo, enable `setting(chat.useCustomizationsInParentRepositories)` to discover custom agents from the parent repository root. Learn more about [parent repository discovery](/docs/copilot/customization/overview.md#parent-repository-discovery).
 
 ## Custom agent file structure
 

docs/copilot/customization/custom-instructions.md

@@ -130,18 +130,15 @@ Use `.instructions.md` files for:
 
 ### Instructions file locations
 
-You can define instructions for a specific workspace or at the user level, where they are applied across all your workspaces.
-
-> [!TIP]
-> In a monorepo, enable `setting(chat.useCustomizationsInParentRepositories)` to discover instructions from the parent repository root. Learn more about [parent repository discovery](/docs/copilot/customization/overview.md#parent-repository-discovery).
+You can define instructions for a specific workspace or at the user level, where they are applied across all your workspaces. The following table lists the default file locations for instructions files based on their scope. You can configure additional file locations for workspace instructions files with the `setting(chat.instructionsFilesLocations)` setting.
 
 | Scope | Default file location |
 |-------|-----------------------|
 | Workspace | `.github/instructions` folder |
 | Workspace (Claude format) | `.claude/rules` folder |
-| User profile | `~/.copilot/instructions`, `~/.claude/rules`, `instructions` folder of the current [VS Code profile](/docs/configure/profiles.md) |
+| User profile | `~/.copilot/instructions`, `~/.claude/rules`, or your user data (specific to your VS Code profile) |
 
-VS Code searches these folders recursively, so you can organize instructions files in subdirectories. For example, you can group instructions by team, language, or module:
+VS Code searches these folders recursively, to enable you to organize instructions files in subdirectories. For example, you can group instructions by team, language, or module:
 
 ```text
 .github/instructions/
@@ -154,11 +151,7 @@ VS Code searches these folders recursively, so you can organize instructions fil
     unit-tests.instructions.md
 ```
 
-You can configure additional file locations for workspace instructions files with the `setting(chat.instructionsFilesLocations)` setting. This is useful if you want to keep instructions files in a different folder or have multiple folders for better organization. Custom locations are also searched recursively.
-
-For compatibility with Claude Code and other Claude-based tools, VS Code also detects instructions files in the `.claude/rules` workspace folder and the `~/.claude/rules` user folder.
-
-The following code snippet shows how to configure instructions file locations, where only workspace-level instructions are enabled and user-level instructions are disabled:
+The following example shows how to configure the instructions file locations to only allow workspace-level instructions:
 
 ```json
 "chat.instructionsFilesLocations": {
@@ -169,6 +162,9 @@ The following code snippet shows how to configure instructions file locations, w
 }
 ```
 
+> [!TIP]
+> In a monorepo, enable `setting(chat.useCustomizationsInParentRepositories)` to discover instructions from the parent repository root. Learn more about [parent repository discovery](/docs/copilot/customization/overview.md#parent-repository-discovery).
+
 ### Instructions file format
 
 Instructions files are Markdown files with the `.instructions.md` extension. The optional YAML frontmatter header controls when the instructions are applied:

docs/copilot/customization/prompt-files.md

@@ -30,17 +30,17 @@ Use prompt files to:
 
 ## Prompt file locations
 
-You can define prompt files for a specific workspace or at the user level, where they are available across all your workspaces.
-
-> [!TIP]
-> In a monorepo, enable `setting(chat.useCustomizationsInParentRepositories)` to discover prompt files from the parent repository root. Learn more about [parent repository discovery](/docs/copilot/customization/overview.md#parent-repository-discovery).
+You can define prompt files for a specific workspace or at the user level, where they are available across all your workspaces. The following table lists the default file locations for prompt files based on their scope. You can configure additional file locations for workspace prompt files with the `setting(chat.promptFilesLocations)` setting.
 
 | Scope | Default file location |
 |-------|-----------------------|
 | Workspace | `.github/prompts` folder |
-| User profile | `prompts` folder of the current [VS Code profile](/docs/configure/profiles.md) |
+| User profile | Your user data (specific to your VS Code profile) |
 
-You can configure additional file locations for workspace prompt files with the `setting(chat.promptFilesLocations)` setting.
+To create a prompt file in user data, use the Chat Customizations editor or use the **Chat: New Prompt File** command.
+
+> [!TIP]
+> In a monorepo, enable `setting(chat.useCustomizationsInParentRepositories)` to discover prompt files from the parent repository root. Learn more about [parent repository discovery](/docs/copilot/customization/overview.md#parent-repository-discovery).
 
 ## Prompt file format