Proposal: Modernize to UV shebang scripts (PEP 723)

[ddlaws0n]

Summary

Propose converting this skill from manual `.venv/requirements.txt` management to modern `uv` shebang scripts with PEP 723 inline metadata.

Motivation

Current approach:

• Requires custom `run.py` wrapper to manage venv
• Manual `setup_environment.py` for first-time setup
• Separate `requirements.txt` file
• 300+ lines of infrastructure code

UV shebang approach:

• Self-contained scripts with inline dependencies
• Automatic dependency installation
• Standard Python ecosystem tool (Astral/Ruff team)
• Zero infrastructure code needed
• Faster dependency resolution and caching

Benefits

1. Simpler installation: No more `python scripts/run.py script.py` wrapper
2. Self-documenting: Dependencies visible in each script
3. Faster execution: UV caches dependencies (instant second run)
4. Modern standard: PEP 723 is official Python spec
5. Less code: Removes 300+ lines of wrapper infrastructure

Breaking Changes

This would be a v2.0.0 breaking change:

Old command pattern:
```bash
python scripts/run.py ask_question.py --question "..."
```

New command pattern:
```bash
./scripts/ask_question.py --question "..."

or

uv run scripts/ask_question.py --question "..."
```

Migration:

• Users need to install uv: `curl -LsSf https://astral.sh/uv/install.sh | sh`
• Scripts become directly executable
• Complete migration guide would be provided

Example Implementation

Before (ask_question.py):
```python
#!/usr/bin/env python3

Requires run.py wrapper to execute

```

After (ask_question.py):
```python
#!/usr/bin/env -S uv run --quiet --script

/// script

requires-python = ">=3.8"

dependencies = [

"patchright==1.55.2",

"python-dotenv==1.0.0",

]

///

Self-contained, auto-installs dependencies

```

Files to Modify

Add UV shebang:

• `scripts/ask_question.py`
• `scripts/auth_manager.py`
• `scripts/notebook_manager.py`
• `scripts/cleanup_manager.py`

Remove (no longer needed):

• `scripts/run.py`
• `scripts/setup_environment.py`
• `requirements.txt`

Keep as utility modules (no shebang):

• `scripts/config.py`
• `scripts/browser_utils.py`
• `scripts/browser_session.py`

Update documentation:

• `SKILL.md` - Update all command examples
• `README.md` - Update installation and quick start
• `CHANGELOG.md` - Add v2.0.0 with migration guide

Testing

I can test thoroughly on macOS. Would need maintainer or community to verify on Windows/Linux.

Questions

1. Is this direction aligned with your vision for the skill?
2. Would you prefer this as a breaking v2.0.0 release, or should I maintain backward compatibility somehow?
3. Any concerns about the UV requirement for users?

Happy to discuss the approach and make adjustments based on your feedback!

References

• UV Documentation
• PEP 723: Inline Script Metadata
• UV Shebang Examples