fix more docs

Author: dsyme

docs/astro.config.mjs

@@ -204,7 +204,7 @@ export default defineConfig({
 						{ label: 'Command Triggers', link: '/reference/command-triggers/' },
 						{ label: 'Compilation Process', link: '/reference/compilation-process/' },
 						{ label: 'Concurrency', link: '/reference/concurrency/' },
-						{ label: 'Copilot Custom Agents', link: '/reference/copilot-custom-agents/' },
+						{ label: 'Copilot Agent Filess', link: '/reference/copilot-custom-agents/' },
 						{ label: 'Custom Engines', link: '/reference/custom-engines/' },
 						{ label: 'Custom Safe Outputs', link: '/reference/custom-safe-outputs/' },
 						{ label: 'Environment Variables', link: '/reference/environment-variables/' },

docs/src/content/docs/examples/agent-imports.md

@@ -1,19 +1,17 @@
 ---
-title: Reusing Copilot Custom Agents
-description: Create and reuse specialized AI agents with custom instructions and behavior for GitHub Agentic Workflows
+title: Importing Copilot Agent Files
+description: Import and reuse Copilot agent files with GitHub Agentic Workflows
 sidebar:
   order: 650
 ---
 
-"Custom Agents" is a term used in GitHub Copilot for specialized prompts for behaviors for specific tasks. They are markdown documents stored in the `.github/agents/` directory and imported via the `imports` field. Copilot supports agents natively, while other engines (Claude, Codex) inject the markdown body as a prompt.
+"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.
 
-## Creating a Copilot Custom Agent
-
-Create a markdown file in `.github/agents/` with agent-specific instructions:
+A typical custom agent file looks like this:
 
 ```markdown title=".github/agents/my-agent.md"
 ---
-name: My Copilot Custom Agent
+name: My Copilot Agent
 description: Specialized prompt for code review tasks
 ---
 
@@ -25,11 +23,11 @@ You are a specialized code review agent. Focus on:
 - Performance optimization
 ```
 
-## Using Copilot Custom Agents from Agentic Workflows
+## Using Copilot Agent Files from Agentic Workflows
 
-Import agent files in your workflow using the `imports` field. Agents can be imported from local `.github/agents/` directories or from external repositories.
+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.
 
-### Local Agent Import
+### Local Agent File Import
 
 Import an agent from your repository:
 
@@ -44,9 +42,9 @@ imports:
 Review the pull request and provide feedback.
 ```
 
-### Remote Agent Import
+### Remote Agent File Import
 
-Import an agent from an external repository using the `owner/repo/path@ref` format:
+Import an agent file from an external repository using the `owner/repo/path@ref` format:
 
 ```yaml wrap
 ---
@@ -59,12 +57,6 @@ imports:
 Perform comprehensive code review using shared agent instructions.
 ```
 
-Remote agent imports support versioning:
-
-- **Semantic tags**: `@v1.0.0` (recommended for production)
-- **Branch names**: `@main`, `@develop` (for development)
-- **Commit SHAs**: `@abc123def` (for immutable references)
-
 The agent instructions are merged with the workflow prompt, customizing the AI engine's behavior for specific tasks.
 
 ## Agent File Requirements
@@ -73,8 +65,74 @@ The agent instructions are merged with the workflow prompt, customizing the AI e
 - **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 agents are cached by commit SHA in `.github/aw/imports/`
+- **Caching**: Remote agent files are cached by commit SHA in `.github/aw/imports/`
+
+## Copilot Agent File Collections
+
+Organizations can create libraries of specialized custom agent files:
+
+```text
+acme-org/ai-agents/
+└── .github/
+    └── agents/
+        ├── code-reviewer.md         # General code review
+        ├── security-auditor.md      # Security-focused analysis
+        ├── performance-analyst.md   # Performance optimization
+        ├── accessibility-checker.md # WCAG compliance
+        └── documentation-writer.md  # Technical documentation
+```
+
+Teams import agent files based on workflow needs:
+
+```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
+
+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:
+
+```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
+  pull-requests: write
+safe-outputs:
+  create-pull-request-review-comment:
+    max: 10
+---
+
+# Comprehensive Security Review
+
+Perform detailed security analysis using specialized agent files and tools.
+```
 
-## The Copilot Custom Agent for Agentic Workflows
+## Related Documentation
 
-The [Copilot Custom Agent for Agentic Workflows](/gh-aw/reference/custom-agent-for-aw/) (`agentic-workflows.agent.md`) is a specialized custom agent designed to assist with creating, updating, importing, and debugging agentic workflows. It provides tailored instructions and behaviors to streamline workflow management tasks.
+- [Imports Reference](/gh-aw/reference/imports/) - Complete import system documentation
+- [Packaging & Distribution](/gh-aw/guides/packaging-imports/) - Managing workflow imports
+- [Frontmatter](/gh-aw/reference/frontmatter/) - Configuration options reference

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

@@ -1,5 +1,5 @@
 ---
-title: Copilot Custom Agent support for Agentic Workflows
+title: Copilot Agent Files support for Agentic Workflows
 description: How to create, update, import, and debug agentic workflows using our AI agent.
 sidebar:
   order: 1
@@ -11,7 +11,7 @@ import CopyEntireFileButton from '../../../components/CopyEntireFileButton.astro
 
 In this guide, we show you how to install and use the custom agent `agentic-workflows` to create, update, import, and debug agentic workflows in your repository.
 
-## Installing the Copilot Custom Agent for Agentic Workflows
+## Installing the Copilot Agent Files for Agentic Workflows
 
 Follow these steps to set up your repository for agentic workflows using the custom `agentic-workflows` agent.
 
@@ -21,7 +21,7 @@ Follow these steps to set up your repository for agentic workflows using the cus
    - Start [VSCode Agent Mode](https://code.visualstudio.com/docs/copilot/agents/overview), or
    - Start your coding agent in your repository
 
-2. **Install the Copilot Custom Agent for Agentic Workflows into your repository**. 
+2. **Install the Copilot Agent Files for Agentic Workflows into your repository**. 
 
    ```text wrap
    Initialize this repository for GitHub Agentic Workflows using https://github.com/github/gh-aw/blob/main/install.md
@@ -42,7 +42,7 @@ After initialization, you'll have:
 - `.github/agents/agentic-workflows.agent.md` - [A Copilot file](/gh-aw/reference/glossary/#agent-files) (custom AI instructions) for the `/agent agentic-workflows` command in Copilot Chat
 - Additional configuration files for workflow authoring
 
-## Using the Copilot Custom Agent for Agentic Workflows
+## Using the Copilot Agent Files for Agentic Workflows
 
 Once your repository is set up for agentic workflows, you can use the `agentic-workflows` agent from VSCode or GitHub.com to perform a variety of tasks:
 

docs/src/content/docs/reference/custom-agent-for-aw.mdx

@@ -102,7 +102,7 @@ engine:
 
 The `agent` field value should match the agent file name without the `.agent.md` extension. For example, `agent: technical-doc-writer` references `.github/agents/technical-doc-writer.agent.md`.
 
-See [Copilot Custom Agents](/gh-aw/reference/copilot-custom-agents/) for details on creating and configuring custom agents.
+See [Copilot Agent Filess](/gh-aw/reference/copilot-custom-agents/) for details on creating and configuring custom agents.
 
 ### Engine Environment Variables
 

docs/src/content/docs/reference/engines.md

@@ -562,7 +562,7 @@ tools: [read, edit, pr]
 
 ## References
 
-- [GitHub Copilot Custom Agents Configuration](https://docs.github.com/en/copilot/reference/copilot-custom-agents-configuration) - Official reference for custom agent configuration including tool aliases
+- [GitHub Copilot Agent Filess Configuration](https://docs.github.com/en/copilot/reference/copilot-custom-agents-configuration) - Official reference for custom agent configuration including tool aliases
 - [GitHub Copilot Custom Instructions Documentation](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions)
 - [About Custom Agents](https://docs.github.com/en/copilot/concepts/agents/coding-agent/about-custom-agents)
 - [GitHub Blog: Custom Instructions Support](https://github.blog/changelog/2025-07-23-github-copilot-coding-agent-now-supports-instructions-md-custom-instructions/)