diff --git a/docs/src/content/docs/reference/custom-agents.md b/docs/src/content/docs/reference/custom-agents.md new file mode 100644 index 0000000000..90cbe31fa4 --- /dev/null +++ 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 index 9b9c4155bd..93dfbb3a2b 100644 --- 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 index 640c8d72e5..9064e9ac58 100644 --- 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) | - | - |