apm.yml inside collections/<name>/ is ignored — Collection detector preempts package resolution

[lirantal]

Summary

Two related gaps prevent a natural "meta-package" mental model — i.e., a sub-path inside a monorepo whose apm.yml purely declares dependencies on other skills/MCPs/packages:

1. /collections/ path segment hard-routes to the .collection.yml parser, shadowing any apm.yml that lives at <repo>/collections/<name>/apm.yml.
2. Pure dependency-only apm.yml (no .apm/ directory) fails validation, even though APM correctly resolves and installs the declared transitive deps before erroring out.

The first was acknowledged inline on closed issue #74 by @danielmeppiel:

when the subfolder is under a collections/ path, APM currently forces collection detection. I'll make sure apm.yml takes priority there too.

The second is a separate constraint that surfaces as soon as you work around the first.

Mental model the user expects

A monorepo of skills where each subfolder is a curated bundle with its own apm.yml listing transitive deps — installable by sub-path:

lirantal/skills/                          (one repo)
├── skills/                               (authored skills, single SKILL.md each)
│   ├── writing-style-explainer/
│   └── gh-bulk-repo-edit/
└── bundles/                              (curated meta-packages)
    └── writing/
        └── apm.yml                       ← lists skills + 3rd-party deps + MCPs

bundles/writing/apm.yml:

name: writing
version: 1.0.0
dependencies:
  apm:
    - lirantal/skills/skills/writing-style-explainer
    - blader/humanizer
  mcp: []

Goal: from a fresh project, apm install lirantal/skills/bundles/writing should pull in the two skills declared above.

Gap 1 — /collections/ shadowing

Repro

With the bundle at collections/writing/apm.yml:

$ apm install lirantal/skills/collections/writing --verbose
[*] Validating 1 package...
[x] lirantal/skills/collections/writing -- not accessible or doesn't exist

(The "Authentication failed" hint in --verbose is misleading — auth is fine.)

Object form exposes the real cause:

- git: https://github.com/lirantal/skills
  path: collections/writing

Failed to download dependency lirantal/skills: Collection manifest not found:
collections/writing.collection.yml (also tried .yaml)

APM hard-routes any /collections/ path to src/apm_cli/deps/collection_parser.py and never considers that a real apm.yml lives at collections/writing/apm.yml.

Why .collection.yml isn't a substitute

.collection.yml (per collection_parser.py) is a flat list of in-repo primitive files with kind ∈ {prompt, instruction, chat-mode, agent, context}. It cannot express skill deps, MCP server deps, or transitive apm: package deps.

Workaround

Rename collections/ → bundles/ (or any segment that doesn't contain collections). The /collections/ heuristic stops firing and APM proceeds to the subdirectory-package code path. ✅ Verified empirically.

Gap 2 — pure dependency-only meta-package fails validation

After the rename workaround, apm install lirantal/skills/bundles/writing correctly resolves and installs the two transitive deps:

[+] github.com/lirantal/skills/bundles/writing (cached)
[+] blader/humanizer (cached)
|-- Skill integrated -> .github/skills/
[+] github.com/lirantal/skills/skills/writing-style-explainer (cached)
|-- Skill integrated -> .github/skills/

But the meta-package itself fails post-validation:

Failed to download dependency lirantal/skills: Subdirectory is not a valid APM
package or Claude Skill: Not a valid APM package: writing has apm.yml but is
missing the required .apm/ directory. Add .apm/ with primitives (instructions,
skills, etc.) or add skills/<name>/SKILL.md for a skill bundle.

The install ends with [!] Installed 2 APM dependencies with 1 error(s). — non-zero status, CI-failing — even though the user-visible outcome is correct.

The validator currently rejects an apm.yml whose only role is to declare dependencies. There's no way to express "this is a meta-package, no own primitives, just a curated dependency set."

Workaround

Adding an empty .apm/ directory (committed via .gitkeep) silences the validator and produces a clean install:

$ apm install lirantal/skills/bundles/writing
[*] Installed 3 APM dependencies.

But this is a wart — users have to commit a placeholder file just to satisfy a structural check that doesn't reflect any real requirement, and it pollutes the repo with empty directories that exist only to humor the tool.

Suggested fix

For Gap 1

1. apm.yml should take priority over the /collections/ heuristic. If <path>/apm.yml exists in the target ref, treat it as a Subdirectory APM package and run the normal resolver. Only fall back to .collection.yml detection when no apm.yml is present.
2. (Optional) An object-form opt-out, e.g. kind: package, that disables auto-classification.

For Gap 2

3. Recognize dependency-only meta-packages as a valid package shape. When an apm.yml declares dependencies but no .apm/ content (and is not a skill bundle), don't treat it as malformed — just resolve its deps and exit cleanly. There is no good reason to require an empty .apm/ directory; the CLI should figure this out for users.
4. (Optional) If a marker is wanted for clarity, allow type: meta (or similar) in apm.yml to make intent explicit, rather than inferring shape from on-disk layout.

Together these would make the user's mental model — "a monorepo of bundles, each a curated dep set, installable by sub-path" — work natively, without renames or placeholder files.

Environment

• apm --version: Agent Package Manager (APM) CLI version 0.11.0 (dc0b53b)
• macOS (Darwin 25.4.0), zsh
• Reference: closed issue [FEATURE] APM.yml as a collection #74, repo lirantal/skills

[danielmeppiel]

Hey @lirantal -- update on this. PR #1097 addresses both gaps you flagged, with a slightly different shape for Gap 1 than you proposed. Wanted to give you the heads-up before merge so you can sanity-check it against your real workflow.

Gap 1 -- /collections/ shadowing

You proposed: "apm.yml should take priority over the /collections/ heuristic."

What we shipped is stronger and breaking: collections support is removed entirely (commit f1b8109a). The shadowing path no longer exists, so <repo>/collections/<name>/apm.yml is parsed as a normal subdirectory package -- you would NOT need the bundles/ rename workaround anymore.

Rationale for going further than your proposal: .collection.yml was a distinct primitive shape that overlapped poorly with apm.yml. With dep-only apm.yml accepted (Gap 2), .collection.yml had no remaining capability that apm.yml couldn't express better. Keeping both alive would have meant maintaining two parsers for one mental model.

For anyone with an existing .collection.yml file, install now surfaces a migration error pointing at apm.yml (covered by tests/unit/test_collection_migration_error.py).

Gap 2 -- dep-only meta-package fails validation

You proposed: "Recognize dependency-only meta-packages as a valid package shape ... no good reason to require an empty .apm/ directory."

Shipped exactly that. Validation now accepts an apm.yml whose only role is to declare apm: / mcp: / dev deps, with no .apm/ directory and no skills/<name>/SKILL.md. The [!] Installed N APM dependencies with 1 error(s) non-zero exit you reported is gone.

If validation does still fail somewhere downstream, the cascade-exit error now explicitly mentions the dep-only escape hatch (commit 56688ff2) so future users hit a clear signpost instead of a dead-end.

Coverage

Gap 2 specifically -- the load-bearing user-promise -- is covered by:

• tests/unit/test_dep_only_package.py -- 14 unit tests (apm/mcp/dev-deps detection, malformed shapes, hybrid with skill bundle, negative cases).
• tests/integration/test_apm_dependencies.py::test_dep_only_project_installs_dependencies_without_dot_apm -- real-fixture integration test of your exact bundles/writing/apm.yml scenario (install a dep-only meta-package, assert clean exit).
• tests/integration/test_apm_dependencies.py::test_apm_yml_without_deps_or_apm_dir_rejects_as_invalid -- negative boundary (an apm.yml with neither deps nor .apm/ is still rejected).
• tests/integration/test_validation_cascade_boundary.py -- verifies the cascade-exit error wording mentions the escape hatch.

Gap 1 is covered by the migration-error suite plus the broader subdirectory-package tests that previously had to special-case /collections/.

What we'd love your eyes on

If you have a moment, the highest-value sanity check is: re-run your original repro on PR #1097's branch with your original layout (collections/writing/apm.yml, no bundles/ rename, no .gitkeep in .apm/). That single command should now succeed cleanly:

apm install lirantal/skills/collections/writing

If it does -- both gaps closed end-to-end. If it doesn't, that's a regression we want to know about before merge.

Thanks again for the precise repro and the side-by-side mental-model framing in the issue body. Made the diagnosis trivial.

[lirantal]

Sounds good, thanks!