The `dependencies:` documentation undersells APM and lacks guidance for users

[danielmeppiel]

The dependencies: documentation undersells APM and lacks guidance for users

Problem

The APM Dependencies section in the frontmatter reference has four gaps that leave workflow authors without the information they need to adopt APM effectively in their workflows.

1. No link to APM documentation.
The section links to the GitHub repo but not to the documentation site (https://microsoft.github.io/apm/), which covers package authoring, dependency management, governance, and the full CLI reference. Users who want to create, publish, or manage packages have no path to follow.

2. The description does not explain why dependencies: matters.
It describes the mechanics (pack in activation job, unpack in agent job) but not the value: apm.lock pins every package to an exact commit SHA, giving workflows reproducible agent context across runs. Lock file diffs are reviewable in PRs. For teams and enterprises, this is the difference between "it worked yesterday" and provable consistency. The APM governance guide covers this in depth -- the frontmatter docs should surface the core value and link there.

3. The description understates what APM packages contain and what the dependency format supports.
The current text says APM manages "skills, prompts, instructions, agents, and hooks." APM also supports installing plugins (the Claude plugin.json specification) as dependencies -- they are referenced just like any other primitive. A single dependencies: entry can provision both agent context (instructions, skills) and plugin tooling.

In addition, the examples only show the simple owner/repo shorthand. APM dependencies support inline version pinning with # (e.g., owner/repo#v2.0, owner/repo#main, owner/repo#commitsha), which is central to APM's reproducibility story and should be reflected in the examples.

4. No way for users to debug the pack/unpack flow locally.
The docs explain that the compiler packs in the activation job and unpacks in the agent job, but do not mention that apm pack and apm unpack are the underlying commands. Users hitting issues have no way to reproduce the flow outside of GitHub Actions.

Requested changes

In the dependencies: section of the frontmatter reference:

1. Add a link to the APM documentation site (https://microsoft.github.io/apm/) alongside the existing repo link.

2. Add a sentence explaining the reproducibility value: lock files pin exact versions, diffs are PR-reviewable, enables governance and audit trails. Link to the APM governance guide for depth -- do not duplicate the content.

3. Update the description of what APM manages to include plugins (Claude plugin.json format) alongside the existing primitives.

4. Expand the examples to show key capabilities beyond the simple shorthand:

dependencies:
  # Full APM package
  - microsoft/apm-sample-package
  # Individual primitive from any repository
  - github/awesome-copilot/skills/review-and-refactor
  # Plugin
  - github/awesome-copilot/plugins/context-engineering
  # Version-pinned to a tag
  - microsoft/apm-sample-package#v2.0
  # Git URL with sub-path and ref (object format)
  - git: https://github.com/acme/coding-standards.git
    path: instructions/security
    ref: v2.0

5. Mention apm pack / apm unpack as the underlying commands and link to the pack/unpack guide for local debugging.

Reference links

Resource	URL
APM documentation site	https://microsoft.github.io/apm/
APM governance guide	https://microsoft.github.io/apm/enterprise/governance/
Pack and Distribute guide	https://microsoft.github.io/apm/guides/pack-distribute/
gh-aw integration (APM docs)	https://microsoft.github.io/apm/integrations/gh-aw/
apm-action	https://github.com/microsoft/apm-action

We maintain the APM side of this integration and will keep our gh-aw integration page aligned. Happy to submit a PR for these changes if preferred.

[pelikhan]

Add a new documentation page in references about dependencies.