Clarify or make additive --skill behavior when installing from existing skill bundles

[lirantal]

Summary

When installing a subset of skills from the same skill-bundle dependency, apm install --skill ... appears to replace the previously configured skill subset instead of adding to it. This is surprising for an install command and makes the workflow for incrementally adding skills confusing.

Reproduction

Start with a user-scope install of one skill from a bundle:

apm install -g --target agent-skills lirantal/skills --skill gh-bulk-repo-edit

This installs the skill and writes a user-scope dependency entry similar to:

dependencies:
  apm:
    - git: lirantal/skills
      skills:
        - gh-bulk-repo-edit

Then try to add another skill from the same dependency:

apm install -g --target agent-skills lirantal/skills --skill gh-repo-init-context

The resulting ~/.apm/apm.yml replaces the previous subset:

dependencies:
  apm:
    - git: lirantal/skills
      skills:
        - gh-repo-init-context

APM then treats the previously installed skill as stale and attempts to clean it up.

Why this is confusing

From a user perspective, apm install <package> --skill <skill-name> reads like "install this additional skill from this package", especially when the package is already configured.

Instead, the current behavior is closer to "set the exact selected skill subset for this package to only these --skill values". That behavior is understandable once known, but it was not obvious from the CLI flow.

This was especially confusing in user scope with the agent-skills target because the first command successfully created:

~/.agents/skills/gh-bulk-repo-edit/

Then the second command updated ~/.apm/apm.yml to the new skill only and cleaned the old skill as stale.

Workaround

To keep both skills, the user must pass all desired skill selections every time:

apm install -g --target agent-skills lirantal/skills \
  --skill gh-bulk-repo-edit \
  --skill gh-repo-init-context

Or edit ~/.apm/apm.yml manually so the dependency has the full desired subset, then run:

apm install -g --target agent-skills

If the dependency is floating on a branch and the new skill exists only on a newer commit, the user may also need:

apm install -g --target agent-skills --update

Suggested friendlier behavior

I think one of these would be much easier to understand:

1. Make repeated apm install <existing-package> --skill <new-skill> additive by default, merging the new skill into the existing skills: list.

2. If replacement is intentional, print an explicit warning before changing the subset, for example:

   [!] Replacing selected skills for lirantal/skills:
       previous: gh-bulk-repo-edit
       new: gh-repo-init-context
       To keep both, pass both --skill flags or edit ~/.apm/apm.yml.
   

3. Add explicit flags so intent is unambiguous:

   apm install ... --skill gh-repo-init-context          # additive
   apm install ... --only-skill gh-repo-init-context     # replacement / exact subset
   apm install ... --remove-skill gh-bulk-repo-edit      # removal

At minimum, the help text for --skill could say that it sets/replaces the package's selected skill subset.

Related observation

In the same flow, --refresh still installed from the cached resolved commit:

[+] lirantal/skills @8f088042 (cached)

The user had to reason separately about --update versus --refresh. That may be working as designed, but it compounded the confusion because the config listed two skills while only one appeared in ~/.agents/skills/.

[github-actions]

Triage decision

needs-design

Proposed labels

area/cli
area/docs-site
type/feature
status/needs-design

Milestone

null

Suggested next action

Maintainer should post a design decision comment choosing among: (1) additive --skill by default, (2) warning before replacement, or (3) new explicit --only-skill / --remove-skill flags -- then tag as status/accepted and link the chosen design here.

Suggested issue comment

Thanks for this thorough writeup, `@lirantal` -- the reproduction steps, the workaround, and the three concrete proposals make this very actionable.

You have correctly identified that the current `--skill` behavior (replacement of the skill subset) diverges from the "install adds" mental model that `npm install`, `pip install`, and `cargo add` all follow. The confusion is real and we agree it should be resolved.

There are three viable paths (as you laid out):

1. Make `apm install --skill <name>` additive by default (merges into the existing `skills:` list).
2. Print an explicit warning before replacing the subset, so the user can abort or adjust.
3. Add `--only-skill` (replacement/exact subset) and `--remove-skill` (removal) so intent is always unambiguous.

Each option has different implications for how users manage skill state over time, so we want to make an intentional design call before implementation. We will post a design decision here and update the status to `status/accepted` once that call is made.

In the meantime, the workaround you documented (pass all desired `--skill` flags in one command, or edit `~/.apm/apm.yml` directly) is the correct approach.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

Genuine UX friction against the "install adds, never silently mutates" principle. In every major package manager ecosystem (npm install, pip install, cargo add), install is additive. The current behavior -- where apm install --skill X replaces the entire skill subset -- violates this universal expectation. The author's three proposed options are well-reasoned. Option 3 (explicit --only-skill / --remove-skill flags) is the cleanest ergonomically because it makes intent unambiguous without relying on flag combinations. However, the choice between options has downstream UX implications (discoverability, help text, mental model alignment) and requires a design decision before implementation.

Supply Chain Security Expert -- Risk-Surface Reviewer

No risk-surface implication. The issue concerns how the skills: list in apm.yml is updated when --skill is passed; no lockfile integrity, no auth surface, no package provenance path is affected by making the update additive vs. replacement. The skill subset is a user-controlled config value, not a security boundary.

OSS Growth Hacker -- Contributor-Tone Reviewer

lirantal has author_association: NONE but submitted an extremely detailed, well-structured issue (reproduction, analysis, workaround, three concrete proposals). The reply validates the thoroughness, gives a clear "here is what happens next" signal (design decision before implementation), and explicitly acknowledges the workaround documentation which other users will benefit from. The design gate should not feel like a soft rejection; the tone makes it clear this is a quality gate and the issue is accepted in principle.

Python Architect -- Architecture Reviewer

Making --skill additive has non-trivial implications for the install state machine. The current replacement model is declarative: the user states the desired exact subset each time, and APM makes it so. An additive model introduces drift risk between the manifest and the user's intent over repeated installs, and requires an explicit removal mechanism (--remove-skill or a separate apm uninstall --skill). Option 3 (explicit flags) resolves this cleanly by making intent explicit at call time and preserving the declarative model for --only-skill. The design decision must address: what is the removal path? how does this compose with apm.yml direct edits? A maintainer comment choosing one option is the correct gate before a PR lands; this should not land as status/accepted without it.

Doc Writer -- Documentation Reviewer

Any of the three proposed solutions will require docs/src/content/docs/reference/cli-commands.md and the install guide to be updated. Option 3 (new flags) requires the most doc work: new flag descriptions, updated examples, and a note on the semantic difference between --skill and --only-skill. area/docs-site rides as a secondary label to remind the implementing PR author. The suggested comment wording is grounded in the existing apm install help text and avoids framing the issue as "won't fix".

APM CEO -- Triage Arbiter

This is a legitimate UX complaint against a real violation of the "install adds, never silently mutates" principle that APM holds as a core mental model invariant. The author's research is thorough and their three proposals are all viable. The needs-design call is not a deferral -- it is the correct next step because the replacement vs. additive model choice has downstream implications for how users manage skill state. The Python Architect correctly identifies that an additive model needs an explicit removal path. The maintainer's design comment should be made promptly; this is not a hard problem, it just needs a deliberate answer. No theme/* label is applied: this is pure CLI surface with no portability, security, or governance product surface implication. No milestone because needs-design is milestone-free per label-set policy.

{
  "decision": "needs-design",
  "decision_detail": "Three viable options presented (additive default, warning before replacement, explicit flags); maintainer must choose before implementation to avoid introducing worse UX or state-management issues.",
  "theme": null,
  "areas": ["area/cli", "area/docs-site"],
  "type": "type/feature",
  "status": "status/needs-design",
  "priority": null,
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Maintainer should post a design decision comment choosing among the three proposed options, then update the issue to status/accepted.",
  "comment_markdown": "Thanks for this thorough writeup, `@lirantal` -- the reproduction steps, the workaround, and the three concrete proposals make this very actionable.\n\nYou have correctly identified that the current `--skill` behavior (replacement of the skill subset) diverges from the \"install adds\" mental model that `npm install`, `pip install`, and `cargo add` all follow. The confusion is real and we agree it should be resolved.\n\nThere are three viable paths (as you laid out):\n\n1. Make `apm install --skill <name>` additive by default (merges into the existing `skills:` list).\n2. Print an explicit warning before replacing the subset, so the user can abort or adjust.\n3. Add `--only-skill` (replacement/exact subset) and `--remove-skill` (removal) so intent is always unambiguous.\n\nEach option has different implications for how users manage skill state over time, so we want to make an intentional design call before implementation. We will post a design decision here and update the status to `status/accepted` once that call is made.\n\nIn the meantime, the workaround you documented (pass all desired `--skill` flags in one command, or edit `~/.apm/apm.yml` directly) is the correct approach."
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · sonnet46 3.3M · ◷