Bug: .github/agents imports on Claude/Codex take fragile prompt-assembly path; .github/snippets avoids it

[corymhall]

Summary

Docs say .github/agents/*.md imports should work with non-Copilot engines by injecting markdown body into the prompt, but in practice this path still uses special prompt assembly (AGENT_CONTENT + PROMPT_TEXT) and remote-merge behavior that appears brittle.

In our CI this manifested as:

Error: Input must be provided either through stdin or as a prompt argument when using --print

Switching the same content from ../agents/code-review.md to ../snippets/code-review.md removed the special path and resolved the failure.

Environment

• gh aw version v0.53.1 (2026-03-04)

Docs vs Behavior

Docs indicate .github/agents should work for Claude/Codex by injecting markdown body

• https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/copilot-custom-agents.md#L8
• https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/imports.md#L76-L120

Current compiler still emits special agent assembly path

• Claude: AGENT_CONTENT + PROMPT_TEXT
  • https://github.com/github/gh-aw/blob/main/pkg/workflow/claude_engine.go#L221-L234
• Codex: similar path
  • https://github.com/github/gh-aw/blob/main/pkg/workflow/codex_engine.go#L215-L222
• Main job still emits merge_remote_agent_github_folder for agent imports
  • https://github.com/github/gh-aw/blob/main/pkg/workflow/compiler_yaml_main_job.go#L102-L113

Minimal Repro

Create two workflows with identical content except import path:

1. imports: ../agents/code-review.md
2. imports: ../snippets/code-review.md

Compile both with gh aw compile.

Observed

../agents/... lockfile includes:

• AGENT_CONTENT=...awk...
• PROMPT_TEXT=...printf...
• merge_remote_agent_github_folder

../snippets/... lockfile does not include those pieces.

Why this seems buggy

If docs guarantee .github/agents as valid prompt injection for Claude/Codex, behavior should be as robust as snippet imports. Today, .github/agents appears to trigger extra legacy/special handling with different failure modes.

Related real-world diff

This PR shows the practical workaround that fixed CI by moving import path from agents to snippets:

• https://github.com/pulumi/pulumi-awsx/pull/1889/changes

Request

• Confirm whether this is expected behavior or a bug.
• If bug: align .github/agents handling with robust snippet-style prompt path for Claude/Codex (or document explicit limitations/workarounds).