Agent discovery flattens directories, misclassifies non-agent .md as agents, and silently drops non-.md sibling assets

[brindasanth]

Summary

When installing a local plugin.json "plugin collection" whose agents/<name>/ directories contain subfolders (e.g. guides/, templates/) alongside the real agent definition files, apm install's agent-primitive discovery:

1. Flattens every discovered .md file into a single directory (.claude/agents/ or .github/agents/), losing the original per-agent grouping.
2. Misclassifies any non-agent .md file in a nested subfolder as a real, invokable agent (e.g. a reference guide or a data template with placeholder frontmatter gets deployed as <name>.agent.md).
3. Silently drops every non-.md file in those same directories — scripts, binaries, images — with no warning and no equivalent output anywhere. This is the more serious issue: if an agent's own instructions reference a sibling script or asset file relative to its directory, that file is never deployed, breaking the agent.

By contrast, the Skills primitive handles this correctly: an installed skill's whole directory (scripts/, references/, templates/, evals/, binary assets, everything) is preserved intact as a bundle under .agents/skills/<name>/.... Agents get none of this — they're treated as a flat glob of individual markdown files with no bundling concept.

Environment

• apm version: 0.28.0 (e041462)
• OS: macOS (darwin-arm64)
• Install path exercised: local plugin.json "plugin collection", both --target claude and --target copilot

Repro

Given a plugin with:

my-plugin/
├── .claude-plugin/plugin.json      # "agents": ["./agents/my-agent"]
└── agents/
    └── my-agent/
        ├── my-agent.md              # real agent, valid frontmatter
        ├── guides/
        │   └── reference-doc.md     # NOT an agent — has frontmatter-shaped content but no agent schema
        ├── scripts/
        │   └── helper.py            # referenced by my-agent.md's instructions
        └── templates/
            └── starter.pptx         # referenced by my-agent.md's instructions

Run:

apm install /path/to/my-plugin --target claude
# or --target copilot

Actual result

.claude/agents/ (or .github/agents/) contains:

my-agent.agent.md
reference-doc.agent.md      # <- bogus: not an agent, deployed as one anyway

helper.py and starter.pptx are absent from the entire install output — not deployed anywhere, not referenced, not warned about.

Expected result

• Only files that are actually agent definitions (matching whatever schema/frontmatter contract APM uses to identify an agent) should be deployed as agents.
• Non-agent files nested under an agent's directory should either (a) be preserved as sibling assets alongside the deployed agent, the way the Skills primitive already does, or (b) at minimum, be skipped with a warning rather than silently dropped or silently misclassified.

Real-world impact (concrete example)

In our plugin, agents/gen-power-point/ contains 1 orchestrator + 6 subagents (correctly discovered), plus:

• guides/manifest-schema.md, guides/role-template-map.md, guides/template-authoring-guide.md, templates/README.md — all 4 deployed as bogus agents
• scripts/generate_pptx.py, scripts/validate_pptx.py, and 3 other .py scripts, plus 3 real .pptx starter templates (templates/executive.pptx, templates/status-review.pptx, templates/technical-deepdive.pptx) — all silently dropped

The agent's own generation workflow depends on those scripts and .pptx templates being present relative to its own directory. After apm install, the agent is deployed but non-functional — its own required assets never shipped, with no error or warning surfaced anywhere in the install output.

[danielmeppiel]

Thank you again for the concrete reproduction. We reassessed this from the
package boundary rather than treating it as an agent-file discovery bug.

APM's legacy Claude-plugin path retains the complete source under
apm_modules, but then projects individual agents into harness discovery
directories. That dissection breaks packages whose agents depend on their
original relative directory structure. We considered translating
${CLAUDE_PLUGIN_ROOT}, but that would require source migration, would not fix
your package unchanged, and would spread a Claude-specific convention through
APM's shared cross-harness infrastructure. We have therefore closed PR #2721
and are not pursuing that approach.

Agent Plugins 1.0 is the intended direction for preserving a plugin as one
installable unit. The published 1.0 portable contract currently standardizes
skills and MCP servers, not portable custom agents. It does permit
client-specific extension directories, and Copilot supports custom agents,
commands, rules, and hooks under com.github.copilot/. APM's native Copilot
registration keeps an Agent Plugin whole under apm_modules rather than
projecting its primitives.

Practical options today:

1. If Copilot is your required target, package the agents and their resources
   under the Agent Plugins 1.0 com.github.copilot/ namespace and install the
   plugin declaratively through APM with --target copilot. This keeps the unit
   whole. APM's current pack --format agent-plugin producer intentionally
   emits only the portable skills/MCP core, so a Copilot extension package must
   currently be authored directly.
2. If Claude Code is your required target, install the existing Claude plugin
   natively with Claude Code instead of sending it through APM's legacy
   primitive projection.
3. If you need one portable package across several harnesses today, model the
   bundle as a Skill where possible. Skills have a standardized bundle
   directory and can carry scripts, references, templates, and binary assets.
   There is not yet a portable cross-client custom-agent contract that APM can
   implement without inventing one.

We are keeping this issue open as the concrete requirement for custom-agent
bundle preservation. A legitimate near-term APM improvement is to detect this
lossy legacy layout and emit one actionable warning instead of reporting an
apparently successful installation. We should also qualify and document the
Copilot namespaced Agent Plugin path with an end-to-end fixture based on your
example. We should not guess arbitrary paths, duplicate bundles beside every
projected agent, or define an APM-only substitute for a portable standard.