Collections discovery (verified)
Collections are installable “packs” that can contain profiles, agents, context files, and sometimes modules. This page
describes how applications discover collections and resolve a collection name to a filesystem path, based on the
amplifier-collections library and the CLI wiring.
The resolver: CollectionResolver
The core mechanism is CollectionResolver. It takes search paths from the app (policy), then
resolves collection names by inspecting filesystem content (mechanism).
Source: microsoft/amplifier-collections/src/amplifier_collections/resolver.py
Resolution order
The resolver checks:
- Source override (if a source provider is injected by the app) — file paths only.
- Filesystem search in reverse precedence order (highest precedence path wins).
Metadata name is the source of truth
A subtle but important detail: discovery is driven by the collection’s metadata name (read from
pyproject.toml), not by the directory name. This allows a repo directory like
amplifier-collection-design-intelligence to expose the collection name
design-intelligence.
design-intelligence:designer can work even if the
on-disk directory name differs. It’s also why “find all collections” requires scanning directories and reading metadata.
Flat vs nested collection layouts
The resolver supports both patterns:
- Flat:
collections/<something>/pyproject.toml - Nested:
collections/<something>/<package>/pyproject.toml
How the CLI wires it up
The CLI constructs a collection resolver with CLI-specific search paths and injects a source provider backed by its config system:
-
create_collection_resolver(): microsoft/amplifier-app-cli/amplifier_app_cli/paths.py - Collection management commands: microsoft/amplifier-app-cli/amplifier_app_cli/commands/collection.py
Where collections show up elsewhere
Collections aren’t just “more profiles”: the CLI also uses collections to discover module directories, feeding them into module resolution as a dedicated layer.