[RFC]: Install model — one wheel, category and skill dependency extras

[rosspeili]

Summary

Context: #234 closed — bundled registry = executable Python skills in one PyPI wheel; no soft/hard packaging axis; external/project skills stay operator-managed (discovery + trust doc).

Problem

pip install skillware

installs the core framework and ships all registry skill bundles on disk. Optional extras in pyproject.toml today are SDK/domain-shaped (gemini, defi, office, [all]), not aligned with skill categories or individual skills.

When a user calls load_skill() without the right deps installed, load hard-fails with an ImportError and a generic pip install … hint — deps are not auto-installed at execute time. Operators either install [all] (heavy) or discover missing packages one skill at a time.

As the registry grows, we need an explicit optional extras story: same wheel and same skills on disk, but predictable ways to pre-install category or skill-specific runtime dependencies from manifest requirements.

This RFC discusses install/extras design; it does not split the wheel or change loader discovery roots.

Prerequisite: #182 (wheel smoke test) should land before automating or reshaping extras.

Project: Identity & Registry v2

---

Motivation

Contributors and operators may want:

• Base install unchanged — one command, all bundled skills available by ID
• Lighter targeted installs — pip install skillware[finance] pre-installs deps for finance skills only
• Skill-level precision (optional) — pre-install deps for one skill without [all]
• Clear separation — SDK extras (agent adapters) vs skill runtime deps (manifest requirements)
• No surprise failures — document recommended extras on skill pages and in CLI/docs

Not in scope: multiple PyPI wheels, per-skill PyPI packages, external registry hosting, instruction-only / soft skill packages.

---

Product model (proposed)

Layer	Install	What it does
Core	pip install skillware	Framework + all skill folders on disk + shared core deps
Category extras	pip install skillware[finance]	Union of manifest.requirements for skills under skills/finance/
Skill extras (optional)	TBD naming, e.g. skillware[finance/wallet_screening]	That skill’s manifest requirements only
SDK extras (keep)	gemini, claude, openai, …	Agent adapter deps — separate from skill runtime
Convenience	skillware[all]	Meta-extra for CI / full dev installs

Important: extras control Python dependencies only. They do not remove skills from the wheel or change which IDs load_skill() can resolve.

---

Detailed design

Phase 0 — Baseline (prerequisite)

• #182: prove built wheel loads every bundled skill in a clean venv
• Document today’s behavior: list scans YAML; load checks requirements via find_spec (no version check yet — see [Feat]: Support proper version specifiers in Skill requirements validation #14)

Phase 1 — Category-aligned extras (target for next releases)

• Add [compliance], [finance], [defi], … extras = union of manifest deps per category folder
• Same monolithic wheel; all skills remain on disk
• README + docs/usage/ + skill catalog: “recommended install” per category
• Consider mapping or merging current domain extras (defi, office) into category names to avoid duplicate/confusing groups

Phase 2 — Skill-level extras (optional follow-up)

• Fine-grained extras for single-skill workflows or minimal containers
• Naming convention TBD (registry ID vs short alias)
• Higher maintenance cost — only if Phase 1 proves insufficient

Phase 3 — Automation / drift guard

• CI script: derive or verify pyproject.toml extras against all skills/**/manifest.yaml requirements
• Fail PR if manifest adds a requirement not reflected in category (or skill) extra
• Related: #235 richer load errors should hint the correct extra name when mappable

---

Open questions

1. Category extras vs current defi / office extras — rename to category, keep both, or alias?
2. Skill-level extras — worth the maintenance, or category-only for v1?
3. Auto-generate vs hand-maintain — script in CI to build extras from manifests, or manual pyproject.toml until registry is larger?
4. Naming — category = folder name; skill extra = full registry ID or sanitized slug?
5. [all] composition — core + every category + SDK extras, or separate [all-skills] vs [all]?

---

Relationship

Issue	Role
#234	Closed — single bundled wheel; no soft/hard split
#182	Prerequisite wheel smoke test
#235	Richer dependency errors; should suggest correct extra
#14	Version specifiers in requirements (future)
#241	External registry — deferred; out of this RFC
#149	uv tooling — optional input

---

Suggested outcomes (when ready to close this RFC)

• Agreed: monolithic wheel + category extras (Phase 1) for next 1–2 releases
• Decision on skill-level extras (Phase 2): in / out / later
• Decision on defi / office vs category naming
• Child implementation issue(s) after [Feat]: PyPI wheel smoke test — load every registry skill after pip install #182 is green
• No wheel split or external registry work from this RFC

---

Drawbacks

• Category extras may drift from manifest requirements without CI automation (Phase 3 mitigates)
• Too many extras names confuse pip install UX — docs and loader hints must stay aligned ([Feat]: Loader dependency diagnostics and load modes #235)
• Skill-level extras multiply maintenance as registry grows
• Not a drawback we’re taking: split wheels / external PyPI packages — explicitly deferred