Hi! I just open-sourced a small CLI called skill-indexer. The code
is the easy part; the reason I’m posting is to argue with you about
the design.
Background: every major AI coding assistant — Cursor, Codex, Claude
Code, Copilot, Amp, OpenCode, Goose — wants the same SKILL.md file
in its own folder. There is no shared answer to “how does an npm
library ship a SKILL.md to its consumers, across all of those tools,
without each tool inventing its own marketplace?”
skill-indexer is one attempt: scan node_modules, validate each
candidate’s frontmatter strictly, copy the valid ones into every
target tool’s project-local folder, write a manifest so clean is
safe.
But every interesting decision in there is unsettled.
Is npm even the right distribution substrate? The alternative — a
dedicated registry like agentskills.io — gives stronger curation
but loses npm’s version pinning, lockfiles, and audit pipeline.
What’s actually right?
Convention scan vs declarative agents.skills field. Convention
is zero-friction for library authors but risks pulling in
unrelated skills/ folders. Declarative is the opposite. We
currently support both; I keep wondering whether that’s principled
or just indecisive.
Strict SKILL.md frontmatter validation silently filters out
non-compliant candidates. That protects consumers from junk, but
it also gates experimental skills out of the ecosystem before
they’re polished. Where should the strict/lenient line sit?
Design rationale, comparison with npm-agentskills / sync-skills /
add-skill, code, and tests:
I’d genuinely love to hear “you’re wrong because…” — that’s what’ll
shape 0.2.0.
Hey, thanks for sharing. That’s an interesting angle on the problem.
On Cursor’s side, the official distribution mechanism is plugins: a directory with a .cursor-plugin/plugin.json manifest. Inside it you can include skills plus rules, hooks, MCP servers, and commands. So for Cursor, “how do I deliver SKILL.md to the consumer” becomes “package it as a plugin”. This doesn’t solve the cross-tooling issue you described, but it does solve it for the Cursor-only case and also gives you versioning and a manifest without relying on npm.
Quick answers to your questions:
npm vs a dedicated registry, IMO this isn’t either-or. npm gives you supply chain stuff like lockfiles, provenance, and audit. A dedicated registry gives curation and discovery. Most ecosystems end up with “packages in npm plus a separate index for discovery” like the VS Code marketplace on top of npm-style packaging. Giving up lockfiles just to get curation is expensive.
Convention plus declarative can both be fine as long as declarative clearly overrides convention. That’s the “convention over configuration, but configuration wins” pattern. It’s only indecisive if they can conflict without a clear priority.
Strict validation on install and lenient rules in dev is a standard split. An --experimental flag or a separate experimentalSkills field in the manifest gives authors runway without polluting the default path for consumers.