Windows 11にuvをセットアップし、Claude DesktopのカスタムSkillでPython実行時にuvを使うようにしてみた
さがらです。
Windows 11のClaude DesktopでカスタムSkillからPythonスクリプトを実行する際に、Pythonのパッケージマネージャー兼ランタイム管理ツールである uv を使う構成にしたいと思い、Windows 11でのuvのセットアップ手順と、Claude Desktopからの動作確認方法について本記事でまとめます。
本記事では、Claude Desktop上の「コード」機能を用いて、カスタムSkill実行時のPython関連操作を行う想定で説明します。
uvとは
uvは、Python向けのパッケージマネージャー兼ランタイム管理ツールです。Pythonパッケージのインストールだけでなく、Python本体の管理、プロジェクト初期化、依存関係の追加、スクリプト実行までを一貫して扱えるのが特徴です。
従来のPython環境構築では、Python本体のインストール、仮想環境の作成、pip による依存関係追加などを個別に考える必要がありましたが、uvを使うことでこれらをよりシンプルにまとめて管理しやすくなります。
また、uvはフォルダごとにPython環境を管理しやすい点も大きなメリットです。各フォルダごとにPythonのバージョンや利用するパッケージを独立して管理できるため、プロジェクトごとに異なるPythonバージョンや依存関係が必要な場合でも扱いやすくなります。
特に今回のようにClaude DesktopからPython関連の操作を実行させたい場合、使うコマンドをuvに寄せることでルールを統一しやすい というメリットがあります。たとえば、プロジェクト初期化は uv init、依存関係の追加は uv add、スクリプト実行は uv run python というように、Claudeへの指示も整理しやすくなります。
前提条件
以下の環境での実施を想定しています：
- OS: Windows 11
- Claude Desktop: インストール済み、Maxプラン（Max 100）
- Python: 未インストール
- uv: 未インストール（本記事でセットアップ）
セットアップの流れ
本記事では、まずWindowsに uv をインストールし、その後 CLAUDE.md でuvの使用ルールを定義します。そのうえで検証用のSkillを作成して、Claudeに実行させながら動作確認していきます。
動作確認では、主に以下を確認します。
- Claudeが
uv run pythonでPythonスクリプトを実行できるか CLAUDE.mdの記述に沿ってuv initが実行されるか- 外部パッケージが必要なスクリプトに対して、Claude経由で
uv addを実行できるか uv initやuv add実行後にpyproject.tomlやuv.lockなどのファイルが作成・更新されるか
1. uvのインストール
PowerShellからuvをインストール
PowerShellを立ち上げ、以下のコマンドを実行します。（コマンドはuvの公式Docより引用）
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
インストールが完了すると、$HOME\.local\bin\ 配下に uv.exe が配置されます。PATHも自動で設定されます。
インストールの確認
PowerShellで、以下のコマンドを実行し、uvが正しくインストールされたことを確認します。
uv --version
バージョン番号が表示されればOKです。
2. CLAUDE.mdでuvの使用を徹底する
ClaudeがPythonを実行する際にuvを使うよう促すには、CLAUDE.mdに使用ルールを記載する方法が有効です。
CLAUDE.mdは、Claudeに対するプロジェクトレベルの指示ファイルです。ここに記載したルールは、プロジェクト内でClaudeが動作する際に参照されます。カスタムSkillの実行時にも適用されることが期待できるため、Python関連の操作をuvベースに寄せたい場合に有効です。
CLAUDE.mdの配置場所
特定のプロジェクト内でのみuvを使うようにしたい場合
CLAUDE.mdはプロジェクトのルートディレクトリに配置します。
my-project/
├── CLAUDE.md # Claudeへの指示ファイル
├── scripts/
│ └── process.py
└── ...
グローバル設定にしたい場合
特定のプロジェクトだけでなく、すべてのプロジェクトでuvを使いたい場合は、ユーザーのホームディレクトリにある~/.claude/CLAUDE.mdに記載することもできます。
グローバルのCLAUDE.mdに記載したルールは、すべてのプロジェクトに適用されます。
Windowsでは、~/.claude/CLAUDE.md は通常 C:\Users\<ユーザー名>\.claude\CLAUDE.md に相当します。
私はこちらの方法で行ったので、下図のように配置しました。
CLAUDE.mdの記載例
以下のように、Python関連の操作でuvを使うルールを記載します。
# Python / uv policy
- Python関連の作業では、必ず `uv` を使用すること
- `python`、`python3`、`pip`、`pip3` を直接実行しない
- Pythonの仮想環境が対象フォルダで未作成の場合は、まず `uv init` を使用してプロジェクトを初期化する
- 依存関係が必要な場合は `uv add <package>` を使用する
- Python実行: `uv run python ...`
- ツール実行: `uv run <tool> ...`（pytest、ruff、mypy等）
- pip互換ワークフローが明示的に必要な場合のみ `uv pip ...` を使用
- Bashコマンドを実行する前に、uvの等価コマンドに書き換えること
- Python関連の提案を行う際は、まずuvベースの手順を優先して提示すること
このようにしておくことで、Pythonの単発実行だけでなく、必要に応じたプロジェクト初期化や依存関係追加も含めて、Claudeにuvベースで作業させやすくなります。
動作確認
CLAUDE.mdの設定が正しく反映されているか、検証用のSkillを使ってClaude Desktopで確認していきます。
検証用のフォルダに外部パッケージ必須のPythonスクリプト込みSkillを作成
検証用に、外部パッケージが必須のPythonスクリプトを含むSkillだけを含むフォルダを作成します。今回は外部パッケージとして requests を利用します。
- フォルダ構成
uv_check/
└── .claude/
└── skills/
└── random-quote/
├── SKILL.md
└── reference/
└── random_quote.py
uv_check/.claude/skills/random-quote/SKILL.md
---
name: random-quote
description: 外部APIからランダムな名言を取得して表示する
user_invocable: true
---
# random-quote
`reference/random_quote.py` を実行して、外部APIからランダムな名言を取得して表示します。
## 手順
1. Python実行環境が未作成であれば、uvを使って必要な初期化を行う
2. `requests` が未追加であれば、uvを使って依存関係に追加する
3. `reference/random_quote.py` を実行する
4. 出力結果をユーザーに表示する
uv_check/.claude/skills/random-quote/reference/random_quote.py- 「外部APIからランダムな名言を取得して、ターミナルに表示する」というプログラムです
import requests
response = requests.get("https://api.quotable.io/random", timeout=10)
response.raise_for_status()
data = response.json()
print(f"{data['content']} — {data['author']}")
このスクリプトは requests パッケージに依存しているため、単に uv run python を実行するだけでは動かず、事前に uv add requests が必要になります。
ClaudeからSkillを実行してみる
Claude Desktopで「コード」から、先ほど作成した uv_check/ フォルダを指定して新しいプロジェクトを立ち上げます。
その上で、作成した random-quote Skill を呼び出してみます。
外部パッケージが必要なスクリプトであり、Pythonの仮想環境もできていないため uv init が実行されます。
続いて、外部パッケージである requests を追加するため、uv add requests が実行されます。
これで準備が整ったので、uv run python が実行されます。
Pythonプログラムが実行され、API経由で名言が返ってきました！
あとはおまけですが、uv init を行ったタイミングでこのフォルダ内にPythonのパッケージ管理関連のファイルが自動で追加されます。
このように、Claude Desktop上のSkill実行をきっかけとして、uv init → uv add requests → uv run python という流れで、必要なセットアップから実行までをuvベースで進められることを確認できました。
最後に
Windows 11のClaude Desktopで、カスタムSkill実行時にuvを使うための流れをまとめました。
まずはWindowsにuvをインストールしておき、CLAUDE.md にuv利用ルールを記載することで、ClaudeにPython関連の作業をuvベースで行わせやすくなります。
また、uvを使うことで、フォルダごとにPythonのバージョンや依存パッケージを独立して管理しやすくなるため、複数のプロジェクトを並行して扱う場合にも便利です。
今回の確認では、外部パッケージが必要なPythonスクリプトを含むSkillに対して、Claudeが uv init によるプロジェクト初期化、uv add requests による依存関係の追加、uv run python によるスクリプト実行までを順番に行えることを確認できました。
Windows 11のClaude Desktopにおいて、カスタムSkillでPythonを活用したい方の一助になれば幸いです！
