生成AI関連
生成AIのSkillsとは？仕組み・MCPやカスタム指示との違い・デモまで
Claude CodeやCodexといった生成AIエージェントのSkillに、補助用のPythonスクリプトを同梱して利用する場面が増えてきました。Skillsそのものについては、過去記事で仕組みと使い方を整理しています。
Skillにスクリプトを配置すること自体は容易ですが、外部ライブラリを利用するスクリプトを扱う場合は、依存関係の置き場所に悩むことがあります。pyproject.toml を同梱する、Skill専用のvenvを用意する、グローバル環境にインストールする、といった方法が考えられますが、いずれの場合も「実行前にこの準備を行うこと」「このvenvを使用すること」といった前提条件をエージェント向けに記述する必要が生じます。その結果、SKILL.md の説明文が長くなり、Skillの保守性が低下します。
本記事では、この課題に対するアプローチのひとつとして、Pythonのインラインメタデータ仕様であるPEP 723をSkillの中で利用した事例を紹介します。常に最適な選択肢というわけではありませんが、Skill同梱スクリプトとの相性は良好で、検討に値する書き方であると考えています。
Skillに同梱するPythonスクリプトが外部ライブラリを利用する場合、依存関係を管理する方法には複数の選択肢があります。代表的な方法と、それぞれの課題を整理します。
| 方法 | 課題 |
|---|---|
| Skillディレクトリ内に venv を作成 | venvの構築・有効化手順を SKILL.md に記述する必要があり、Skillの可搬性も低下する |
| pyproject.toml を同梱 | 事前の uv sync や .venv の所在を SKILL.md でエージェントに指示する必要がある |
| グローバル環境にインストール | 実行環境への依存が強くなり、マシン間で挙動が変動する |
| 実行コマンド側に依存を記述 | エージェントへ渡す実行コマンドが長くなり、指示の誤りや記述漏れが生じやすい |
いずれの方法でも動作はしますが、Skillはエージェントが必要に応じて呼び出して活用する仕組みであるため、前提となる準備手順はできる限り減らすことが望まれます。SKILL.md の記述量が増えることは、Skillの保守性の観点からも避けたい点です。
加えて、エージェントに対する指示は、複雑になるほど忠実に守られる保証が弱くなります。venvの有効化や事前の uv sync といった手順を SKILL.md に記述しても、エージェントが手順の一部を省略してしまえば、依存関係が解決されないまま実行され、Skillが本来の役割を果たせなくなる可能性があります。SKILL.md をできる限り簡潔に保つことは、Skillの動作の安定性にも直結します。
そこで検討対象としたのが、近年Pythonコミュニティで利用が広がっているPEP 723です。
PEP 723 は、Pythonスクリプトの先頭に実行時メタデータをインラインで記述するための仕様です（PEP 723 – Inline script metadata）。
書き方は単純で、Pythonファイル先頭に次のようなコメントブロックを記述します。
# /// script
# requires-python = ">=3.13"
# dependencies = [
# "openpyxl>=3.1.5"
# ]
# ///
～以降はpythonの本文を記載～
# /// script から # /// までのブロックがメタデータです。uv などのツールがこのブロックを読み取り、必要なバージョンのPythonと依存パッケージを揃えた上でスクリプトを実行します。
uv を利用する場合、PEP 723 メタデータを含むスクリプトは次のように実行します。
uv run --script inline_sample.py
–script を付けることで、uv がインラインメタデータを解析する「スクリプト実行モード」で動作します。事前の uv sync や uv add は不要で、依存パッケージは初回実行時に自動的に解決されます。
この方式の特徴は、依存関係の宣言がスクリプト自身に閉じている点です。pyproject.toml や requirements.txt、別ディレクトリの .venv を参照する必要がなく、Skill同梱スクリプトの用途と相性が良い構造です。
なお、uv には uv run –with openpyxl script.py のように実行時に依存を追加するオプションもあります。一時的な検証用途には有用ですが、Skillに同梱する場合は次の点がデメリットとなります。
これらを避けるため、本記事ではスクリプト内に依存関係を閉じ込められるPEP 723を採用しています。Agent Skillsのドキュメントでも、Skillに同梱するスクリプトの設計指針としてSelf-contained scriptsが紹介されており、その実装方法の一例としてPEP 723が挙げられています。
When you need reusable logic, bundle a script in scripts/ that declares its own dependencies inline. The agent can run the script with a single command — no separate manifest file or install step required.
「依存関係をスクリプト内に宣言し、別途のマニフェストやインストール手順なしに1コマンドで実行できる」という方針は、PEP 723 と uv run の組み合わせで実現できる構成と一致しています。uv の公式ドキュメントにも、同様の趣旨の説明があります。
The inline metadata format allows the dependencies for a script to be declared in the script itself.
（中略）
uv will automatically create an environment with the dependencies necessary to run the script
スクリプト自身に依存関係を宣言でき、uv が必要な環境を自動的に構築するため、利用者やエージェントが仮想環境を意識的に管理する必要がない、という構造です。
なお、PEP 723 メタデータの解決をサポートするツールは uv だけではなく、pipx でも実行可能です。本記事では uv を前提に解説しますが、利用可能なツールに合わせて選択できます。
また、uv run で解決された依存パッケージは、プロジェクトディレクトリではなく uv のキャッシュディレクトリ（Linux/ で $HOME/.cache/uv）に配置されます。複数のSkillから同じパッケージが参照される場合もキャッシュが再利用されるため、初回以降の起動は高速です。
業界標準として確立しているわけではありませんが、Skill同梱スクリプトを扱う際の選択肢として把握しておく価値はあると考えています。
実際にPEP 723を利用してSkillを構成し、動作を確認します。
本記事ではサンプルとして、Excelファイル（.xlsx）の内容を読み取って表示するSkill pep-723-demo を作成します。シートを順に走査し、内容をタブ区切りで標準出力に表示するシンプルなスクリプトを同梱し、依存ライブラリの openpyxl をPEP 723メタデータで宣言します。
なお、本記事では Claude Code を利用しますが、Skillsの仕組みは Codex CLI や Gemini CLI でも共通しており、Skillの配置先ディレクトリ（Claude Codeでは .claude/skills/、Codexでは .codex/skills/、Gemini CLIでは .gemini/skills/ もしくは .agents/skills/）を変えるだけで、同じSkillをそれぞれのエージェントから利用できます。
ファイルは2点のみです。
.claude/skills/pep-723-demo/
├── SKILL.md
└── scripts/
└── show_excel.py
pyproject.toml や .venv は配置せず、依存関係は show_excel.py の中に記述します。
scripts/show_excel.py の内容は次のとおりです。
# /// script
# requires-python = ">=3.13"
# dependencies = [
# "openpyxl>=3.1.5"
# ]
# ///
"""Print the contents of an Excel workbook."""
from __future__ import annotations
import sys
from pathlib import Path
from openpyxl import load_workbook
def main() -> int:
if len(sys.argv) != 2:
print("usage: show_excel.py workbook.xlsx", file=sys.stderr)
return 2
workbook_path = Path(sys.argv[1])
workbook = load_workbook(workbook_path, data_only=True)
for sheet in workbook.worksheets:
print(f"# {sheet.title}")
for row in sheet.iter_rows(values_only=True):
print("\t".join("" if value is None else str(value) for value in row))
return 0
if __name__ == "__main__":
raise SystemExit(main())
Skillから呼び出される利用形態を想定し、非対話的に動作する構成としています。
SKILL.md 側の記述は最小限に留めています。
---
name: pep-723-demo
description: Excel ファイル（.xlsx）の内容を表示する必要があるときに使う。
---
# PEP 723 Excel Script
## 概要
Excel ファイルの内容を表示します。
依存関係はスクリプト内に書いてあります。
`uv run --script` で実行します。
## 使い方
第1引数に Excel ファイルを指定します。
```bash
uv run --script scripts/show_excel.py path/to/workbook.xlsx
```
`uv add` は不要です。
`openpyxl` は `show_excel.py` の metadata から解決されます。
uv sync の手順、専用venv、グローバル環境に関する注意書きは記載していません。Skillの説明は実行コマンド1行のみで完結しています。
Excelファイルを用意し、Claude Codeにスキルを指定して、「xxディレクトリ内にあるExcelを読み取って簡単に説明してください」と依頼します。結果、SKILL.md に記載された手順に従って uv run –script でスクリプトを実行しました。
※ 本記事で読み込ませているExcelは生成AIで作成したダミーデータ（架空の従業員エンゲージメント調査）であり、実在の組織・個人の情報は含まれていません。
初回実行時は uv がメタデータを読み取り、必要なPythonと openpyxl を解決するため若干の時間を要しますが、2回目以降はキャッシュが効くため十分な速度で起動します。
利用者から見ると、エージェントに依頼するだけで結果が得られています。事前の uv sync やvenvの有効化、グローバル環境へのインストールはいずれも不要です。
実際に運用して感じた利点と留意点を整理します。
| 観点 | 内容 |
|---|---|
| 依存関係の場所 | スクリプト内で完結し、依存定義の所在が明確 |
| 事前準備 | uv run –script のみで動作し、追加の手順が不要 |
| SKILL.md の記述量 | 実行コマンドのみで完結し、説明が簡潔になる |
| Skillの可搬性 | ディレクトリ単位でコピーするだけで他環境でも動作する |
| 実行環境への影響 | グローバル環境や既存のvenvに影響を与えない |
特に意義が大きいと感じているのは、次の2点です。
実行環境への影響がない点
依存パッケージは uv のキャッシュディレクトリに隔離されるため、グローバル環境や既存のvenvを変更することなくSkillを実行できます。Skillを試験的に導入する場合や、複数のSkillを並行して利用する場合でも、環境を汚さずに済みます。
SKILL.md を簡潔に保てる点
Skillsは段階的に読み込まれる仕組みですが、SKILL.md 本文はコンテキストを消費するため、説明が短くなるほどエージェントが本来の判断に利用できるトークンが増えます。さらに、SKILL.md の記述が短く明快であるほど、エージェントが手順を取りこぼさずに意図どおりの動作を取りやすくなります。前段で触れたとおり、指示が複雑になるほど忠実に守られる保証は弱くなるため、説明を簡潔に保てることはSkillの動作の安定性に直結します。
採用前に確認しておきたい点も挙げておきます。
いずれも重大な障害となるものではありませんが、導入時には把握しておくことを推奨します。
Skillに同梱するPythonスクリプトの依存関係をPEP 723で記述することで、次の状態を実現できました。
pyproject.toml で厳密に管理したい場面や、複数のスクリプト間で依存関係を共有したい場面では、他の選択肢が適している場合もあります。一方で、Skillに小規模な補助スクリプトを同梱する用途では、PEP 723 と uv run –script の組み合わせは扱いやすい選択肢のひとつだと言えます。
依存関係の管理に課題を感じている場合は、検討対象に加えていただければと思います。
Tech Funでは、お客様のフェーズに合わせ、生成AI活用に向けた支援を3つのパックでご提供しています。
生成AIに限らず、Web・業務システム開発やインフラ設計など、技術領域を問わずご相談を承っています。「何から始めれば良いか分からない」という段階でも構いませんので、ぜひお気軽にお問い合わせください。
