Summary

The imports: directive in workflow frontmatter currently resolves paths exclusively relative to .github/workflows/. This prevents importing agent files from .github/agents/ (the documented location), from other directories in the repo, or from external repositories. This is a feature request to support repo-root-relative paths, absolute repo paths, and cross-repo imports.

Related: #19703 (bug report on .github/agents/ not resolving)

Problem

Organizations maintaining reusable agent skills across multiple repositories hit a wall quickly. Today, every consumer must either:

1. Copy agent .md files into .github/workflows/agents/ in each repo (duplicating content, making updates error-prone)
2. Use gh aw add to pull workflows — but this only supports complete workflows, not shared agent partials/skills

The import resolver anchors to --dir (default .github/workflows/), so:

• imports: [agents/planner.md] resolves to .github/workflows/agents/planner.md — works, but forces agents into the workflows directory
• imports: [.github/agents/planner.md] resolves to .github/workflows/.github/agents/planner.md — fails (Agent imports: .github/agents/ path does not resolve — must be under .github/workflows/ #19703)
• There is no syntax for referencing files outside .github/workflows/ or in other repositories

The compiled lock file confirms this — the runtime-import directive simply prepends .github/workflows/:

{{#runtime-import .github/workflows/agents/my-agent.md}}

Proposed behavior

1. Repo-root-relative paths (minimum viable fix)

Paths starting with .github/ or / should resolve from the repository root, not from the workflow directory:

imports:
  - .github/agents/planner.md        # resolves from repo root
  - agents/planner.md                # resolves relative to --dir (current behavior, preserved)

A simple heuristic: if the path starts with .github/ or contains a leading /, resolve from repo root. Otherwise, keep the current relative-to---dir behavior for backward compatibility.

2. Cross-repo imports (high-value addition)

Allow importing agent partials from other repositories using owner/repo syntax with a ref pin:

imports:
  - octo-org/shared-agents/.github/agents/code-review.md@v1.0.0
  - octo-org/shared-agents/.github/agents/security-scan.md@main

This would:

• Fetch the file at compile time (similar to how GitHub Actions resolves uses: references)
• Pin to a tag, branch, or SHA for reproducibility
• Inline the content into the compiled lock file (no runtime dependency on the source repo)
• Require network access only during gh aw compile, not at workflow runtime

3. URL-based imports (optional, lower priority)

For agents published as standalone files:

imports:
  - https://raw.githubusercontent.com/octo-org/agents/main/code-review.md

Use cases

Centralized agent library: An organization maintains a repo of vetted agent skills (code review, security analysis, planning). Multiple product repos import them without copy-pasting.

Versioned agent skills: Teams pin agent imports to specific versions. Upgrading is a one-line change in frontmatter, not a file copy.

Separation of concerns: Agent skill definitions (prompt engineering, domain knowledge) live separately from workflow configuration (triggers, permissions, tools). The documented .github/agents/ directory supports this, but the compiler doesn't.

Monorepo patterns: Large repos may organize agents outside .github/workflows/ to keep the workflows directory focused on workflow definitions.

Current workaround

Place agent files under .github/workflows/agents/ and import with paths relative to .github/workflows/:

imports:
  - agents/my-agent.md    # actually at .github/workflows/agents/my-agent.md

For cross-repo sharing, manually copy files or use gh aw add for complete workflows (not partials).

Environment

• gh-aw v0.65.1 (also reported in v0.53.3 via Agent imports: .github/agents/ path does not resolve — must be under .github/workflows/ #19703)
• macOS 15 / Darwin 25.3.0