soia-env-python-install

First confirm the Python interpreter already on the system and the project's version requirements, then choose the official installer or a system-recognized package management method. By default use python -m pip and a project virtual environment to avoid polluting the system Python.

Customer-readable description

What this skill can do

Customer wants	Skill will do	Customer can see
Install Python	Identify system/architecture, choose the official stable version, install and verify	Python/pip version and status
Check for Python updates	Identify interpreter source and project constraints, do not auto-update	Current version, latest version and source
Update Python to the latest	After the customer explicitly requests the latest version, update along the original source	Intermediate state, virtual environment impact and verification results
pip unavailable	Distinguish interpreter, PATH, pip module and permission issues	Safe fix plan
Prepare scripts or knowledge base tools	Create a project-level virtual environment and verify dependency entry points	Readiness summary that can be handed off to downstream skills

How the customer uses it

Other recognizable phrasings include "update Python to the latest", "install pip", "pip doesn't work"; for pure network timeouts, prioritize handing off to soia-env-network-diagnose。

State the target project, operating system and whether there are version requirements; when unsure, choose the currently maintained stable version from the official Python release.
The agent first checks python3、python、Windows py, pip and the project configuration, and does not overwrite existing environments.
When a new version is found, only report it; when only "update Python" is said, first ask whether to update to the latest, and only execute after the latest version is explicitly chosen.
Show the install source, version and PATH impact; when administrator privileges or system-wide installation are needed, confirm separately.
During installation or an explicitly authorized update, continuously display and record checks, plan, execution, verification and final state.

Dependencies and installation

No required external skill. For network issues, first call soia-env-network-diagnose. For official sources, platform differences and maintained versions, see official-sources.md。

Standard process

Read-only check of OS, architecture,python3 --version、python --version、Windows py --version、python3 -m pip --version, and record the interpreter source; do not write the full user path into the receipt.
Read the version constraints in the project's pyproject.toml、requirements.txt or .python-version ; when project files are missing, do not guess project dependencies.
Choose the official Python installer or the current system's official package manager; do not treat third-party "one-click scripts" as the default solution.
After installation, prioritize calling pip in interpreter module form:python -m pip or py -m pip。
In the project directory specified by the user, create .venv or another explicit virtual environment; do not commit the virtual environment to the repository.
Verify the interpreter, pip, virtual environment activation/invocation and one side-effect-free import; on failure, report only the blocking category.

Installed status and updates

First determine the current interpreter and source; if already installed and meeting project constraints, prompt "Python is already installed, no need to reinstall", do not overwrite the system Python, and do not reinstall the runtime just because pip is old.

First check python3 --version、python3 -m pip --version、command -v python3, as well as Homebrew,pyenv, the official installer, or Windows py source indications.
Official installer management: obtain the target maintenance version installer from the official Python download page, and record the existing interpreter and project constraints before updating.
Homebrew management: only after the customer explicitly requests updating to the latest compatible version, execute brew update && brew upgrade python, and do not additionally layer on the official installer.
pyenv management: after obtaining authorization for the latest version, continue using pyenv to install and select the target version, for example pyenv install <version>; do not mix pyenv and Homebrew/official installer as the same interpreter setup.
pip update is an independent action; only when the customer explicitly requests updating pip to the latest, execute within the selected interpreter/virtual environment python -m pip install --upgrade pip. Project constraints can only trigger version reporting and confirmation, and cannot automatically update pip, nor can pip updates be treated as Python runtime updates.

An ambiguous "update Python" only performs a version comparison and returns "waiting for confirmation whether to update to the latest". Explicitly installing a missing Python can install a recommended stable version that meets project constraints, and is not considered updating an existing tool.

After updating, separately verify the interpreter version,python -m pip --version, the project virtual environment, and project version constraints. If the update fails, retain the old interpreter, virtual environment, and error evidence, and do not automatically delete the environment.

Customer status list (mandatory)

Skill	Current status	Current version	Latest version	Running status	Update time	Handling result
Python	<installed/not installed/blocked>	<version or not obtained>	<version or not obtained>	<normal/abnormal/unverified>		<no need to reinstall/updatable, not executed/waiting for confirmation whether to update to the latest/updated/waiting for confirmation before installation/blocked: reason>

When the user only asks about Python, output only the Python row, and do not additionally output pip; only when the user explicitly asks about pip, add the pip row.
更新时间 Record the time after interpreter, pip, and harmless virtual environment verification are completed.
The latest version must comply with project constraints; if it cannot be obtained, write "not obtained" and do not guess.
After the table, retain only the necessary permission confirmation, virtual environment impact, or blocking explanation, and do not display the internal probing log.

Intermediate states of installation and update

When actually performing installation or an update authorized for the latest version, use a random run_id to immediately call at the moment each stage actually occurs scripts/record_install_progress.py: record once each before inspection, after the plan is formed, before the installer/updater call, before verification, and at the final state; when administrator privileges, changing sources, modifying PATH, or affecting the project virtual environment are needed, first present the exact plan and record waiting_confirmation, and continue only after obtaining confirmation for that item. Do not write it afterward; the time is generated by the recorder. Read-only checks do not call it. Only when the customer's exact words explicitly request the latest version does the update execution stage carry --customer-requested-latest。

python3 scripts/record_install_progress.py --run-id <run-id> --action <install|update> --stage checking --status in_progress --result-code checking_started
python3 scripts/record_install_progress.py --run-id <run-id> --action update --stage updating --status in_progress --result-code update_started --customer-requested-latest

At the same time, continuously display the fixed stage table; whether successful, failed, canceled, or waiting for permission, append the final state:

Stage	Current status	Update time	Handling result
<inspection/plan/waiting for confirmation/installation or update/verification/completed or failed>	<in progress/waiting/completed/failed/blocked>		<redacted result>

Permissions and rollback

Default user-level installation; do not automatically use sudo, administrator privileges, or replace the system Python.
Do not execute pip install into the global environment, and do not modify project dependency files unless the customer explicitly requests it.
Do not delete the old Python; when versions conflict, keep the current state and provide a rollback-capable option.

Private information and intermediate data

Private package source credentials use the provider's official login state, keyring, or system credential store; SOIA configuration stores only non-secret preferences and paths.
During installation or update, use a progress recorder to append redacted actions, stages, results, and times; read-only checks are not written to disk by default.
Package index metadata may be placed in cache; wheels, installers, and virtual environment detection files are placed in the system temporary directory and cleaned up after success or failure.
Do not record pip tokens, full private index URLs, usernames, virtual environment contents, or customer private absolute paths.

Logs and completion receipt

| 技能 | 当前状态 | 当前版本 | 最新版本 | 运行状态 | 更新时间 | 处理结果 |
|---|---|---|---|---|---|---|
| Python | <状态> | <当前版本> | <最新版本> | <运行状态> | <RFC3339-with-timezone> | <处理结果> |

Forward testing

Use fixtures to cover Python already present, only Python 2 present, pip missing, Windows py available, and virtual environment creation failure; real acceptance must separately verify the interpreter, pip, and the project virtual environment.

Install the entire domain (Claude Code and Codex share the same domain plugin):

claude plugin marketplace add soia-team/soia-open-skills
claude plugin install soia-env@soia

Install only this one skill:

npx skills add soia-team/soia-open-env-skills -g -a '*' -s soia-env-python-install -y

WorkBuddy 's loading unit is role-based experts rather than plugins,npx skills add -a '*' cannot cover it, so it needs to be installed separately, see docs/install/workbuddy.md。