Support declaring skill locations beyond the top-level skills/ directory

[johannespfrang-h-d]

Contribution

• I'd be willing to implement this feature (contributing guide)

Describe the user story

Agent Skills sometimes ship inside repositories whose primary purpose is something else, and whose root layout is already taken. A concrete example: the official glab skill lives in gitlab-org/cli at

internal/commands/skills/bundled/assets/glab/SKILL.md

The Agent Skills spec allows SKILL.md anywhere in a package, but pnpm only discovers skills under the package's top-level skills/ directory (plus category subpaths, up to three levels). So this perfectly valid, upstream-maintained skill is invisible to pnpm approve, while other skill tools that accept a subpath install it fine.

Verified on pnpm 12.17.0: a git dependency whose skill sits at a nested path installs cleanly but is never offered for approval; move the identical SKILL.md under skills/ and it's detected immediately. Upstreams like GitLab aren't going to restructure a Go CLI's source tree to satisfy an npm-package convention they don't otherwise use — and consumers fall back to vendoring copies, which loses exactly the provenance and lockfile pinning that make pnpm-managed skills worth using.

Describe the solution you'd like

Akin to @vercel-labs/skills, a client-side solution. One of three options:

A. Path-scoped entries in the existing permissions.skills list

permissions.<pkg>.skills currently takes true | false | [names], where names are directories under skills/. Extend it: an entry containing / is treated as a path (glob allowed) inside the package, and pnpm scans exactly there — requiring SKILL.md to exist at that path:

permissions:
  "@gitlab-org/cli@git+https://gitlab.com/gitlab-org/cli.git":
    skills:
      - internal/commands/skills/bundled/assets/glab

• No new setting; it composes with the repo-level approval key that already spans commits.
• Links land as glab (basename of the skill directory), collision rules unchanged.
• Pinned in a reviewed file (pnpm-workspace.yaml), covering content the lockfile integrity already pins.

B. Consumer-declared discovery map (variant of A)

Keep approval and discovery separate: a skills.paths map keyed by package matcher, next to skills.dirs:

skills:
  paths:
    "@gitlab-org/cli": ["internal/commands/skills/bundled/assets/*"]

C. Implement npm's ::path: git fragment, with a root-level skill scan for path-selected packages

npm already supports selecting a subdirectory of a git repo as the package root (npm-package-arg#91):

gitlab:gitlab-org/cli#v1.124.0::path:internal/commands/skills/bundled/assets

pnpm parses git specs with a fork of npm-package-arg, so the fragment grammar is already understood at the boundary — but the subdirectory is not honored on fetch. Today, any colon in the fragment makes resolution fail outright:

Could not resolve main:nested to a commit of …

(verified on pnpm 12.17.0; npm 11 extracts the subdirectory and reads its package.json)

The proposal has two halves.

1. Core: implement gitSubdir end-to-end — fetch the subdirectory as the package root, and keep the ::path: selector intact through committish resolution and in the lockfile.

2. Skills, one small rule: when a package was fetched via a consumer-chosen ::path: fragment, the subdirectory root is itself a skills root — directories directly under it containing SKILL.md are discovered as skills, alongside the existing skills/ scan.

With both, glab installs and links as if it had been built for pnpm:

• gitlab:gitlab-org/cli#v1.124.0::path:internal/commands/skills/bundled/assets
• package root = that assets/ directory, which directly contains glab/SKILL.md → discovered, no dependency on where an ancestor happens to be named skills/
• approved by the existing repo-level permissions key, pinned by the existing lockfile integrity, linked as glab

The root-scan rule is deliberately narrower than it sounds: it activates only for packages whose spec carries an explicit ::path: — i.e. the consumer already declared "this exact directory is what I want installed", which is a stronger, more reviewable signal than any post-hoc path list. Packages without the fragment keep today's behavior verbatim.

This is still mostly a compatibility gap being closed, not a skills feature being invented: a whole class of "valid skill, wrong layout" repos becomes installable, and pnpm gains git-subdir dependencies for any use, skills or not.

Describe the drawbacks of your solution

A. Path-scoped entries in permissions.skills

• Syntax overload. Distinguishing a skill name from a path by the presence of / is a silent semantic switch. It collides with the existing category layout: engineering/glab is already expressible today as a discovered category path — is that an approval for a discovered skill, or a directive to scan a new location? Ambiguity in a security-relevant field is a bad trade.
• Discovery smuggled into a decision field. permissions records verdicts; this makes it also encode where to look. Consequences are visible in tooling: pnpm approve writes entries programmatically, and generated name-entries would be indistinguishable from hand-written path-entries — bad for review clarity, bad for revocation semantics ("a skill not in the list is never offered again" gets weird when the list mixes names and globs).
• The manifest-less wart shows through. Installing gitlab-org/cli still derives its name from the host (@gitlab-org/cli), and the permissions key must match that derived name — an artifact of pnpm's fallback, not anything upstream declared. Host mirrors or owner renames silently orphan the approval.
• Still full-tree fetch. The entire CLI repo lands in node_modules for one Markdown file; the path only selects what to scan, not what to download.

B. Consumer-declared discovery map

• Everything A's downsides have, plus a second key grammar. Discovery is decoupled from approval, so using it requires the matcher to appear in two places (skills.paths + permissions), and the two grammars differ: permissions needs the name@git+url repo form (a bare name does not match a git dependency — verified), while the map keys on a plain name. Name-only keying also drops provenance: it can't express which @gitlab-org/cli source, and cloning the repo elsewhere is a different trust decision with the same key.
• Undefined states multiply. A path configured for a package that's not installed; a package approved skills: false but present in skills.paths; a discovered path the approval list doesn't cover. Each pair needs a defined precedence, or pnpm approve starts nagging on every install.
• Looks like an approval bypass. A discovery setting that exists outside permissions reads exactly like "configure paths, get skills, no approval" to a reviewer — even if the approval still gates linking. A is worse on paper for trust but has fewer such states because there's only one gate to configure.

C. npm's ::path: git fragment

• It's dependency-resolution work wearing a skills ticket. Fetching a subdirectory as package root touches the tarball/git fetchers, store keys, the lockfile's resolved-spec serialization, and virtual-store naming. That is a much bigger review surface than A/B — and a bigger win, but reviewers should expect it to land as a core feature with a skills use case, not the reverse.
• The resolved-spec bug class comes with it. npm's pacote shipped a bug where resolving a branch/tag spec to a sha silently dropped ::path:, installing the repo root under an unchanged dependency entry (npm/pacote#513). For skills, the silent-wrong-content version of that bug means instructions changing under an approval nobody re-granted. Mitigable — test that ::path: round-trips through resolution, which is exactly what npm had to learn — but it's a regression pnpm would have to avoid by contract.
• The npm-compat fork in the road. npm's semantics expect a package.json inside the selected subdirectory; glab has none anywhere in the tree. Implement npm's strictness and the motivating example stays broken; extend pnpm's existing manifest-less fallback (derived @owner/repo names) to subdirs and git specs in package.json grow a pnpm-only dialect npm rejects. Either outcome is a deliberate spec decision that belongs in the docs, not an implementation detail.
• Approval keys bind to a derived name. For a manifest-less subdirectory, the package name — and thus the name@git+url approval key — comes from pnpm's host-derived fallback. It's an artifact no author declared: owner renames, host mirrors, or later adding a manifest with a different name silently orphans (or re-targets) the approval. Pre-existing in the manifest-less fallback, but C is the first feature to lean on it as a happy path.
• Two scan modes must now coexist. Root-scan (path-selected packages) vs. skills/-only (everything else), plus their interactions: category rules at a root that is already the skills root, collision naming, and stray SKILL.md fixtures a repo keeps at its root becoming discoverable skills. The activation condition is clean, but the rule is one more branch in the discovery story, and it's skills-feature work after all — C is not "zero skills changes."
• One path per dependency. Two skills in unrelated subdirectories mean two aliased dependency entries for the same repo (glab-skills@…::path:…, xyz@…::path:…), with two lockfile entries for one repository. A/B take lists within one dependency.
• Every consumer edits package.json. The path lives in the dependency spec, so path churn (upstream moves the directory) dirties manifests and lockfiles across all consumers — whereas A/B confine that maintenance to the workspace policy file.
• Consumer-side trust, same as A and B. Let's not oversell: C packages the choice as npm compatibility, but the directory is still consumer-chosen rather than author-designated. It dodges the syntax objections to A/B, not the philosophical one. If that objection is the real blocker, only the author-side manifest field resolves it — and it composes with C: author-declares beats consumer-selects.

Describe alternatives you've considered

Author-declared paths like:

{
  "name": "@glab/cli",
  "skills": ["internal/commands/skills/bundled/assets/*"]
}

Needs buy-in from the skill authors, which is more work, but might be a much cleaner solution in the long term.

[zkochan]

This already works with pnpm's own git subdirectory syntax. pnpm uses #path: (or &path: combined with a ref), not npm's ::path::

pnpm add 'gitlab:gitlab-org/cli#v1.124.0&path:/internal/commands'

permissions:
  "@gitlab-org/cli@git+https://gitlab.com/gitlab-org/cli.git":
    skills: true

Verified on pnpm 12.19.0. The install reports the package as awaiting approval. After approval, glab and glab-stack are linked into the agent skill directories.

Why it works: with internal/commands as the package root, the skills sit at skills/bundled/assets/<name>/SKILL.md. pnpm searches up to three levels below skills/, so they are found. The lockfile keeps the selector in both the resolved version and resolution.path, so it survives resolving the tag to a commit. Only the selected subdirectory is stored.

On the options:

• A and B: I'd rather not. As you noted, they put discovery into the approval setting, or add a second matcher next to it.
• C: the core half already exists under pnpm's syntax. Accepting npm's ::path: spelling would be a separate compatibility change, and skills don't need it.

The case this doesn't cover is a repo whose skills have no ancestor directory named skills/, or sit more than three levels below one. If you have a real repository like that, please share it. A narrow fix would be to also look for skills directly under the root selected by path:. An author-declared skills field in package.json is a separate idea, and it wouldn't help glab, which has no manifest.

---

Written by an agent (Claude Code, claude-opus-5-5).

[zkochan]

Follow-up: #17976 makes pnpm accept the npm spelling too, so gitlab:gitlab-org/cli#v1.124.0::path:internal/commands works as written. It covers only the :: separator. Skill discovery is unchanged, as described above.

---

Written by an agent (Claude Code, claude-opus-5-5).