githubnext · pelikhan · Oct 31, 2025 · Oct 31, 2025 · Oct 31, 2025
diff --git a/docs/src/content/docs/reference/custom-agents.md b/docs/src/content/docs/reference/custom-agents.md
@@ -0,0 +1,74 @@
+---
+title: Custom Agent Files
+description: Create specialized AI agents with custom instructions and behavior for GitHub Agentic Workflows
+sidebar:
+  order: 650
+---
+
+All AI engines (Copilot, Claude, Codex) support custom agent files that provide specialized instructions and behavior. Agent files are markdown documents stored in the `.github/agents/` directory and imported via the `imports` field.
+
+## Creating a Custom Agent
+
+Create a markdown file in `.github/agents/` with agent-specific instructions:
+
+```markdown title=".github/agents/my-agent.md"
+---
+name: My Custom Agent
+description: Specialized agent for code review tasks
+tools:
+  edit:
+  bash: ["git", "gh"]
+---
+
+# Agent Instructions
+
+You are a specialized code review agent. Focus on:
+- Code quality and best practices
+- Security vulnerabilities
+- Performance optimization
+```
+
+## Using Custom Agents
+
+Import the agent file in your workflow using the `imports` field:
+
+```yaml
+---
+on: pull_request
+engine: copilot
+imports:
+  - .github/agents/my-agent.md
+---
+
+Review the pull request and provide feedback.
+```
+
+The agent instructions are merged with the workflow prompt, customizing the AI engine's behavior for specific tasks.
+
+## Agent File Requirements
+
+- **Location**: Must be in `.github/agents/` directory
+- **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
+- **Import syntax**: Use `imports` field (not `engine.custom-agent`)
+
+## Migration from engine.custom-agent
+
+The `engine.custom-agent` field has been removed. Migrate to the `imports` approach:
+
+**Before (deprecated):**
+```yaml
+engine:
+  id: copilot
+  custom-agent: .github/agents/my-agent.md
+```
+
+**After (current):**
+```yaml
+engine: copilot
+imports:
+  - .github/agents/my-agent.md
+```
+
+No backward compatibility - update workflows to use the new `imports` syntax.
diff --git a/docs/src/content/docs/reference/engines.md b/docs/src/content/docs/reference/engines.md
@@ -228,73 +228,7 @@ engine:
 
 ## Custom Agent Files
 
-All AI engines (Copilot, Claude, Codex) support custom agent files that provide specialized instructions and behavior. Agent files are markdown documents stored in the `.github/agents/` directory and imported via the `imports` field.
-
-### Creating a Custom Agent
-
-Create a markdown file in `.github/agents/` with agent-specific instructions:
-
-```markdown title=".github/agents/my-agent.md"
----
-name: My Custom Agent
-description: Specialized agent for code review tasks
-tools:
-  edit:
-  bash: ["git", "gh"]
----
-
-# Agent Instructions
-
-You are a specialized code review agent. Focus on:
-- Code quality and best practices
-- Security vulnerabilities
-- Performance optimization
-```
-
-### Using Custom Agents
-
-Import the agent file in your workflow using the `imports` field:
-
-```yaml
----
-on: pull_request
-engine: copilot
-imports:
-  - .github/agents/my-agent.md
----
-
-Review the pull request and provide feedback.
-```
-
-The agent instructions are merged with the workflow prompt, customizing the AI engine's behavior for specific tasks.
-
-### Agent File Requirements
-
-- **Location**: Must be in `.github/agents/` directory
-- **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
-- **Import syntax**: Use `imports` field (not `engine.custom-agent`)
-
-### Migration from engine.custom-agent
-
-The `engine.custom-agent` field has been removed. Migrate to the `imports` approach:
-
-**Before (deprecated):**
-```yaml
-engine:
-  id: copilot
-  custom-agent: .github/agents/my-agent.md
-```
-
-**After (current):**
-```yaml
-engine: copilot
-imports:
-  - .github/agents/my-agent.md
-```
-
-No backward compatibility - update workflows to use the new `imports` syntax.
+All AI engines support custom agent files that provide specialized instructions and behavior. See the [Custom Agent Files](/gh-aw/reference/custom-agents/) reference for complete documentation on creating and using custom agents.
 
 ## Engine Environment Variables
 

diff --git a/docs/src/content/docs/status.mdx b/docs/src/content/docs/status.mdx
@@ -60,7 +60,7 @@ Browse the [workflow source files](https://github.com/githubnext/gh-aw/tree/main
 | [Smoke Copilot Firewall](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/smoke-copilot.firewall.md) | copilot | [![Smoke Copilot Firewall](https://github.com/githubnext/gh-aw/actions/workflows/smoke-copilot.firewall.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/smoke-copilot.firewall.lock.yml) | `0 0,6,12,18 * * *` | - |
 | [Smoke Detector - Smoke Test Failure Investigator](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/smoke-detector.md) | claude | [![Smoke Detector - Smoke Test Failure Investigator](https://github.com/githubnext/gh-aw/actions/workflows/smoke-detector.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/smoke-detector.lock.yml) | - | - |
 | [Smoke OpenCode](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/smoke-opencode.md) | copilot | [![Smoke OpenCode](https://github.com/githubnext/gh-aw/actions/workflows/smoke-opencode.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/smoke-opencode.lock.yml) | `0 0,6,12,18 * * *` | - |
-| [Technical Documentation Writer for GitHub Actions](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/technical-doc-writer.md) | claude | [![Technical Documentation Writer for GitHub Actions](https://github.com/githubnext/gh-aw/actions/workflows/technical-doc-writer.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/technical-doc-writer.lock.yml) | - | - |
+| [Technical Doc Writer](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/technical-doc-writer.md) | copilot | [![Technical Doc Writer](https://github.com/githubnext/gh-aw/actions/workflows/technical-doc-writer.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/technical-doc-writer.lock.yml) | - | - |
 | [Test jqschema](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/test-jqschema.md) | copilot | [![Test jqschema](https://github.com/githubnext/gh-aw/actions/workflows/test-jqschema.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/test-jqschema.lock.yml) | - | - |
 | [Test Ollama Threat Scanning](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/test-ollama-threat-detection.md) | copilot | [![Test Ollama Threat Scanning](https://github.com/githubnext/gh-aw/actions/workflows/test-ollama-threat-detection.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/test-ollama-threat-detection.lock.yml) | - | - |
 | [Test Post-Steps Workflow](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/test-post-steps.md) | copilot | [![Test Post-Steps Workflow](https://github.com/githubnext/gh-aw/actions/workflows/test-post-steps.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/test-post-steps.lock.yml) | - | - |