diff --git a/docs/src/content/docs/getting-started/migration.md b/docs/src/content/docs/getting-started/migration.md
index 78a06b93b..403c20a0d 100644
--- a/docs/src/content/docs/getting-started/migration.md
+++ b/docs/src/content/docs/getting-started/migration.md
@@ -1,11 +1,11 @@
 ---
 title: "Existing Projects"
-description: "Add APM to a project that already has AI agent configuration."
+description: "Add APM to a project that already has AI agent configuration, or migrate from npx skills add."
 sidebar:
   order: 5
 ---
 
-APM is additive. It never deletes, overwrites, or modifies your existing configuration files. Your current `.github/copilot-instructions.md`, `AGENTS.md`, `.claude/` config, `.cursor-rules` — all stay exactly where they are, untouched.
+APM is additive. It never deletes, overwrites, or modifies your existing configuration files. Your current `.github/copilot-instructions.md`, `AGENTS.md`, `.claude/` config, `.cursor-rules` -- all stay exactly where they are, untouched.
 
 ## Add APM in three steps
 
@@ -54,9 +54,42 @@ If you decide APM is not for you:
 
 No uninstall script, no cleanup command. Zero risk.
 
+## Coming from `npx skills add`
+
+APM is a drop-in replacement. The install gesture is identical, and you also
+get a manifest, lockfile, and reproducible installs across machines.
+
+```bash
+# Install a whole skill bundle (equivalent to: npx skills add vercel-labs/agent-skills)
+apm install vercel-labs/agent-skills
+
+# Install a single skill from a bundle and persist the selection to apm.yml
+apm install vercel-labs/agent-skills --skill deploy-to-vercel
+
+# Subsequent bare apm install respects the persisted selection
+apm install
+```
+
+The `--skill` flag is repeatable. Your selection is written to `apm.yml` and
+`apm.lock.yaml` so the exact subset is reproducible on every machine.
+
+```bash
+# Pick two skills, then reset to all
+apm install vercel-labs/agent-skills --skill deploy-to-vercel --skill preview
+apm install vercel-labs/agent-skills --skill '*'   # back to full bundle
+```
+
+Any public repo that works with `npx skills add owner/repo` also works with
+`apm install owner/repo`. APM recognizes bare `skills/<name>/SKILL.md`
+layouts (the [agentskills.io](https://agentskills.io) convention) as a
+first-class package type; `apm.yml` is optional.
+
+See [Package Types](../../reference/package-types/#skill-collection-skillsnameskillmd) for the full
+skill collection layout reference.
+
 ## Next steps
 
-- [Quick start](../quick-start/) — first-time setup walkthrough
-- [Dependencies](../../guides/dependencies/) — managing external packages
-- [Manifest schema](../../reference/manifest-schema/) — full `apm.yml` reference
-- [CLI commands](../../reference/cli-commands/) — complete command reference
+- [Quick start](../quick-start/) -- first-time setup walkthrough
+- [Dependencies](../../guides/dependencies/) -- managing external packages
+- [Manifest schema](../../reference/manifest-schema/) -- full `apm.yml` reference
+- [CLI commands](../../reference/cli-commands/) -- complete command reference