Replace engine.custom-agent field with imports-based agent files by Copilot · Pull Request #2838 · github/gh-aw

Copilot · 2025-10-31T00:11:56Z

The engine.custom-agent field is removed. Agent files are now imported via the imports field. Any markdown file under .github/agents/ directory is treated as a custom agent file.

Changes

Schema: Removed custom-agent from engine configuration
Import detection: Any markdown files under .github/agents/ directory are treated as agent files
Validation: Only one agent file allowed per workflow (enforced during import processing)
Engine integration: All engines (copilot, claude, codex) now read agent path from WorkflowData.AgentFile instead of EngineConfig.CustomAgent
Workflow updates: technical-doc-writer.md moved to .github/agents/, workflow now uses imports

Migration

Before:

engine:
  id: copilot
  custom-agent: .github/agents/my-agent.md

After:

engine:
  id: copilot
imports:
  - .github/agents/my-agent.md

No legacy support - clean break.

Original prompt

Remove the "custom-agent" field and instead support importing custom agent file in the "imports" section.

.agent.md under .github/agents are treated as agent file

only one agent is allowed

same import strategy

remove custom-agent field, no legacy support

update JSON schema description

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

- Remove custom-agent field from engine configuration - Add support for .agent.md files in imports - Only one agent file allowed per workflow - Agent files detected by .agent.md extension - Update all engines to use AgentFile from WorkflowData - Update tests to reflect new import-based approach - Update technical-doc-writer workflow to use imports - Update JSON schema to remove custom-agent field Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

- Update custom-agents.instructions.md to reflect imports approach - Remove custom-agent references from frontmatter docs - Document .agent.md extension requirement - Document one agent file per workflow limitation - Update example workflows to use imports Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

pelikhan · 2025-10-31T00:59:51Z

@copilot any markdown file under .github/agents is considered an custom agent. .agent.md is not required.

… an agent Changed agent file detection from checking .agent.md extension to checking if the file is under .github/agents/ directory. This matches the expected behavior where any markdown file under .github/agents is treated as a custom agent file. Changes: - Updated detection logic in ProcessImportsFromFrontmatterWithManifest - Renamed technical-doc-writer.agent.md -> technical-doc-writer.md - Updated all documentation to reflect directory-based detection - Updated schema examples and descriptions - Updated tests to use .md extension Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot · 2025-10-31T01:10:45Z

@copilot any markdown file under .github/agents is considered an custom agent. .agent.md is not required.

Fixed in commit 2188b18. Changed agent file detection from .agent.md extension to directory-based: any markdown file under .github/agents/ is now treated as a custom agent file. Updated all documentation and tests accordingly.

github-actions · 2025-10-31T02:53:59Z

Agentic Changeset Generator triggered by this pull request.

Copilot

Pull Request Overview

This PR removes the engine.custom-agent field and replaces it with an imports-based approach for custom agent files. Agent files are now detected automatically when markdown files under .github/agents/ directory are imported via the imports field.

Key changes:

Removed custom-agent field from engine configuration with no legacy support
Agent files now imported through standard imports mechanism with validation for single agent per workflow
All engines (copilot, claude, codex) updated to read agent path from WorkflowData.AgentFile instead of EngineConfig.CustomAgent

Reviewed Changes

Copilot reviewed 15 out of 16 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
pkg/workflow/validation.go	Simplified agent file validation to check existence without complex path resolution
pkg/workflow/engine_agent_import_test.go	Updated test names and removed engine config extraction tests, focused on imports-based agent testing
pkg/workflow/engine.go	Removed CustomAgent field from EngineConfig struct and related extraction logic
pkg/workflow/copilot_engine.go	Updated to use WorkflowData.AgentFile instead of EngineConfig.CustomAgent
pkg/workflow/compiler_jobs.go	Updated checkout step logic to check WorkflowData.AgentFile
pkg/workflow/compiler.go	Added AgentFile field to WorkflowData and populated from imports result
pkg/workflow/codex_engine.go	Updated to use WorkflowData.AgentFile for agent file handling
pkg/workflow/claude_engine.go	Updated to use WorkflowData.AgentFile for agent file handling
pkg/parser/schemas/main_workflow_schema.json	Removed custom-agent field from schema and updated imports description
pkg/parser/frontmatter.go	Added agent file detection logic in imports processing with single agent validation
docs/src/content/docs/reference/frontmatter-full.md	Updated documentation to reflect imports-based agent configuration
.github/workflows/unbloat-docs.lock.yml	Updated Node.js action version (unrelated change)
.github/workflows/technical-doc-writer.md	Migrated from custom-agent field to imports-based configuration
.github/workflows/technical-doc-writer.lock.yml	Updated generated workflow to use full agent file path
.github/instructions/custom-agents.instructions.md	Updated documentation to reflect new imports-based agent configuration

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-10-31T02:54:24Z

pkg/parser/frontmatter.go

 		processedFiles = append(processedFiles, importPath)

+		// Check if this is a custom agent file (any markdown file under .github/agents)
+		isAgentFile := strings.Contains(fullPath, "/.github/agents/") && strings.HasSuffix(strings.ToLower(fullPath), ".md")


The agent file detection logic may fail for Windows paths or paths that don't use Unix-style separators. Consider using filepath.Separator or strings.Contains(filepath.ToSlash(fullPath), \"/.github/agents/\") for cross-platform compatibility.

Suggested change

isAgentFile := strings.Contains(fullPath, "/.github/agents/") && strings.HasSuffix(strings.ToLower(fullPath), ".md")

isAgentFile := strings.Contains(filepath.ToSlash(fullPath), "/.github/agents/") && strings.HasSuffix(strings.ToLower(fullPath), ".md")

Copilot · 2025-10-31T02:54:24Z

pkg/parser/frontmatter.go

+		if isAgentFile {
+			if agentFile != "" {
+				// Multiple agent files found - error
+				return nil, fmt.Errorf("multiple agent files found in imports: '%s' and '%s'. Only one agent file is allowed per workflow", agentFile, importPath)


The error message uses importPath but should use fullPath for consistency with how agentFile is set on line 452. This could show incorrect path information in the error message.

Suggested change

return nil, fmt.Errorf("multiple agent files found in imports: '%s' and '%s'. Only one agent file is allowed per workflow", agentFile, importPath)

return nil, fmt.Errorf("multiple agent files found in imports: '%s' and '%s'. Only one agent file is allowed per workflow", agentFile, fullPath)

This PR updates the documentation based on features merged in the last 24 hours. ## Documentation Updates ### Custom Agent Files (PR #2838, #2837) - Added comprehensive documentation for custom agent files in the AI Engines reference - Documented the new imports-based approach for agent files - Provided migration guide from deprecated `engine.custom-agent` field - Included examples of creating and using custom agents ### Permission Validation (PR #2843) - Documented new permission validation behavior in non-strict mode - Added examples of warning messages when permissions are under-provisioned - Explained the difference between non-strict and strict mode validation - Provided actionable guidance for resolving permission warnings ### Agent File Imports (PR #2838) - Updated Imports reference to explain agent file imports - Clarified that only one agent file can be imported per workflow - Cross-referenced Custom Agent Files documentation in Engines reference ## Changes Made - Updated `docs/src/content/docs/reference/engines.md`: - Added "Custom Agent Files" section with creation and usage examples - Documented agent file requirements and constraints - Provided migration guide from `engine.custom-agent` to `imports` - Updated `docs/src/content/docs/reference/frontmatter.md`: - Added "Permission Validation" subsection under Permissions - Documented non-strict mode warning behavior - Documented strict mode error behavior - Included example warning messages - Updated `docs/src/content/docs/reference/imports.md`: - Added "Agent Files" section - Updated "Frontmatter Merging" to mention agent file fields 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Initial plan

6271f75

Copilot AI assigned Copilot and pelikhan Oct 31, 2025

Copilot started work on behalf of pelikhan October 31, 2025 00:12 View session

Copilot AI and others added 3 commits October 31, 2025 00:18

Initial analysis - understanding current custom-agent implementation

c6d27b9

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Remove custom-agent field and update imports section~~ Replace engine.custom-agent field with imports-based agent files Oct 31, 2025

Copilot AI requested a review from pelikhan October 31, 2025 00:43

Copilot finished work on behalf of pelikhan October 31, 2025 00:43

Copilot started work on behalf of pelikhan October 31, 2025 01:00 View session

Copilot finished work on behalf of pelikhan October 31, 2025 01:11

pelikhan marked this pull request as ready for review October 31, 2025 02:53

Copilot AI review requested due to automatic review settings October 31, 2025 02:53

pelikhan approved these changes Oct 31, 2025

View reviewed changes

pelikhan enabled auto-merge (squash) October 31, 2025 02:53

Copilot AI reviewed Oct 31, 2025

View reviewed changes

Add changeset [skip-ci]

02dc867

pelikhan disabled auto-merge October 31, 2025 03:13

pelikhan merged commit 3ad76ba into main Oct 31, 2025
4 checks passed

pelikhan deleted the copilot/remove-custom-agent-field branch October 31, 2025 03:13

github-actions bot mentioned this pull request Oct 31, 2025

[docs] Update documentation for features from 2025-10-31 #2851

Merged

Copilot AI mentioned this pull request Oct 31, 2025

Format code and recompile workflows #2873

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Replace engine.custom-agent field with imports-based agent files#2838

Replace engine.custom-agent field with imports-based agent files#2838
pelikhan merged 6 commits intomainfrom
copilot/remove-custom-agent-field

Copilot AI commented Oct 31, 2025 •

edited

Loading

Uh oh!

pelikhan commented Oct 31, 2025

Uh oh!

Copilot AI commented Oct 31, 2025

Uh oh!

github-actions bot commented Oct 31, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Oct 31, 2025

Uh oh!

Copilot AI Oct 31, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	isAgentFile := strings.Contains(fullPath, "/.github/agents/") && strings.HasSuffix(strings.ToLower(fullPath), ".md")
	isAgentFile := strings.Contains(filepath.ToSlash(fullPath), "/.github/agents/") && strings.HasSuffix(strings.ToLower(fullPath), ".md")

	return nil, fmt.Errorf("multiple agent files found in imports: '%s' and '%s'. Only one agent file is allowed per workflow", agentFile, importPath)
	return nil, fmt.Errorf("multiple agent files found in imports: '%s' and '%s'. Only one agent file is allowed per workflow", agentFile, fullPath)

Conversation

Copilot AI commented Oct 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Migration

Uh oh!

pelikhan commented Oct 31, 2025

Uh oh!

Copilot AI commented Oct 31, 2025

Uh oh!

github-actions bot commented Oct 31, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Oct 31, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 31, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented Oct 31, 2025 •

edited

Loading