From 40fcf03ac30993b380ef535259830a1f572d400b Mon Sep 17 00:00:00 2001 From: GitHub Copilot Date: Sat, 4 Apr 2026 03:31:23 +0000 Subject: [PATCH] docs: document native skill collision warning from #545 - Add CHANGELOG.md entry under [Unreleased] Fixed for the new cross-package native skill name collision warning - Add 'Skill Name Collision Warning' troubleshooting section in docs/src/content/docs/guides/skills.md explaining the warning message and how to resolve the conflict Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- CHANGELOG.md | 1 + docs/src/content/docs/guides/skills.md | 15 +++++++++++++++ 2 files changed, 16 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index fbf9630e7..141339495 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Standardized `--target` choices, replaced Unicode with ASCII for cp1252 compatibility, and documented missing CLI flags (#519) - `apm install -g` now correctly deploys to user-scope directories, skips unsupported primitives, and cleans up on uninstall -- including multi-level paths like `~/.config/opencode/` (#542) - `apm deps update` now correctly re-resolves transitive dependencies instead of reusing stale locked SHAs (#548) +- `apm install` now warns when two packages deploy a native skill with the same name, identifying both the incoming and previous owner so users know which dependency to remove (#545) ### Added diff --git a/docs/src/content/docs/guides/skills.md b/docs/src/content/docs/guides/skills.md index 9cdb59ecb..829db13f3 100644 --- a/docs/src/content/docs/guides/skills.md +++ b/docs/src/content/docs/guides/skills.md @@ -376,6 +376,21 @@ If you see a skill name validation warning: 1. **Check naming:** Names must be lowercase, 1-64 chars, hyphens only (no underscores) 2. **Auto-normalization:** APM automatically normalizes invalid names when possible +### Skill Name Collision Warning + +If you see a warning like: + +``` +[!] Skill 'humanizer': replaced 'org/other-package' -- remove one package to avoid this +``` + +Two of your installed packages deploy a native skill with the same name. The second install +overwrote the first. To resolve: + +1. **Identify the conflict**: The warning names both the incoming package and the previous owner. +2. **Remove one**: Uninstall the package you no longer need with `apm uninstall owner/repo`. +3. **Reinstall**: Run `apm install` again to restore a clean state. + ### Metadata Missing If skill lacks APM metadata: