Problem
Libraries have started shipping agent skills inside their npm packages so the skill content is versioned with the library (e.g. a component library shipping its migration/upgrade skills — the guides must match the installed version).
Today the only way to consume such a skill with dotagents is a path: source that hardcodes the node_modules layout:
[[skills]]
name = "ui-kit-upgrade"
source = "path:./node_modules/@acme/ui-kit/skills/ui-kit-upgrade"
This works, but:
- It hardcodes
node_modules, which is generally an antipattern: the layout isn't guaranteed (Yarn PnP has no node_modules at all; workspace hoisting can place the package in a parent directory; the config silently breaks in those setups).
- It leaks the package's internal file layout into every consumer's
agents.toml instead of resolving through the package name.
- A bare specifier like
@acme/ui-kit/skills/ui-kit-upgrade can't be used instead — it's parsed as GitHub owner/repo shorthand (stripLeadingAt → acme/ui-kit/...), so there's currently no package-aware form at all.
Proposed feature
An npm-aware source type that resolves through Node's module resolution (e.g. import.meta.resolve / require.resolve) rather than a literal path:
[[skills]]
name = "ui-kit-upgrade"
source = "npm:@acme/ui-kit"
path = "skills/ui-kit-upgrade"
Semantics:
- Resolve the installed package location via Node resolution from the project root (works with pnpm symlinks, hoisting, and PnP).
- Treat it like a local source otherwise: copy on
install, refresh on every run (this already gives a great property — the skill auto-updates whenever the dependency is updated, staying version-coupled with zero extra pinning, since the package manager's lockfile is the pin).
agents.lock could record the resolved package version for provenance.
Why this fits dotagents
Shipping skills alongside the code they describe is a natural pattern for library authors (migration guides, API usage skills), and dotagents is already the nicest way to surface skills into agent tools. A first-class npm: source would make dotagents the missing consumer-side half of that pattern without every team hand-writing node_modules paths.
Current workaround
path:./node_modules/<pkg>/<skill-dir> — functional in npm/pnpm layouts, broken under Yarn PnP, and layout-leaking.
Happy to provide more detail — we're using this pattern in production with an internal design-system package and its consumer apps.
Problem
Libraries have started shipping agent skills inside their npm packages so the skill content is versioned with the library (e.g. a component library shipping its migration/upgrade skills — the guides must match the installed version).
Today the only way to consume such a skill with dotagents is a
path:source that hardcodes thenode_moduleslayout:This works, but:
node_modules, which is generally an antipattern: the layout isn't guaranteed (Yarn PnP has nonode_modulesat all; workspace hoisting can place the package in a parent directory; the config silently breaks in those setups).agents.tomlinstead of resolving through the package name.@acme/ui-kit/skills/ui-kit-upgradecan't be used instead — it's parsed as GitHubowner/reposhorthand (stripLeadingAt→acme/ui-kit/...), so there's currently no package-aware form at all.Proposed feature
An npm-aware source type that resolves through Node's module resolution (e.g.
import.meta.resolve/require.resolve) rather than a literal path:Semantics:
install, refresh on every run (this already gives a great property — the skill auto-updates whenever the dependency is updated, staying version-coupled with zero extra pinning, since the package manager's lockfile is the pin).agents.lockcould record the resolved package version for provenance.Why this fits dotagents
Shipping skills alongside the code they describe is a natural pattern for library authors (migration guides, API usage skills), and dotagents is already the nicest way to surface skills into agent tools. A first-class
npm:source would make dotagents the missing consumer-side half of that pattern without every team hand-writingnode_modulespaths.Current workaround
path:./node_modules/<pkg>/<skill-dir>— functional in npm/pnpm layouts, broken under Yarn PnP, and layout-leaking.Happy to provide more detail — we're using this pattern in production with an internal design-system package and its consumer apps.