Multi-Surface npm Distribution Strategy

Evolving agentic-skills from a git-clone skill repository into a multi-surface distribution system via npm packages and a programmatic SDK — while preserving the markdown-first skill authoring model.

alignment_status: review generated: 2026-06-06 artifact: alignment/idea-scope-brief-npm-distribution.html

Current State Snapshot

Section feedback

298SKILL.md files

40Packs

9Global skills (Claude)

0npm packages published

Distribution is entirely git-clone-based. init.sh installs global skills to ~/.claude/skills/ and ~/.codex/skills/. scripts/pack.sh (1,164 lines of bash) manages project-local pack installs via file copies with .agentic-skills-managed markers. Versioning uses v0.MINOR decimal convention with archive/<version>/SKILL.md snapshots. Content-hash-based drift detection tracks staleness.

There is no package.json at repo root, no npm presence, and no programmatic API. The only npm usage is the test harness (vitest) and a Next.js showcase app.

Current Install Flow

# One-time setup
git clone agentic-skills && cd agentic-skills
./init.sh                                    # global skills → ~/.claude/skills/

# Per-project
cd ~/my-project
/path/to/agentic-skills/scripts/pack.sh install game code-quality
# Copies SKILL.md files into .claude/skills/ with managed markers
# Writes .agents/project.json with enabled_packs

What This Limits

No remote distribution — requires local git clone of the entire repo
No discoverability — users must know about the repo to find skills
No programmatic access — other tools cannot query or use skills without file-system access
Manual updates — git pull + refresh required to get new versions
Version pinning is local-only — no remote registry of available versions

Goals and Constraints

Section feedback

Must-Have Goals

npm distribution — users can install skills via npm without cloning the repo
Multi-surface reach — Claude Code, Codex, programmatic API
Agent-maintainable versioning — agents can bump versions and publish without human ceremony
User version selection — users can pin, lock, and update skill versions with standard tooling
Backward compatibility — existing git-clone + pack.sh users are not broken

Nice-to-Have Goals

npm search discoverability (users find packs via npm search)
Programmatic SDK for third-party integrations
Web-based skill browser / registry
Per-skill install granularity (install one skill without its whole pack)

Constraints

Skills must remain SKILL.md markdown files — no compilation or transpilation
Pack grouping must be preserved as the primary organizational unit
Dual-surface (Claude + Codex) skill mirrors must continue
Solo maintainer — publishing overhead must be automatable
.agents/project.json remains the project-level designation file

Invariants (All COAs)

Section feedback

These hold regardless of which COA is chosen:

Invariant	Detail
Skills are markdown	SKILL.md with YAML frontmatter (`name`, `description`, `version`, optional `type`, `argument-hint`, `invocation`) is the canonical format. No transpilation.
Pack grouping preserved	Named collections of domain skills remain the primary selection unit. Pack names survive.
Project designation file	`.agents/project.json` tracks `enabled_packs`, `pinned_versions`, `project_type`, and `skill_updates` in consumer repos.
Dual-surface mirrors	Skills supporting both Claude and Codex have `claude/` and `codex/` variants.
Archive-on-bump	`archive/<version>/SKILL.md` snapshots and per-skill `CHANGELOG.md` remain the versioning artifacts.
Global vs pack distinction	A small set of domain-neutral skills installs globally; packs install per-project.
Git-clone still works	`pack.sh` continues to function for users who prefer the local checkout model.

COA A: The Monolith

Section feedback

COA A One package ships everything Recommended

Philosophy: Maximum simplicity. One npm install, everything available. Optimize for speed to market and minimal publishing overhead.

Architecture

npm packages:
  agentic-skills              # Single package. CLI + all packs.

Layout inside the package:
  agentic-skills/
    package.json
    bin/agentic-skills.mjs     # CLI entry point
    src/cli/                   # CLI commands (install, remove, refresh, doctor)
    src/registry.mjs           # Pack/skill index builder
    global/claude/...          # Unchanged from current repo
    global/codex/...
    packs/...                  # All 40 packs, unchanged

Version Model

npm package follows semver: 1.0.0, 1.1.0, 2.0.0
Individual skill v0.x versions remain in SKILL.md frontmatter for pinning
An npm version bump aggregates all skill changes since last release
Agent workflow: edit SKILL.md → npx agentic-skills bump-skill <name> → archives, bumps, optionally triggers npm version patch

CLI Surface

npm install -g agentic-skills         # or use npx

agentic-skills install business-discovery game
agentic-skills list
agentic-skills status
agentic-skills doctor
agentic-skills refresh
agentic-skills pin devtool-adoption v0.0
agentic-skills init-global            # replaces ./init.sh
agentic-skills bump-skill <skill>     # agent-driven version bump

Migration Path

Add package.json at repo root
Port pack.sh core logic to Node.js CLI
Keep pack.sh as backward-compat wrapper that delegates to npx agentic-skills
Publish to npm

Timeline

Phase	Size	Duration	Deliverable
1	S	1–2 weeks	Add `package.json`, wire CLI as thin Node wrapper around `pack.sh`
2	M	2–4 weeks	Port `pack.sh` to Node.js, make bash a shim
3	S	1 week	Publish to npm, update docs

Best for: Solo maintainer who wants the fastest path to npm presence. Ideal if the primary audience is Claude Code / Codex users who already know about the project and just want an easier install.

COA B: The Federation

Section feedback

COA B Each pack is its own npm package

Philosophy: Ecosystem-native. Users install only what they need. Each pack has its own identity, version, and npm search presence.

Architecture

npm packages:
  @agentic-skills/cli                    # CLI coordinator
  @agentic-skills/core                   # Global skills
  @agentic-skills/business-discovery     # Pack package
  @agentic-skills/code-quality           # Pack package
  @agentic-skills/game                   # Pack package
  ... (~37 pack packages)

Monorepo layout (pnpm workspaces):
  agentic-skills/
    pnpm-workspace.yaml
    packages/
      cli/package.json          # @agentic-skills/cli
      core/package.json         # @agentic-skills/core
      packs/
        business-discovery/package.json
        game/package.json
        ...

Version Model

Each pack package has its own semver version, tracking changes to skills within that pack
@agentic-skills/cli versions independently (CLI features, not skill content)
Skill-level v0.x versions remain for pinning within a pack version
Agent workflow: edit SKILL.md → npx @agentic-skills/cli bump <pack> → bump pack package.json → npm publish for that one pack
Compatibility aliases (business → three packs) become meta-packages with peer dependencies

CLI Surface

npm install -g @agentic-skills/cli

agentic-skills init                      # install global skills
agentic-skills install business-discovery game
agentic-skills list
agentic-skills status
agentic-skills doctor
agentic-skills pin devtool-adoption v0.0
agentic-skills lock business-discovery@2.1.0  # lock pack npm version

Migration Path

Restructure repo into pnpm workspace with packages/ directory
Generate package.json for each pack (scripted from PACK.md)
Build @agentic-skills/cli as Node.js port of pack.sh
Publish core + first 10 packs, validate end-to-end
Publish remaining packs in waves

Timeline

Phase	Size	Duration	Deliverable
1	M	3–4 weeks	Restructure to pnpm workspace, build CLI
2	M	2–3 weeks	Publish `core` + first 10 packs
3	S	1–2 weeks	Publish remaining packs, add `pack.sh` shim
4	S	1 week	Docs, migration guide

Best for: Building an npm-native ecosystem where packs are independently discoverable and versionable. Ideal if you expect external contributors or want packs to have independent release cadences.

COA C: The Registry

Section feedback

COA C Skill registry + thin client

Philosophy: Skills are data, not code. Publish a registry and a thin client. Maximum granularity and multi-surface reach.

Architecture

npm packages:
  agentic-skills               # CLI + local manager
  @agentic-skills/registry     # Skill manifest + all SKILL.md files as data
  @agentic-skills/sdk          # Programmatic API for third-party tools

Registry structure:
  @agentic-skills/registry/
    skills.json                # Generated manifest: every skill with metadata
    packs.json                 # Pack definitions
    skills/                    # Flat directory of versioned SKILL.md files
      business-discovery--icp-interview--claude--v0.3.md
      game--playtest--claude--v0.0.md
      ...

Version Model

Each skill has its own semver version mapped from SKILL.md: v0.0 → 0.0.0, v0.1 → 0.1.0
The registry package (@agentic-skills/registry) versions on its own cadence; each publish is a new snapshot
skills.json manifest includes per-skill version, content hash, pack membership, and dependency info
Pinning at skill level: .agents/project.json → { "devtool-adoption": "0.0.0" }
Historical versions available via npm package version history

CLI Surface

npm install -g agentic-skills

agentic-skills init                      # install registry, set up cache
agentic-skills install game business-discovery
agentic-skills install-skill devtool-adoption  # single skill from any pack
agentic-skills pin devtool-adoption 0.0.0
agentic-skills update                    # show available updates
agentic-skills update --apply            # apply updates
agentic-skills search "code quality"
agentic-skills registry-build            # maintainer: regenerate skills.json
agentic-skills registry-publish          # maintainer: npm publish registry

SDK Surface

import { SkillRegistry } from '@agentic-skills/sdk'

const registry = new SkillRegistry()
const skill = await registry.getSkill('devtool-adoption')
const packs = await registry.listPacks()
const results = await registry.search('code quality')

Migration Path

Build registry generator (walks global/ and packs/, produces skills.json)
Build CLI with registry-aware resolution
Publish @agentic-skills/registry with initial snapshot
Build and publish SDK
pack.sh becomes backward-compat wrapper; standalone bash mode preserved
Over time, registry becomes source of truth; git repo is the authoring environment

Timeline

Phase	Size	Duration	Deliverable
1	M	3–4 weeks	Registry generator, `@agentic-skills/registry` publish, basic CLI
2	M	3–4 weeks	Full CLI with install/remove/doctor/pin/update
3	M	2–3 weeks	SDK package with TypeScript types
4	S	1–2 weeks	Docs, migration guide

Best for: Maximum multi-surface reach and future extensibility. Ideal if the vision includes third-party integrations, tool-agnostic consumption, and per-skill granularity.

Side-by-Side Comparison

Section feedback

Dimension	A Monolith	B Federation	C Registry
npm package count	1	~40	4
Install size per project	Full library (~3 MB)	Selected packs only	Selected skills only
Version granularity	Library-level	Pack-level	Skill-level
Agent publish workflow	Edit → `npm publish`	Edit → bump pack → publish pack	Edit → rebuild registry → publish registry
npm discoverability	Single listing	Per-pack listings	Single registry + CLI listing
Offline support	Full	Full (installed packs)	After initial fetch
Cross-pack dependencies	All available locally	npm peer deps	Registry resolves
Publishing overhead	Lowest	Highest	Medium
Time to first npm publish	~2 weeks	~6 weeks	~4 weeks
Total implementation	4–7 weeks	7–10 weeks	9–13 weeks
Programmatic SDK	Not included	Not included	Included
Per-skill install	No (full library)	No (full pack)	Yes
Community contribution	Easy (clone + PR)	Medium (must target pack)	Harder (registry pipeline)

Effort vs Reach

Evolutionary Path

These COAs are not mutually exclusive over time. A pragmatic path: start with COA A (fastest to npm), then extract hot packs into independent packages (COA B pattern) as demand grows, and layer the registry index (COA C pattern) as a discoverability surface on top. The CLI abstracts the backend so users never see the migration.

Recommendation: COA A — The Monolith. For a solo maintainer, COA A is the right starting point. It has the lowest publishing overhead (one npm publish), the fastest path to npm presence (~4–7 weeks), and the simplest agent publish workflow. The ~3 MB tarball is well within npm norms. The CLI abstraction layer means users never see if the backend evolves later — you can extract hot packs (COA B pattern) or add a registry index (COA C pattern) if demand warrants, without breaking anyone's install.

Future Consideration: Hosted Skill Registry. A central server that serves skills on-demand over HTTP without local npm install. This enables zero-install surface reach, usage analytics, dynamic versioning, access control, and third-party publishing. This is a different product from npm distribution — it requires hosting, authentication, uptime guarantees, and API design. Build it later if adoption warrants, reusing the versioning and pack metadata that npm establishes. A network protocol like MCP becomes a natural fit here (serving skills over a wire to remote clients) rather than wrapping local file reads.

Risk Matrix

Section feedback

Risk	A	B	C
Package size bloat	HIGH	LOW	LOW
Publishing coordination	LOW	HIGH	MED
Breaking change blast radius	MED	LOW	LOW
Agent publishability	EASY	MED	MED
Backward compat risk	LOW	MED	HIGH
npm scope availability	LOW	MED	LOW
Maintenance burden	LOW	HIGH	MED

Naming and Branding

Section feedback

The current branding uses "agentic-skills" as the repo name and "packs" / "card packs" as the grouping metaphor. Moving to npm creates a public identity that should be intentional.

Naming Options

Option	npm name	Scoped packages	Vibe
Keep agentic-skills	`agentic-skills`	`@agentic-skills/*`	Descriptive, clear, slightly long
skillpacks	`skillpacks`	`@skillpacks/*`	Leans into the "pack" metaphor, shorter
agentkit	`agentkit`	`@agentkit/*`	Broader, positions as a toolkit not just skills
promptpacks	`promptpacks`	`@promptpacks/*`	Describes what it literally is: packaged prompts

Terminology Mapping

Concept	Current term	Proposed public term
The product	agentic-skills (repo name)	TBD — see gate question
A bundle of related skills	Pack / Card pack	Pack (drop "card")
An individual skill	Skill	Skill (unchanged)
The CLI tool	`pack.sh`	`agentic-skills` / `skillpacks` (matches npm name)
Global (domain-neutral) skills	Global skills	Core skills

Evidence and Assumptions

Section feedback

Evidence Matrix

Claim	Evidence	Inference	Confidence	Decision impact
Current distribution requires git clone	`init.sh`, `pack.sh`, and `skill-links.sh` all resolve paths relative to the repo checkout. No `package.json` at root.	npm distribution requires wrapping or porting these scripts.	High	All COAs must port or wrap `pack.sh`.
Estimated npm tarball size ~3 MB for full library	298 SKILL.md files + archives + scripts; markdown files are small but archives multiply.	COA A's single package is large but not prohibitive for npm.	Medium	COA A is viable but wasteful for single-pack users.
Solo maintainer constraint	All 53k+ commits are from one author. No external contributors.	Publishing overhead must be automatable by agents.	High	COA B's 37+ packages are the highest maintenance risk.
Agent-driven publishing is feasible	Existing `create-agentic-skill` and `skill-archive.sh` already automate version bumps. `npm publish` can be scripted.	Agents can handle the full publish pipeline with minimal human intervention.	High	All COAs benefit; COA A is simplest to automate.
Pack interdependencies are soft, not hard	Cross-pack references are via slash-command recommendations in prose, not formal dependency declarations.	Pack packages do not strictly require npm peer dependencies.	High	COA B's dependency model is simpler than expected.

Assumptions Register

Assumption	Status	What would change it
`@agentic-skills` npm scope is available	Unverified	Check npm org availability before committing to scoped packages (COA B/C).
`agentic-skills` unscoped name is available	Unverified	Check `npm info agentic-skills`. If taken, all COAs need a different CLI package name.
Users are willing to use npm for skill management	Assumed	If the primary user base is non-developers, a different distribution channel (brew, curl) may be needed.
Monorepo tooling (pnpm workspaces) is sufficient for COA B	Provisional	37+ packages may need changesets or turborepo for coordinated releases.

Compile YAML

Section feedback

Use feedback YAML for emphasis requests, concerns, or clarification before answering all gates. Use final answers YAML only when every required gate is answered.

	Business / Consumer	Developer / OSS
Rapid (days)	VARD	ORD
Deliberate (weeks–months)	Business AFPS	Devtool AFPS

Current State Snapshot

Current Install Flow

What This Limits

Goals and Constraints

Must-Have Goals

Nice-to-Have Goals

Constraints

Invariants (All COAs)

COA A: The Monolith

COA A One package ships everything Recommended

Architecture

Version Model

CLI Surface

Migration Path

Timeline

COA B: The Federation

COA B Each pack is its own npm package

Architecture

Version Model

CLI Surface

Migration Path

Timeline

COA C: The Registry

COA C Skill registry + thin client

Architecture

Version Model

CLI Surface

SDK Surface

Migration Path

Timeline

Side-by-Side Comparison

Effort vs Reach

Evolutionary Path

Risk Matrix

Naming and Branding

Naming Options

Terminology Mapping

Evidence and Assumptions

Evidence Matrix

Assumptions Register

Review Gates

Recommended Path

Product Naming

Version Granularity

Artifact Destination

Post-Approval Route

Compile YAML

Deck-Based Installation

COA A Monolith — Decks as install presets

COA B Federation — Decks as curated package lists

COA C Registry — Decks as tagged collections