pip install fails on macOS due to PEP 668 (Externally Managed Environment)

[GordonChowkk]

Problem

Following the install instructions in README:

git clone --depth 1 https://github.com/oaker-io/wewrite.git ~/.claude/skills/wewrite
cd ~/.claude/skills/wewrite && pip install -r requirements.txt

pip install -r requirements.txt fails on macOS (Homebrew Python 3.11+) with:

error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try brew install xyz.
    ...
    See PEP 668 for the detailed specification.

This is because macOS Homebrew Python now enforces PEP 668, which prohibits direct pip install into the system Python environment.

Workaround

Create a virtual environment first:

cd ~/.claude/skills/wewrite
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Then all python3 references in SKILL.md need to be changed to {skill_dir}/.venv/bin/python3 so that scripts use the venv Python at runtime.

Suggestion

1. Update README install instructions to use venv
2. Update SKILL.md to reference {skill_dir}/.venv/bin/python3 instead of bare python3
3. Or provide an install.sh script that handles venv creation + dependency installation automatically

Environment

• macOS Sequoia (Darwin 25.1.0, arm64)
• Python 3.13 (Homebrew)
• pip 26.0