docs: clarify APM's role for skills, unify plugins-as-packages, add ADO sub-path examples, state stability

[danielmeppiel]

TL;DR

A user audited our docs against actual behavior and surfaced six high-signal gaps. This PR ships all six in a single doc-only change. A separate parser-fix issue tracks the one underlying bug we found while validating the ADO write-up (full https URL with sub-path).

Why

User feedback (verbatim quotes; full thread held privately):

1. "creating a package and initializing a project appear to be different concepts, yet in practice both are done via apm init... The documentation sometimes implies that a .apm/ directory is created as part of package creation, but in reality .apm/ is not generated by apm init."
2. "It's unclear how much value a SKILL.md provides beyond being another instruction file, and how authors should design them differently."
   3a. "The documentation states that plugins can be used 'instead of' packages... Are plugins simply an alternative distribution format, or do they have strategic advantages over packages?"
   3b. "There is no documented mechanism explaining how such users are expected to load or activate the plugin after extraction... no native loader outside APM."
3. "The dependencies guide mentions support for git URL + path + ref, including Azure DevOps repositories. I tested this with our ADO repo but could not get it to work (failed)."
4. "How stable and recommended is this feature today?" (re: apm run / Copilot CLI runtime)

Maintainer reframings applied:

• Skills authoring is agentskills.io's job, not ours; APM is the package manager for skills, not the spec.
• A plugin is a package, a package is a plugin. apm pack defaults to plugin-compatible output. The "Three modes" framing in the docs was the bug.
• Without APM, you give up the manifest, lockfile, governance, security scanning. Same trade-off as npx skills add vs apm install.
• apm run is fully experimental, vendor-neutral, modeled on npx-for-npm, not currently prioritized.

What

File	Change
guides/skills.md	Reframe opening to defer SKILL.md authoring to agentskills.io. Fix the apm init tree (no .apm/ is scaffolded). Replace emoji checkmarks with [+]/[x].
guides/plugins.md	Drop "Three modes" table. State plainly: every package is plugin-compatible by default; the only choice is whether you keep an apm.yml.
guides/pack-distribute.md	New "Without APM: what you give up" section with comparison table and host-specific install paths.
guides/dependencies.md	Add ADO object-form sub-path + ref example with shorthand alternative; warn that the full https://...repo/sub-path URL form is rejected today.
getting-started/authentication.md	Add ADO shorthand sub-path + ref example.
introduction/what-is-apm.md	Add explicit Stability section: stable surface (install / lock / audit / pack / unpack / cross-runtime deploy) vs experimental (apm run, Cowork).

Validation

• Tested ADO sub-path + ref combinations against DependencyReference.parse() and parse_from_dict() for all 8 URL shapes:
  • Working: all shorthand forms (dev.azure.com/...[/sub-path][#ref]) and all object-form variants.
  • Broken: https://dev.azure.com///_git// with or without #ref raises Invalid Azure DevOps repository path. Tracked in a separate issue with a failing test as repro.
• All edits in docs/ only - no source or CI touched.
• Encoding: only ASCII added; existing box-drawing in directory trees preserved (matches existing convention in docs/; the project encoding rule scopes Markdown to .github/).

How to test

git fetch origin docs/customer-feedback-clarifications
git checkout docs/customer-feedback-clarifications
cd docs && npm install && npm run dev
# Visit:
#   /guides/skills/                       (new opening + agentskills.io callout)
#   /guides/plugins/                      (no more 'Three modes' table)
#   /guides/pack-distribute/              ('Without APM: what you give up' section)
#   /guides/dependencies/                 (ADO sub-path example + parser warning)
#   /getting-started/authentication/      (ADO _git sub-path example)
#   /introduction/what-is-apm/            (Stability section above 'What's next')

Verify the user-cited contradictions are gone:

• guides/skills.md no longer claims apm init creates .apm/.
• guides/plugins.md no longer frames plugins as an alternative to packages.
• guides/pack-distribute.md now answers "what happens for non-APM consumers."
• guides/dependencies.md documents ADO sub-path + ref with the exact two forms that work today.

Trade-offs

• Pruned the "AI-optimized meta-guide" marketing copy in guides/skills.md. We lose some aspirational framing but stop overlapping with what agentskills.io owns.
• Kept the "Three modes" rewrite minimal in guides/plugins.md rather than restructuring the whole page; downstream sections (Overview, Installation, Examples) still reflect the old framing in places and can be tightened in a follow-up.
• The ADO https://...sub-path warning links to the parser-fix issue but ships before the fix lands. We can drop the warning in a follow-up PR once the parser is fixed.

Related

• Engineering follow-up: parser fix for ADO https:// URL form with sub-path (filed as a separate issue with a failing test as repro).

[Copilot]

Pull request overview

Doc-only update that responds to customer-reported documentation gaps by clarifying APM's role (package manager vs skill spec), unifying the plugins-as-packages story, documenting Azure DevOps sub-path usage, and explicitly labeling stable vs experimental surfaces.

Changes:

• Reframe skills docs to defer SKILL.md authoring guidance to agentskills.io and correct apm init scaffolding expectations.
• Clarify that plugins and packages are the same artifact in APM, and add a “Without APM” consumer trade-off section for plugin bundles.
• Add Azure DevOps sub-path + ref examples (and document the currently-broken full-https://.../<sub-path> URL shape) plus a Stability section in the intro docs.

Show a summary per file

File	Description
docs/src/content/docs/introduction/what-is-apm.md	Adds a Stability section distinguishing stable vs experimental CLI/integrations.
docs/src/content/docs/guides/skills.md	Reframes skills positioning, corrects apm init output tree, replaces emoji markers with ASCII status tokens.
docs/src/content/docs/guides/plugins.md	Removes “three modes” framing and states plugins/packages are the same artifact with apm.yml as the main authoring choice.
docs/src/content/docs/guides/pack-distribute.md	Adds “Without APM: what you give up” section describing consumer trade-offs and host placement notes.
docs/src/content/docs/guides/dependencies.md	Adds Azure DevOps object-form sub-path + ref example and a note documenting the unsupported full-URL-with-sub-path form.
docs/src/content/docs/getting-started/authentication.md	Adds Azure DevOps _git sub-path + ref install example.

Copilot's findings

• Files reviewed: 7/7 changed files
• Comments generated: 3