[docs] docs: unbloat Copilot custom agents reference

docs/src/content/docs/reference/copilot-custom-agents.md

@@ -5,9 +5,9 @@ sidebar:
   order: 650
 ---
 
-"Custom agents" is a term used in GitHub Copilot for specialized prompts for behaviors for specific tasks. They are markdown files stored in the `.github/agents/` directory and imported via the `imports` field. Copilot supports agent files natively, while other engines (Claude, Codex) inject the markdown body as a prompt.
+GitHub Copilot custom agents are Markdown prompt files stored in `.github/agents/` and imported with `imports`. Copilot supports these files natively; other engines such as Claude and Codex receive the Markdown body as prompt text.
 
-A typical custom agent file looks like this:
+A typical agent file looks like this:
 
 ```markdown title=".github/agents/my-agent.md"
 ---
@@ -25,7 +25,7 @@ You are a specialized code review agent. Focus on:
 
 ## Using Copilot Agent Files from Agentic Workflows
 
-Import Copilot agent files in your workflow using the `imports` field. Agent files can be imported from local `.github/agents/` directories or from external repositories.
+Use `imports` to load an agent file from your repository or from another repository.
 
 ### Local Agent File Import
 
@@ -44,7 +44,7 @@ Review the pull request and provide feedback.
 
 ### Remote Agent File Import
 
-Import an agent file from an external repository using the `owner/repo/path@ref` format:
+Import an agent file from another repository with the `owner/repo/path@ref` format:
 
 ```yaml wrap
 ---
@@ -57,19 +57,15 @@ imports:
 Perform comprehensive code review using shared agent instructions.
 ```
 
-The agent instructions are merged with the workflow prompt, customizing the AI engine's behavior for specific tasks.
+The imported instructions are merged into the workflow prompt.
 
 ## Agent File Requirements
 
-- **Location**: Must be in a `.github/agents/` directory (local or remote repository)
-- **Format**: Markdown with YAML frontmatter
-- **Frontmatter**: Can include `name`, `description`, `tools`, and `mcp-servers`
-- **One per workflow**: Only one agent file can be imported per workflow
-- **Caching**: Remote agent files are cached by commit SHA in `.github/aw/imports/`
+Agent files must live in `.github/agents/`, use Markdown with YAML frontmatter, and may define fields such as `name`, `description`, `tools`, and `mcp-servers`. Remote imports are cached by commit SHA in `.github/aw/imports/`.
 
 ## Copilot Agent File Collections
 
-Organizations can create libraries of specialized custom agent files:
+Organizations can keep shared agent files in a dedicated repository:
 
 ```text
 acme-org/ai-agents/
@@ -82,15 +78,14 @@ acme-org/ai-agents/
         └── documentation-writer.md  # Technical documentation
 ```
 
-Teams import agent files based on workflow needs:
+Teams can then import the agent that fits the workflow:
 
 ```yaml wrap title="Security-focused PR review"
 ---
 on: pull_request
 engine: copilot
 imports:
   - acme-org/ai-agents/.github/agents/security-auditor.md@v2.0.0
-  - acme-org/ai-agents/.github/agents/code-reviewer.md@v1.5.0
 ---
 
 # Security Review
@@ -100,23 +95,16 @@ Perform comprehensive security review of this pull request.
 
 ## Combining Copilot Agent Files with Other Imports
 
-You can mix custom agent file imports with tool configurations and shared components:
+Agent files can be combined with shared tools, MCP servers, and policy imports:
 
 ```yaml wrap
 ---
 on: pull_request
 engine: copilot
 imports:
-  # Import specialized custom agent file
   - acme-org/ai-agents/.github/agents/security-auditor.md@v2.0.0
-
-  # Import tool configurations
   - acme-org/workflow-library/shared/tools/github-standard.md@v1.0.0
-
-  # Import MCP servers
   - acme-org/workflow-library/shared/mcp/database.md@v1.0.0
-
-  # Import security policies
   - acme-org/workflow-library/shared/config/security-policies.md@v1.0.0
 permissions:
   contents: read