[FEATURE] Skills install syntax support having compatibility with that of Vercel

[lirantal]

Is your feature request related to a problem? Please describe.
Support skill install syntax similar to that of Vercel skills npx package

Describe the solution you'd like
Example:

npx skills add https://github.com/anthropics/skills --skill frontend-design

As you can see, it uses a --skill flag, unlike currently in apm which requires a full directory part in the git repo. It also accepts the github URL syntax (https://github.com/) instead of only owner/repo format.

Describe alternatives you've considered
It would be a nice DX to be able to swap between Vercel skills and that of apm easily.

[sergio-sisternes-epam]

Thanks for the suggestion, @lirantal!

Regarding the --skill flag — APM already supports subdirectory targeting natively. You can install a specific skill from a multi-skill repo by appending the path:

# Install a specific skill from a repo
apm install anthropics/skills/frontend-design

So there's no need for a separate --skill flag — the path-based syntax is more flexible and already works today.

As for accepting full GitHub URLs (https://github.com/owner/repo) as input, that's a great DX improvement and is being tracked as part of the broader URL-based install design in #692 (design hub: #676).

Keeping this open and cross-referencing #692 for the URL parsing piece.

[lirantal]

I think you misunderstood in me in the first part. I want to be able to provide a --skill <skill-name> flag so that I can easily switch between skills cli and apm cli :)

Once apm also support for URLs both will be easy to just use interchangeably

[github-actions]

Triage decision

needs-design

Proposed labels

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

Milestone

null

Suggested next action

Clarify the --skill flag semantic (how does it map to APM's directory-based install model?) and whether URL normalization alone would cover the primary use case.

Suggested issue comment

Thanks for filing this, `@lirantal`! This is a valid DX interoperability request -- supporting `https://github.com/` URL syntax alongside `owner/repo` is straightforward, and the Vercel compatibility angle is a useful framing.

Before this can land, two things need clarification:

1. **`--skill` flag semantic**: In Vercel's model, `--skill frontend-design` selects a subdirectory by name. In APM, skill location within a repo is already part of the `owner/repo/path` install syntax. How should `--skill frontend-design` map when the repo has multiple skills at different paths? Should it match by directory name, by manifest name, or by a dedicated metadata field?

2. **Scope**: Would URL normalization alone (`https://github.com/owner/repo` -> `owner/repo`) cover your immediate use case, or is the `--skill` flag itself the key need?

If you can share a concrete example of a Vercel skill install command that you want to translate directly to APM, that would help define the design quickly.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

Two distinct asks in one issue: (1) URL syntax normalization (https://github.com/owner/repo -> owner/repo), which is trivially addable and non-controversial, and (2) a --skill flag to select a specific skill within a repo, which requires design. The Vercel CLI uses --skill frontend-design to select by name, but APM uses owner/repo/path/to/skill for sub-path installs. The flag semantic (select by dir name? manifest name?) is undefined and the two models are not directly compatible.

Supply Chain Security Expert -- Risk-Surface Reviewer

URL input in apm install is an existing surface handled by path_security.py. The --skill flag value would be used to construct a path, which must go through validate_path_segments() to prevent traversal. No new critical security concern, but the path-construction logic for --skill must be explicitly designed with the security guardrails in mind.

OSS Growth Hacker -- Contributor-Tone Reviewer

lirantal has author_association=NONE on microsoft/apm, activating this lens. The contributor is well-known in the OSS/security community. The reply should be warm and technically specific, not dismissive. Ask for the concrete use-case example (a real Vercel skill install command they want to replicate) to make the design conversation efficient. Acknowledge the interoperability angle is valuable for the APM positioning story.

Python Architect -- Architecture Reviewer

The two asks should be separated: URL normalization is a small string-processing addition to the install argument parser; the --skill flag is a new CLI parameter that changes how APM resolves the install path. The --skill flag would require changes in cli.py (new option), the install pipeline (path resolution from flag value to actual subdirectory), and test coverage. Cross-cutting enough to warrant a design comment before code lands.

Doc Writer -- Documentation Reviewer

A new --skill flag and URL syntax support would need entries in the CLI reference (cli-commands.md) and the installation guide. area/docs-site as a secondary label ensures the implementing PR is reminded to update docs. The issue itself is well-scoped for a feature-request body but thin on examples -- the suggested reply asks for one.

APM CEO -- Triage Arbiter

Interoperability with Vercel's skill CLI is strategically interesting -- it lowers the switching cost for teams already using Vercel skills. But the --skill flag semantic must be pinned before code lands, or we risk an awkward divergence from both Vercel's model and APM's own owner/repo/path convention. URL normalization can land independently and quickly; --skill needs a design comment. needs-design overall with a clear ask for the use-case example.

{
  "decision": "needs-design",
  "decision_detail": "The --skill flag semantic (path selection within a repo) must be defined before implementation. URL normalization alone is trivially feasible and could land separately.",
  "theme": "theme/portability",
  "areas": ["area/cli", "area/docs-site"],
  "type": "type/feature",
  "status": "status/needs-design",
  "priority": null,
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Clarify the --skill flag semantic and whether URL normalization alone covers the primary use case; provide a concrete Vercel-to-APM translation example.",
  "comment_markdown": "Thanks for filing this, `@lirantal`! This is a valid DX interoperability request -- supporting `https://github.com/` URL syntax alongside `owner/repo` is straightforward, and the Vercel compatibility angle is a useful framing.\n\nBefore this can land, two things need clarification:\n\n1. **`--skill` flag semantic**: In Vercel's model, `--skill frontend-design` selects a subdirectory by name. In APM, skill location within a repo is already part of the `owner/repo/path` install syntax. How should `--skill frontend-design` map when the repo has multiple skills at different paths? Should it match by directory name, by manifest name, or by a dedicated metadata field?\n\n2. **Scope**: Would URL normalization alone (`https://github.com/owner/repo` -> `owner/repo`) cover your immediate use case, or is the `--skill` flag itself the key need?\n\nIf you can share a concrete example of a Vercel skill install command that you want to translate directly to APM, that would help define the design quickly."
}

---

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 · ● 2.2M · ◷

[danielmeppiel]

@lirantal shipped in PR #974 and live in v0.9.4