ASDF Manager
このスキルにより、エージェントは asdf を使用してプロジェクトのツールバージョンと依存関係を管理できます。.tool-versions ファイルの作成・更新、プラグインのインストールと更新を処理し、サードパーティのプラグインをインストールする際に重要なセキュリティガードレールを適用します。
使用するタイミング
- プロジェクトがランタイム環境（例：Node.js、Python、Ruby、Go、Elixir、Rust）の管理に
asdfを使用している場合。 - リポジトリに
.tool-versionsファイルが存在するか、ユーザーがマルチランタイムのバージョン管理を設定したい場合。 - ユーザーが「すべてのツールをアップデート」または特定のツールを「最新」バージョンに設定するよう要求した場合。
- ユーザーが
asdfで管理可能な新しい開発ツール、言語ランタイム、またはユーティリティを追加したい場合。
使用しないタイミング
- プロジェクトが他のパッケージ/ランタイムマネージャー（
mise、fnm、nvm、pyenv、rbenv、gvm、asdf-vmなど）を使用するように明示的に設定されている場合。 - システムレベルのパッケージマネージャー（
brew、apt、pacman、dnfなど）で管理すべきパッケージをインストールする場合で、プロジェクトごとのバージョン固定が不要な場合。
入力
| 入力 | 必須 | 説明 |
|---|---|---|
| ツール名 | はい | ランタイムまたはツールの名前（例：nodejs、python、golang） |
| バージョン | いいえ | 設定またはインストールする特定のバージョン（例：18.16.0、latest、system） |
| アクション | はい | 実行する操作：update-all、install-tool、set-version、add-plugin |
| グローバル | いいえ | true に設定すると、ローカルプロジェクトディレクトリではなく、グローバル（$HOME/.tool-versions）に設定を適用します。 |
ワークフロー
ステップ 1: ASDF 環境の検出と検証
asdf コマンドを実行する前に、エージェントの現在のシェル環境で asdf がインストールされ、アクセス可能であることを確認します。
which asdfまたはasdf --versionを実行します。asdfが見つからない場合、一般的なインストールパス（$HOME/.asdf/bin/asdfや/opt/homebrew/bin/asdfなど）を確認します。インストールされているが source されていない場合は、source する方法をユーザーに案内します。- システムに
asdfが完全に存在しない場合、スキルは早期に終了し、ユーザーに次のように伝えます。 「https://asdf-vm.com/guide/getting-started.html からインストールしてください。」- 理由:
asdfコア実行ファイルがインストールされていないとスキルは続行できません。役立つインストール URL とともに早期に失敗することで、スムーズなユーザーセットアップ体験を保証します。
- 理由:
ステップ 2: 「すべてのツールを更新」要求への対応
ユーザーがすべてのツールを最新バージョンに更新するよう要求した場合：
.tool-versionsファイルを見つけます（通常はプロジェクトルート、または親ディレクトリを確認します）。.tool-versionsファイルで定義されているツールのリストを読み取ります。- 見つかった各ツールに対して、以下のコマンドを実行して最新バージョンを自動的に解決し書き込みます：
asdf set <tool-name> latest- 理由:
asdf set <tool-name> latestを使用する方が.tool-versionsを手動で編集するよりも正確で堅牢です。これはasdfが実際の解決済みの最新利用可能バージョンを取得し、必要に応じてダウンロード/コンパイルし、正確な静的バージョン文字列を.tool-versionsファイルに書き戻すためです。
- 理由:
ステップ 3: プラグインの検索と追加（コミュニティインデックスの確認）
ユーザーがツール/プラグインのインストールを要求した場合：
- まず、プラグインがすでにインストールされているか確認するために次を実行します：
すでにインストールされている場合は、ステップ 5 に進みます。asdf plugin list - プラグインがインストールされていない場合、公式の
asdfコミュニティインデックスに存在するか確認します：
出力をフィルタリングまたは検索して、目的のツール名を見つけます。asdf plugin list all- 理由: コミュニティインデックスを確認することで、キュレーションされレビューされたプラグインのみをインストールすることが保証されます。公式インデックス外のサードパーティプラグインは、カスタムフックスクリプトを実行し、ホストシステム上で信頼できないバイナリをコンパイル/インストールする権限を持ちます。
ステップ 4: カスタム/非コミュニティプラグインに対する厳格なセキュリティチェック
要求されたツールが公式コミュニティインデックス（asdf plugin list all の出力）に存在しない場合：
- エージェントにオンラインで検索するよう指示（検索エンジン、GitHub、ドキュメントなど）し、
asdfプラグインの正しい正当なソースリポジトリ URL を見つけます。 - ユーザーの明示的な許可なしにカスタムプラグインのインストールを進めてはいけません。 これは重要なセキュリティ境界です。
- 構造化された許可リクエストをユーザーに作成し、以下を含めます：
- プラグインが公式の
asdfコミュニティリポジトリリストにないという明確な警告。 - 見つかったプラグインの正確なリポジトリ URL（例：
https://github.com/someone/asdf-mytool）。 - サードパーティプラグインのセキュリティへの影響に関する警告（インストール/使用中に任意のシェルコードを実行する可能性があること）。
- インストールを続行する許可を求める明示的なプロンプト。
- プラグインが公式の
- ユーザーが同意した場合にのみ、確認された URL を使用してカスタムプラグインの追加を進めます：
asdf plugin add <tool-name> <plugin-url>
ステップ 5: ツールバージョンのインストールと設定
プラグインがインストール/追加されたら：
- ユーザーが特定のバージョンを要求した場合、それをインストールします：
それ以外の場合は、最新バージョンをインストールします：asdf install <tool-name> <version>asdf install <tool-name> latest - プロジェクト設定にバージョンを書き込みます：
- ローカルプロジェクトのバージョン管理（デフォルト）：
asdf set <tool-name> <version-or-latest> - グローバルユーザーレベルのバージョン管理：
asdf set -u <tool-name> <version-or-latest>
- ローカルプロジェクトのバージョン管理（デフォルト）：
- インストール後に
asdf reshimを実行して、すべてのシムが更新され、新しくインストールされた実行ファイルがすぐに使用可能であることを確認します。
検証
-
asdf currentを実行して、新しく設定されたツールバージョンがディレクトリ内でアクティブであり、正しく解決されることを確認します。 -
.tool-versionsファイルが設定されたツールとバージョンと一致していることを確認します。 - 公式インデックス外で追加されたカスタムプラグインは、ユーザーの明示的な確認後にのみインストールされたことを確認します。
よくある落とし穴
| 落とし穴 | 解決策 |
|---|---|
エージェントシェルで asdf: command not found | asdf はインストールされているが、アクティブなシェルで source されていない可能性があります。asdf.sh（例：/opt/homebrew/opt/asdf/libexec/asdf.sh または $HOME/.asdf/asdf.sh）を見つけて source するか、/shims をエージェントコンテキストで動的に $PATH に追加します。 |
| インストール後、ツールの実行ファイルが動作しない | asdf reshim を実行してシムディレクトリラッパーを再生成し、シェルが新しいバイナリを見つけられるようにします。 |
| コンパイルツール不足によりインストールが失敗する | Ruby、Python、Erlang などの言語は asdf を使用してソースからコンパイルする場合、ローカルのビルド依存関係（gcc、openssl、make、libyaml など）が必要です。ビルドログに基づいて、不足している依存関係をユーザーに伝えます。 |
| 非対話型シェルが対話型プロンプトでブロックされる | asdf コマンドが非対話的に実行されるか、依存関係が事前に満たされていることを確認します。 |