From 9f715c8649ddc62713ad8582a8d99d02eb3116ae Mon Sep 17 00:00:00 2001 From: Daniel Meppiel <51440732+danielmeppiel@users.noreply.github.com> Date: Tue, 28 Apr 2026 15:15:35 +0200 Subject: [PATCH] docs: add 'Coming from npx skills add' migration section Add a dedicated section to the migration guide for users arriving from the npx skills add / agentskills.io ecosystem. Covers the drop-in install gesture, --skill flag for selective installs, and persistent selection across machines. This mirrors the README migration table added in v0.10.0 (#980) and brings the docs site to parity. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../content/docs/getting-started/migration.md | 35 ++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/docs/src/content/docs/getting-started/migration.md b/docs/src/content/docs/getting-started/migration.md index 78a06b93b..8a88cf3e1 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//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