スキルスクリプトの実行

本レッスンでできること

run_skill_script ツールを使用して、スキルディレクトリ以下の実行可能スクリプトを実行する
スクリプトにコマンドライン引数を渡す
スクリプト実行時の作業ディレクトリのコンテキストを理解する
スクリプト実行エラーと終了コードを処理する
スクリプトのパーミッション設定とセキュリティメカニズムを習得する

現在の課題

AI に特定スキルの自動化スクリプトを実行させたい（例：プロジェクトのビルド、テストの実行、アプリのデプロイなど）。しかし、スクリプトの呼び出し方法が不明だったり、実行時にパーミッションエラーやスクリプトが見つからないなどの問題に遭遇したりしているかもしれません。

この機能を使う場面

自動化ビルド: スキルの build.sh や build.py を実行してプロジェクトをビルドする
テスト実行: テストスイートをトリガーしてカバレッジレポートを生成する
デプロイフロー: デプロイスクリプトを実行してアプリを本番環境に公開する
データ処理: ファイルを処理したり、データ形式を変換するスクリプトを実行する
依存関係のインストール: 依存関係をインストールするスクリプトを実行する

コア概念

run_skill_script ツールを使用すると、スキルディレクトリのコンテキストで実行可能スクリプトを実行できます。これにより以下のメリットが得られます：

正しい実行環境: スクリプトはスキルディレクトリで実行されるため、スキルの設定とリソースにアクセスできる
自動化ワークフロー: スキルが一連の自動化スクリプトを含み、繰り返しの操作を削減できる
パーミッションチェック: 実行権限を持つファイルのみ実行され、通常のテキストファイルの誤実行を防ぐ
エラー検出: スクリプトの終了コードと出力をキャプチャし、デバッグを容易にする

スクリプト発見ルール

プラグインはスキルディレクトリ以下を再帰的に実行可能ファイルを検索します（最大深度は 10 層）：

ディレクトリのスキップ: 隠しディレクトリ（. で始まるもの）、node_modules、__pycache__、.git、.venv など
実行可能チェック: 実行権限があるファイル（mode & 0o111）のみがスクリプトリストに含まれる
相対パス: スクリプトパスはスキルディレクトリからの相対パス（例: tools/build.sh）

利用可能なスクリプトを先に確認

実行する前に、まず get_available_skills を使用してスキルのスクリプトリストを確認してください：

docker-helper (project)
  Docker コンテナ化とデプロイガイド [scripts: build.sh, deploy.sh]

ハンズオン

ステップ 1: スキルスクリプトの実行

docker-helper スキルに build.sh スクリプトが含まれていると仮定します：

ユーザー入力：
docker-helper の build.sh を実行してください

システム応答：
Building Docker image...
Successfully built abc123def456
Tagged as myapp:latest

確認できること: スクリプトの出力内容が応答に表示されます。

スクリプト実行時の作業ディレクトリはスキルディレクトリに切り替わるため、build.sh はスキルの Dockerfile などのリソースに正しくアクセスできます。

ステップ 2: コマンドライン引数の渡し方

多くのスクリプトは引数をサポートしています。例えば、deploy.sh で環境を指定する必要がある場合：

ユーザー入力：
docker-helper の deploy.sh を実行してください。引数は production です

システム応答：
Deploying to production environment...
Uploading image to registry...
Deployment successful: https://myapp.example.com

複数の引数も渡せます：

ユーザー入力：
deploy.sh を使用してデプロイしてください。引数は staging と --force です

システム応答：
Deploying to staging environment (--force mode)...
Skipping validation...
Deployment successful

確認できること: スクリプトは引数を受け取って、それに応じた操作を実行します。

ステップ 3: ネストされたディレクトリ内のスクリプト実行

スクリプトはスキルのサブディレクトリにある場合もあります（例: tools/setup.sh）：

ユーザー入力：
docker-helper の tools/setup.sh を実行してください

システム応答：
Setting up Docker environment...
✓ Docker network created
✓ Volume mounted
✓ Environment configured

相対パスは常にスキルディレクトリからの相対パスであり、スクリプトの実際の位置がどれだけ深くても問題ありません。

確認できること: ネストされたディレクトリ内のスクリプトも正しく実行されます。

ステップ 4: スキルが存在しないエラーの処理

間違ったスキル名を入力した場合：

ユーザー入力：
docker-asistant の build.sh を実行してください

システム応答：
Skill "docker-asistant" not found. Did you mean "docker-helper"?

プラグインはあいまい一致に基づいて正しいスキル名を提案します。まず get_available_skills を呼び出して利用可能なスキルを確認できます。

確認できること: エラーメッセージと正しい名前の提案が表示されます。

ステップ 5: スクリプトが存在しないエラーの処理

スクリプトがスキルのスクリプトリストにない場合：

ユーザー入力：
docker-helper の run.sh を実行してください

システム応答：
Script "run.sh" not found in skill "docker-helper". Did you mean "build.sh"?
Available scripts: build.sh, deploy.sh

プラグインは利用可能なすべてのスクリプトを一覧表示し、正しいスクリプト名を選択しやすくします。

確認できること: エラーメッセージと利用可能なスクリプトリストが表示されます。

ステップ 6: スクリプト実行失敗の理解

スクリプトが失敗した場合（終了コードが 0 以外）、プラグインはエラー情報を返します：

ユーザー入力：
docker-helper の build.sh を実行してください

システム応答：
Script failed (exit 1): Dockerfile not found in /path/to/skill

エラー情報には以下が含まれます：

終了コード: exit 1 はスクリプトがゼロ以外の状態で終了したことを示す
エラー出力: スクリプトの stderr または stdout の内容
失敗の原因: スクリプトの具体的なエラーメッセージ

確認できること: 問題を特定するための詳細なエラー情報が表示されます。

チェックポイント ✅

[ ] スキルディレクトリ以下の実行可能スクリプトを実行できますか？
[ ] スクリプトにコマンドライン引数を渡せますか？
[ ] スクリプト実行時の作業ディレクトリのコンテキストを理解していますか？
[ ] スクリプト実行エラーを識別して処理できますか？
[ ] スクリプトのパーミッション設定を確認する方法を知っていますか？

よくある落とし穴

トラップ 1: スクリプトに実行権限がない

新しいスクリプトを作成したが実行権限を設定し忘れた場合、スクリプトリストに表示されません。

エラーの兆候：

Available scripts: build.sh  # 新しいスクリプト new-script.sh がリストにない

原因: ファイルに実行権限がない（mode & 0o111 が false）。

解決策: ターミナルで実行権限を設定します：

bash

chmod +x .opencode/skills/my-skill/new-script.sh

確認: 再度 get_available_skills を呼び出してスクリプトリストを確認してください。

トラップ 2: スクリプトパスの誤り

スクリプトパスはスキルディレクトリからの相対パスでなければならず、絶対パスや親ディレクトリ参照は使用できません。

間違った例：

bash

# ❌ エラー: 絶対パスを使用
docker-helper の /path/to/skill/build.sh を実行してください

# ❌ エラー: 親ディレクトリへのアクセスを試みる（セキュリティチェックは通過しますが、パスが間違っています）
docker-helper の ../build.sh を実行してください

正しい例：

bash

# ✅ 正しい: 相対パスを使用
docker-helper の build.sh を実行してください
docker-helper の tools/deploy.sh を実行してください

原因: プラグインはパスの安全性を検証し、ディレクトリトラバーサル攻撃を防止します。同時に、相対パスはスキルディレクトリに基づいています。

トラップ 3: スクリプトが作業ディレクトリに依存している

スクリプトが現在のディレクトリがプロジェクトルートではなくスキルディレクトリであると仮定している場合、実行に失敗する可能性があります。

間違った例：

bash

# skill ディレクトリ内の build.sh
#!/bin/bash
# ❌ エラー: 現在のディレクトリがプロジェクトルートであると仮定
docker build -t myapp .

問題: 実行時、現在のディレクトリはスキルディレクトリ（.opencode/skills/docker-helper）であり、プロジェクトルートではありません。

解決策: スクリプトは絶対パスを使用するか、プロジェクトルートを動的に特定する必要があります：

bash

# ✅ 正しい: 相対パスを使用してプロジェクトルートを特定
docker build -t myapp ../../..

# または: 環境変数や設定ファイルを使用
PROJECT_ROOT="${SKILL_DIR}/../../.."
docker build -t myapp "$PROJECT_ROOT"

説明: スキルディレクトリにはプロジェクトの Dockerfile がない場合があるため、スクリプトは自分でリソースファイルを特定する必要があります。

トラップ 4: スクリプト出力が長すぎる

スクリプトが大量のログを出力する場合（例：npm install のダウンロード進捗）、応答が非常に長くなる可能性があります。

兆候：

bash

システム応答：
npm WARN deprecated package...
npm notice created a lockfile...
added 500 packages in 2m
# 数百行の出力がある場合がある

推奨事項: スクリプトは出力を簡潔にし、重要な情報のみを表示するようにすべきです：

bash

#!/bin/bash
echo "Installing dependencies..."
npm install --silent
echo "✓ Dependencies installed (500 packages)"

本レッスンのまとめ

run_skill_script ツールを使用すると、スキルディレクトリのコンテキストで実行可能スクリプトを実行できます。以下がサポートされています：

引数の渡し方: arguments 配列を通じてコマンドライン引数を渡す
作業ディレクトリの切り替え: スクリプト実行時に CWD がスキルディレクトリに切り替わる
エラー処理: 終了コードとエラー出力をキャプチャし、デバッグを容易にする
パーミッションチェック: 実行権限を持つファイルのみを実行する
パスの安全性: スクリプトパスを検証し、ディレクトリトラバーサルを防止する

スクリプト発見のルール：

スキルディレクトリを再帰的にスキャンし、最大深度は 10 層
隠しディレクトリと一般的な依存ディレクトリをスキップ
実行権限を持つファイルのみを含める
パスはスキルディレクトリからの相対パス

ベストプラクティス：

スクリプト出力は簡潔にし、重要な情報のみを表示する
スクリプトは現在のディレクトリがプロジェクトルートであると仮定しない
新しいスクリプトには chmod +x を使用して実行権限を設定する
まず get_available_skills を使用して利用可能なスクリプトを確認する

次のレッスンの予告

次のレッスンでは スキルファイルの読み込み を学習します。
以下の内容を学びます：
read_skill_file ツールを使用してスキルのドキュメントと設定にアクセスする
パスセキュリティチェックメカニズムを理解し、ディレクトリトラバーサル攻撃を防止する
ファイル読み込みと XML コンテンツインジェクションのフォーマットを習得する
スキルでサポートファイル（ドキュメント、サンプル、設定など）を整理する方法を学ぶ

付録: ソースコード参照

展開してソースコードの場所を表示

更新日時: 2026-01-24

機能	ファイルパス	行番号
RunSkillScript ツール定義	`src/tools.ts`	137-198
findScripts 関数	`src/skills.ts`	59-99

主要な型：

Script = { relativePath: string; absolutePath: string }：スクリプトのメタデータ、相対パスと絶対パスを含む

主要な定数：

最大再帰深度：10（skills.ts:64）- スクリプト検索の深さ制限
スキップディレクトリリスト：['node_modules', '__pycache__', '.git', '.venv', 'venv', '.tox', '.nox']（skills.ts:61）
実行権限マスク：0o111（skills.ts:86）- ファイルが実行可能かどうかをチェック

主要な関数：

RunSkillScript(skill: string, script: string, arguments?: string[])：スキルスクリプトを実行し、引数の渡し方と作業ディレクトリの切り替えをサポート
findScripts(skillPath: string)：スキルディレクトリ以下の実行可能ファイルを再帰的に検索し、相対パスでソートして返す

ビジネスルール：

スクリプト実行時に作業ディレクトリをスキルディレクトリに切り替える（tools.ts:180）：$.cwd(skill.path)
スキルの scripts リストにあるスクリプトのみを実行する（tools.ts:165-177）
スクリプトが存在しない場合、利用可能なスクリプトリストを返し、あいまい一致の提案をサポート（tools.ts:168-176）
実行失敗時に終了コードとエラー出力を返す（tools.ts:184-195）
隠しディレクトリ（. で始まるもの）と一般的な依存ディレクトリをスキップする（skills.ts:70-71）

スキルスクリプトの実行 ​

本レッスンでできること ​

現在の課題 ​

この機能を使う場面 ​

コア概念 ​

ハンズオン ​

ステップ 1: スキルスクリプトの実行 ​

ステップ 2: コマンドライン引数の渡し方 ​

ステップ 3: ネストされたディレクトリ内のスクリプト実行 ​

ステップ 4: スキルが存在しないエラーの処理 ​

ステップ 5: スクリプトが存在しないエラーの処理 ​

ステップ 6: スクリプト実行失敗の理解 ​

チェックポイント ✅ ​

よくある落とし穴 ​

トラップ 1: スクリプトに実行権限がない ​

トラップ 2: スクリプトパスの誤り ​

トラップ 3: スクリプトが作業ディレクトリに依存している ​

トラップ 4: スクリプト出力が長すぎる ​

本レッスンのまとめ ​

次のレッスンの予告 ​

付録: ソースコード参照 ​

スキルスクリプトの実行

本レッスンでできること

現在の課題

この機能を使う場面

コア概念

ハンズオン

ステップ 1: スキルスクリプトの実行

ステップ 2: コマンドライン引数の渡し方

ステップ 3: ネストされたディレクトリ内のスクリプト実行

ステップ 4: スキルが存在しないエラーの処理

ステップ 5: スクリプトが存在しないエラーの処理

ステップ 6: スクリプト実行失敗の理解

チェックポイント ✅

よくある落とし穴

トラップ 1: スクリプトに実行権限がない

トラップ 2: スクリプトパスの誤り

トラップ 3: スクリプトが作業ディレクトリに依存している

トラップ 4: スクリプト出力が長すぎる

本レッスンのまとめ

次のレッスンの予告

付録: ソースコード参照