[RFC]: Where uv could benefit Skillware, install tooling, reproducibility, and dependency workflows

[rosspeili]

Summary

Skillware today ships as a standard PyPI package with optional extras in pyproject.toml, per-skill requirements in manifest.yaml, and install guidance centered on pip. uv is a modern Python package and project manager that is pip-compatible, fast, and built for reproducible environments and lockfiles.

This RFC opens discussion on where uv could meaningfully benefit Skillware — for maintainers, contributors, end users, and future framework features — without committing to a full toolchain switch. The goal is to map opportunity areas, compare lightweight adoption paths, and decide whether any of them are worth follow-up issues.

Scope of this RFC: tooling and workflow around Skillware, not a redesign of skill execution or manifest schema (those could be follow-ups if this RFC points there).

Out of scope for implementation in this RFC itself: this issue is for discussion and decision only. Concrete changes would land in separate [Feat] or [Docs] issues after consensus.

Motivation

Skillware sits at an interesting intersection:

Layer	Today
Framework package	pip install skillware with extras like [gemini], [claude], [dev]
Registry skills	Bundled in the wheel; manifest.yaml lists extra packages per skill
Loader	Checks imports at load time and suggests pip install … when deps are missing
Examples	Some scripts need packages beyond framework extras (e.g. fastembed, numpy)
CI	GitHub Actions installs via pip across Python 3.10–3.12

Several friction points uv is well suited to address:

1. Contributor onboarding — new contributors run pip install -e ".[dev,all]" and rely on an unpinned resolve. A lockfile-backed workflow could make “clone → test” more predictable.

2. CI install time — every push reinstalls dependencies with pip. uv’s resolver and cache are significantly faster, which matters as the test matrix and optional skill deps grow.

3. Documentation surface — install instructions appear across README, docs/usage/, skill catalog pages, examples index, and loader error strings. uv offers a parallel install path (uv pip install …) that works with the same PyPI artifacts Skillware already publishes.

4. Per-skill and per-example dependencies — manifests declare requirements metadata; examples sometimes need ad hoc packages. uv’s project and uv run patterns could eventually give contributors a clean way to run examples or skill tests in isolated, pinned environments.

5. Python version coverage — Skillware supports >=3.10 and CI runs 3.10, 3.11, and 3.12. uv can install and pin multiple Python versions locally, which helps maintainers reproduce matrix failures without manual pyenv/system setup.

6. Future dependency orchestration — if Skillware grows CLI commands for dependency profiles, environment repair, or workflow sync, uv is a strong candidate engine behind them because it already handles resolution, locking, venv creation, and Python version selection in one tool.

This RFC asks: which of these benefits are worth pursuing now, later, or not at all?

Detailed Design

Baseline (unchanged by default)

Skillware continues to publish standard wheels to PyPI from pyproject.toml using the existing build backend. uv consumes those artifacts like pip does:

uv pip install skillware
uv pip install "skillware[gemini]"
uv pip install -e ".[dev,all]"

No change to PyPI publishing is required for uv to be useful. uv reads PEP 621 metadata, optional dependency groups, and requires-python the same way pip does.

---

Opportunity areas

1. Maintainer and CI workflow

What uv could improve

Area	Current	With uv
CI install step	pip install + manual extra packages in ci.yml	uv pip install or uv sync with cache
Reproducible CI/dev resolves	Unpinned unless manually locked	uv.lock committed for the repo
Cold start time	Full resolver run each job	uv cache + faster resolver

Possible adoption path

Phase	Action
A	Swap CI install commands to uv (keep same dependency set)
B	Add uv.lock for contributor reproducibility
C	Pin uv version in CI via astral-sh/setup-uv

Discussion point: Is Phase A alone enough ROI, or is B necessary for Skillware?

---

2. Contributor documentation

What uv could improve

A single documented alternative path for installs:

# Existing
pip install skillware
pip install -e ".[dev]"

# Additional
uv pip install skillware
uv sync   # if repo adopts uv.lock

Files that would eventually mention uv (in follow-up docs issues):

File	Role
README.md	Quick Start
CONTRIBUTING.md	Dev setup
docs/usage/cli.md	CLI install section
requirements.txt	Dev convenience pointer
skillware/core/loader.py	Missing-deps error message
skillware/version_policy.py	Upgrade advisory text

Discussion point: Should uv appear as “equally supported” or “recommended for contributors only”?

---

3. Reproducible framework development

What uv could improve

The Skillware repo itself is a Python project with optional groups (dev, cli, gemini, etc.). A root uv.lock would:

• Pin transitive dependencies for all contributors
• Make CI and local pytest runs resolve the same versions
• Reduce “works on my machine” drift when optional SDKs bump

Discussion point: Does Skillware want a committed lockfile at repo root, or prefer staying lock-free and only using uv as a faster pip?

---

4. Python version management

What uv could improve

Maintainers testing the 3.10 / 3.11 / 3.12 matrix locally could use:

uv python install 3.10 3.11 3.12
uv run --python 3.11 pytest tests/

Contributors on Windows (a common Skillware audience per CLI docs) benefit from uv managing interpreters without relying on OS Python layout.

Discussion point: Is this worth a short section in CONTRIBUTING, or purely maintainer-internal?

---

5. Examples and skill-adjacent dependencies

What uv could improve

Today some examples document manual installs:

pip install fastembed numpy
pip install "skillware[gemini]"

uv could support clearer patterns:

Pattern	Benefit
uv pip install in example docs	Faster, same commands with uv prefix
Per-example pyproject.toml + lock (optional)	Runnable uv run examples/gemini_novelty_extractor.py with pinned deps
Profile groups aligned with framework extras	uv sync --extra gemini mirrors pip install -e ".[gemini]"

This stays compatible with Skillware’s model where registry skills declare requirements: in manifest.yaml for discovery and loader checks.

Discussion point: Should examples gain lightweight uv project files, or should the repo stay a single-root project only?

---

6. Manifest requirements and future CLI tooling

What uv could improve

SkillLoader already reads manifest.yaml requirements and validates imports. uv could power future framework commands, for example:

Hypothetical command	uv role
skillware doctor	Detect missing deps, suggest or run install
skillware sync --profile gemini	Install extras + skill deps into current env
skillware run-example <script>	uv run with resolved deps for that example

None of this exists today. This RFC only asks whether adopting uv now (CI/docs) makes those features easier later.

Discussion point: Should the RFC record uv as the preferred backend for a future dependency CLI, or keep that decision open?

---

7. Optional extras mapping

What uv could improve

Skillware’s optional groups in pyproject.toml are coarse bundles:

[project.optional-dependencies]
gemini = ["google-genai"]
claude = ["anthropic"]
all = [...]

uv resolves these groups identically to pip. Over time, documentation could map skill categories or skill IDs to recommended extras (e.g. compliance skills → core only, Gemini examples → [gemini]), with uv sync profiles as the mechanical install step.

Discussion point: Is a “skill → recommended extra” table in docs enough, or should the CLI expose that mapping?

---

8. Publish workflow (optional enhancement)

What uv could improve

The current .github/workflows/publish.yml uses pip install build and standard tooling. uv also provides uv build for producing sdist/wheel from pyproject.toml.

Discussion point: Is there benefit to switching the publish workflow to uv, or is CI/install adoption sufficient?

---

Proposed decision framework

After discussion, record decisions on a simple matrix:

Area	Options
CI	No change / uv install only / uv + lockfile
Docs	No mention / optional parallel commands / uv-first for contributors
Repo lockfile	None / uv.lock at root / per-example locks
Loader messages	pip only / pip + uv hint
Future CLI deps	Defer / design with uv as intended backend

Follow-up issues (post-RFC) might include:

1. [Docs]: Document uv as supported install path
2. [Feat]: Adopt uv in GitHub Actions CI
3. [Feat]: Add uv.lock for contributor reproducibility
4. [Feat]: RFC follow-up — dependency profiles / doctor command (if desired)

---

References

Resource	Link
uv documentation	https://docs.astral.sh/uv/
Skillware optional extras	pyproject.toml [project.optional-dependencies]
Loader dependency check	skillware/core/loader.py
CI install step	.github/workflows/ci.yml
Dev install pointer	requirements.txt

Drawbacks

Tradeoffs and open questions will be captured in discussion on this RFC and in follow-up issues.

[rosspeili]

Questions for maintainers and contributors. Reply with preferences, tradeoffs you care about, or “defer.”

1. CI first? Is adopting uv in GitHub Actions the highest-value first step?

2. Lockfile? Should Skillware commit a root uv.lock, or stay unpinned and use uv only for speed?

3. Documentation stance? Should README list uv alongside pip from day one, or start in CONTRIBUTING only?

4. Loader error strings? Should missing-deps messages mention uv pip install in addition to pip install?

5. Examples layout? Are per-example uv project files desirable, or too much structure for a skill registry repo?

6. Future CLI? If Skillware adds dependency orchestration (doctor, sync, profiles), should this RFC note uv as the intended implementation tool?

7. Optional extras vs skill manifests? Is the current [gemini] / [claude] model sufficient long term, or should this RFC spawn a separate discussion on manifest-driven install profiles (with uv as the engine)?

8. Publish workflow? Any interest in uv build for releases, or is install/CI scope enough for v1 of uv adoption?

9. Python pin file? Should the repo add .python-version (e.g. 3.12) for contributors using uv, while keeping requires-python = ">=3.10" for PyPI?

10. Success criteria? What would make you say “yes, uv adoption was worth it” six months after merging follow-ups?