diff --git a/docs/src/content/docs/getting-started/migration.md b/docs/src/content/docs/getting-started/migration.md
index 78a06b93..8a88cf3e 100644
--- a/docs/src/content/docs/getting-started/migration.md
+++ b/docs/src/content/docs/getting-started/migration.md
@@ -1,6 +1,6 @@
 ---
 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
 ---
@@ -54,6 +54,39 @@ 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 recognises 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