# Skill-indexer — and an open question about how AI agent skills should be distributed **URL:** \ **Category:** Discussions\ **Tags:** skills\ **Created:** [May 19, 2026, 10:30am UTC](https://forum.cursor.com/t/skill-indexer-and-an-open-question-about-how-ai-agent-skills-should-be-distributed/160999 "2026-05-19T10:30:48Z")\ **Posts on this page:** 3\ **Page:** 1
**Author:** ![hyminghan](https://avatars.discourse-cdn.com/v4/letter/h/5fc32e/32.png) [@hyminghan](https://forum.cursor.com/u/hyminghan)\ **Post date:** [May 19, 2026, 10:30am UTC](https://forum.cursor.com/t/skill-indexer-and-an-open-question-about-how-ai-agent-skills-should-be-distributed/160999/1 "2026-05-19T10:30:48Z")
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. 1. Is npm even the right distribution substrate? The alternative — a dedicated registry like [agentskills.io](http://agentskills.io) — gives stronger curation but loses npm’s version pinning, lockfiles, and audit pipeline. What’s actually right? 2. 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. 3. 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: > **[GitHub - hymhub/skill-indexer: Zero-config CLI that scans your npm dependencies...](https://github.com/hymhub/skill-indexer)** > > Zero-config CLI that scans your npm dependencies for SKILL.md directories, validates them, and installs them into Cursor / Codex / Claude / Copilot / Amp / OpenCode / Goose skill folders. I’d genuinely love to hear “you’re wrong because…” — that’s what’ll shape 0.2.0. ---
**Author:** ![deanrie](https://sea3.discourse-cdn.com/cursor1/user_avatar/forum.cursor.com/deanrie/32/1263_2.png) [@deanrie](https://forum.cursor.com/u/deanrie)\ **Post date:** [May 19, 2026, 12:53pm UTC](https://forum.cursor.com/t/skill-indexer-and-an-open-question-about-how-ai-agent-skills-should-be-distributed/160999/4 "2026-05-19T12:53:51Z")
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: 1. 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. 2. 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. 3. 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. Also, for Cursor specifically, it’s worth checking this thread about a parity gap between the IDE and the cursor-agent CLI for skills coming from plugins: [Cursor-agent CLI does not register skills from plugins (IDE does — parity gap)](https://forum.cursor.com/t/cursor-agent-cli-does-not-register-skills-from-plugins-ide-does-parity-gap/158947). If you plan to target both, they currently behave differently. ---
**Author:** ![system](https://sea3.discourse-cdn.com/cursor1/user_avatar/forum.cursor.com/system/32/99069_2.png) [@system](https://forum.cursor.com/u/system)\ **Post date:** [August 17, 2026, 12:54pm UTC](https://forum.cursor.com/t/skill-indexer-and-an-open-question-about-how-ai-agent-skills-should-be-distributed/160999/5 "2026-08-17T12:54:37Z")
This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.