docs(readme): add 'Coming from npx skills add?' conversion block

[danielmeppiel]

TL;DR

Adds one ~5-line "Coming from npx skills add?" block to README.md, sitting between the git clone / apm install example and the "three promises" section -- the exact funnel moment where readers familiar with npx skills add decide whether to switch. No other content changes.

Problem (WHY)

The 0.9.4 release shipped SKILL_BUNDLE (PR #974) so that every public repo installable via npx skills add owner/repo is also installable via apm install owner/repo. That is the strongest single conversion claim APM has against the current incumbent in agent-skill installation (skills.sh / vercel-labs/skills), and it is invisible on the README -- so the conversion never happens.

Without this block, an npx skills add user reading our README sees a manifest-shaped product that looks unrelated to what they do today. The mental cost to evaluate "would this also work for me?" is high enough that most bounce.

Approach (WHAT)

A surgical edit, not a rewrite:

• Where: between the git clone / apm install example (existing line 45) and ## The three promises (existing line 47). That is the moment a reader has just understood "what APM does" but has not yet committed to learning more.
• Form: bold inline lead (**Coming from npx skills add?**) -- not an h3 -- so non-npx readers scroll past without losing the page narrative; npx readers self-identify in <1s.
• Two real install commands: apm install vercel-labs/agent-skills and apm install vercel-labs/agent-skills --skill deploy-to-vercel. Both repos / skill names are real, falsifiable in 30 seconds.
• One outbound link only: reference/package-types/#skill-bundle -- where the SKILL_BUNDLE shape, manifest, and lockfile are already documented. README's job is to convert the click; docs explain.

Implementation (HOW)

 apm install    # every agent is configured

+Coming from npx skills add? Drop-in:
+
+bash +apm install vercel-labs/agent-skills # whole bundle, like npx skills add +apm install vercel-labs/agent-skills --skill deploy-to-vercel # one skill, persisted to apm.yml +
+
+Same install gesture. You also get a manifest, lockfile, and reproducibility.
+

The three promises

9 insertions, 0 deletions. No other file touched.

## Trade-offs

- **Bold inline lead vs. h3 sub-section.** h3 would give the block more visual weight but would also register as a major page section, slowing the funnel for the ~80% of readers who don't come from `npx skills add`. The bold inline is intentionally a "side note" so it's invisible if not relevant.
- **Naming a competitor in the README.** `npx skills add` is a known surface in the agent-skills ecosystem (`skills.sh` / `agentskills.io`), and the framing is incumbent-friendly ("drop-in", "same install gesture") rather than challenger-aggressive. Lower risk than naming a different commercial product. Not naming it would mean readers who use it daily can't recognize themselves on the page.
- **Concrete repo + skill names rather than `<owner>/<repo>` placeholders.** Concrete is more compelling and verifiable; it does mean the block depends on `vercel-labs/agent-skills` continuing to exist with `deploy-to-vercel` in it. Both are stable public artifacts; the cost of a future stale claim is one README PR.

## Validation evidence

Both commands verified locally against `vercel-labs/agent-skills` immediately before this PR:

$ apm install vercel-labs/agent-skills
[+] vercel-labs/agent-skills (cached)
|-- 7 skill(s) integrated -> .github/skills/

$ apm install vercel-labs/agent-skills --skill deploy-to-vercel
[+] vercel-labs/agent-skills (cached)
|-- 1 skill(s) integrated -> .github/skills/
[*] Persisted skill subset for vercel-labs/agent-skills: [deploy-to-vercel]

Resulting `apm.yml` after the second install:
```yaml
dependencies:
  apm:
  - git: vercel-labs/agent-skills
    skills:
    - deploy-to-vercel

Resulting apm.lock.yaml:

- repo_url: vercel-labs/agent-skills
  resolved_commit: ce3e64e468f8fa09a2d075d102771838061fdac0
  package_type: skill_bundle
  skill_subset:
  - deploy-to-vercel

Every claim in the new block (drop-in install, --skill lever, persistence to apm.yml, lockfile reproducibility) is reproducible from the snippet itself.

How to test

1. Open the rendered README on this branch.
2. Confirm the new block sits between the git clone example and the "three promises" section.
3. Run the two apm install commands above against APM 0.9.4 and confirm the integration counts and the apm.yml / apm.lock.yaml shape match what the block claims.

Drift / future-proofing

The block depends on vercel-labs/agent-skills continuing to publish a skill named deploy-to-vercel. If we ship a CI job that validates the README install commands against APM regularly, any drift would surface immediately. Not in scope for this PR; flagged for follow-up if the panel wants it.

[Copilot]

Pull request overview

Adds a small conversion-oriented README callout for readers familiar with npx skills add, pointing them to equivalent apm install usage for SKILL_BUNDLE-style repos.

Changes:

• Insert a short "Coming from npx skills add?" block between the clone/install snippet and "The three promises" section.
• Add two concrete apm install examples (full bundle and --skill subset).
• Add a docs link intended to explain manifest/lockfile/reproducibility for skill bundles.

Show a summary per file

File	Description
README.md	Adds an npx skills add conversion block with example apm install commands and a link to package type docs.

Copilot's findings

• Files reviewed: 1/1 changed files
• Comments generated: 1

[Copilot]

The link fragment .../reference/package-types/#skill-bundle looks inconsistent with the docs page: docs/src/content/docs/reference/package-types.md has headings ## Skill bundle (SKILL.md at root) and ## Skill collection (skills//SKILL.md) (the latter is the SKILL_BUNDLE/npx-style layout). As written, #skill-bundle is likely not a valid anchor and also points readers at the wrong section. Suggest linking to the package-types page without a fragment, or update the fragment (and/or link text) to target the Skill collection / SKILL_BUNDLE section and verify it matches the rendered site slug.

Suggested change

	Same install gesture. You also get a [manifest, lockfile, and reproducibility](https://microsoft.github.io/apm/reference/package-types/#skill-bundle).
	Same install gesture. You also get a [manifest, lockfile, and reproducibility](https://microsoft.github.io/apm/reference/package-types/).

[danielmeppiel]

Thanks @copilot-pull-request-reviewer -- two real issues caught in one comment.

Pushed 42d7aa76 dropping the fragment entirely and linking to the page root https://microsoft.github.io/apm/reference/package-types/. Reasoning:

1. Wrong anchor slug. Verified against the deployed page: only #skill-bundle-skillmd-at-root exists; #skill-bundle is not a valid anchor.
2. Wrong heading semantically. That SKILL.md-at-root heading is the single-skill bundle shape, but npx skills add's layout is the multi-skill skills/<name>/SKILL.md layout, documented under "Skill collection" further down the same page.
3. Source has the right anchor, but it isn't deployed yet. "Skill collection" landed in 0.9.4 source; the v0.9.4 docs auto-deploy (from fix(ci): deploy docs after bot-cut releases via workflow_call #953) is mid-rollout, so the README has to work against the live site, not the in-flight one.

Linking to the page root is robust today (lands on the right doc, both shapes visible above the fold) and self-correcting once 0.9.4 docs deploy completes.

[danielmeppiel]

Update: v0.9.4 docs are now live. The deploy was actually broken in a workflow gate (the skip we saw was not just lag) -- root cause + fix in #981.

Manually triggered workflow_dispatch run 24983311706 succeeded; live site now exposes the precise anchor:

$ curl -s https://microsoft.github.io/apm/reference/package-types/ | grep -oE 'id="skill[^"]*"'
id="skill-bundle-skillmd-at-root"
id="skill-collection-skillsnameskillmd"

Restored the precise fragment in 14e60ac0 so the README lands readers exactly on the "Skill collection (skills/<name>/SKILL.md)" heading -- the layout npx skills users already know -- instead of the page root.

So this PR now ships with both the live docs and the right anchor. Conversion funnel from npx-skills users -> APM lands on the heading that matches their existing layout, not on a page they have to scan.