Skip to content

ADR 0002 — npm Skill Marketplace as Skill Source-of-Truth

  • Status: accepted
  • Date: 2026-05-22
  • Deciders: principal-architect (eric)
  • Supersedes: —
  • Superseded by: —
  • Related: ADR-0001

Context

The framework's value depends on having a rich, curated set of skills. Options: 1. Build skills in-house (huge effort, narrow domain) 2. Crawl public docs (legally messy, quality variable) 3. Use existing skill marketplace (skills.sh / npm) 4. Hybrid: in-house + marketplace

The marketplace already hosts 1000+ community skills with install counts that signal quality. Using it as source-of-truth gives us leverage at zero authoring cost; the trade-off is dependency on an external ecosystem.

Options considered

Option A — Marketplace as source-of-truth + curated subset

  • ✅ Massive leverage (684 skills already filesystem-installed)
  • ✅ Install counts give a quality signal
  • ✅ Community maintains them; we curate
  • ❌ Marketplace API can change; rename risk (R-001)
  • ❌ Skill quality varies; need curation discipline

Option B — Build in-house

  • ✅ Full control + uniformity
  • ✅ Quality guaranteed
  • ❌ Effort: years of work to match marketplace breadth
  • ❌ No leverage from broader community

Option C — Hybrid (marketplace base + in-house extensions)

  • ✅ Combines leverage with control
  • ❌ Two-class system; complexity
  • ❌ Eventually devolves toward one side or other

Decision

Adopt Option A. Marketplace is source-of-truth. We curate via a 4-tier system (platinum/gold/silver/bronze) with provenance scoring to filter out false matches. In-house skills permitted but rare.

Tier thresholds: - Platinum: ≥100K installs OR official Anthropic - Gold: 10K-100K - Silver: 1K-10K with provenance score ≥ 50 - Bronze: 100-1K with provenance score ≥ 50

Consequences

Positive

  • 684 skills available immediately
  • Weekly refresh via _refresh-curated.py keeps tier data current
  • Audit chain validates curated entries match disk (zero orphans)
  • Community ownership of skill maintenance

Negative

  • External dependency: marketplace outage or rename = breakage (R-001 mitigation in place)
  • Skill quality varies; curation is ongoing work
  • License of marketplace skills must be tracked (none yet block use)

Neutral

  • Provenance scoring is heuristic; false positives possible (mitigated by ≥50 threshold + manual review)

Compliance

  • Rule 1, 2 (Documentation + Single Source of Truth): _skills-registry.yaml is authoritative for curated set; registry-full.yaml for filesystem
  • Rule 23 (4 data tiers): skill registry is Tier 1 (internal)

Implementation references

  • Curation tooling: _fetch-marketplace.py, _refresh-curated.py, _analyze-deltas.py
  • Registry: docs/reference/registries/_skills-registry.yaml (127 curated)
  • Full inventory: docs/reference/registries/registry-full.yaml (684 total)
  • Audit: _audit.py enforces zero orphans + schema integrity
  • Provenance scoring: in _find_silver.py / _find_bronze.py (temp scripts, removed; logic preserved in scoring rationale of inventory)