skill-installer

ローカルスキルインストーラー

使用する場合

ユーザーから、ワークスペース内の特定のローカルスキルを検証、インストール、パッケージ化、削除、または復元するよう依頼された場合に使用します。スキルを作成しただけでは、インストール、別のスキルの上書き、検出された候補すべてのインストール、またはグローバルなエージェント設定の変更は許可されません。

対象範囲とセットアップ

管理対象のインストール先があるワークスペースから実行してください。インストーラー、バリデーター、パッケージャーに渡すパスは、現在のワークスペース内を指している必要があります。シンボリックリンクのパス、およびスキルツリー内のリンクや特殊ファイルは拒否されます。スクリプトは ./skills、./.claude/skills、./.skill-installer/data（バックアップ／ステージング／ログ）、./dist（ZIP）を使用します。特定ユーザーの Windows ディレクトリを対象としたり、グローバルにインストールしたりすることはありません。

ヘルパーを使用する前に、適切に分離された Python 環境へ scripts/requirements.txt をインストールしてください。PyYAML が必要です。形式不正、キーの重複、またはマッピング以外のフロントマターは、ヒューリスティックな復元を試みずに拒否されます。検出されたスキルと、そこに含まれるプログラムは、確認が済むまで信頼できないものとして扱ってください。検証で確認するのは構造と一部の機密ファイル名です。スキルの安全性を保証したり、すべての認証情報を検出したりするものではありません。

ワークフロー

作業ディレクトリを対象のワークスペースに設定したまま、このスキルからの相対パスで同梱スクリプトのパスを解決してください。

# Read-only structural check of an explicitly selected local directory.
python /path/to/skill-installer/scripts/validate_skill.py ./incoming/my-skill

# Plan the installation. This installation dry-run creates no installation artifacts.
python /path/to/skill-installer/scripts/install_skill.py --source ./incoming/my-skill --dry-run --json

# Execute within the user's existing authorization.
python /path/to/skill-installer/scripts/install_skill.py --source ./incoming/my-skill --json

インストール前に、同梱されているすべてのファイルを確認してください。対象のワークスペース、ソース全体、既存のインストール先、上書きによる影響を特定してください。--name に指定できるのは、ハイフンで区切られた、1～64 文字の小文字 ASCII 識別子です。無効な名前は、別のスキル名に黙って書き換えられることなく、エラーになります。明示的に許可された上書きの場合にのみ --force を追加してください。最初にバックアップが作成されますが、複数ディレクトリへのインストールはトランザクションではありません。失敗すると一部だけインストールされた状態になり、確認と復元が必要になる場合があります。

このヘルパーは検証後、ステージング経由でファイルをコピーし、実行ビットを含む決定論的な SHA-256 ツリーダイジェストを比較します。ワークスペースの .claude/skills にツリー全体を登録し、内容が一致することを確認して、./dist に ZIP を作成します。レジストリとの統合は、このバンドルに含まれていない外部コードに依存するため、明示的にスキップされます。また、外部の scan_registry.py が自動的に実行されることもありません。作成された ZIP は手動アップロード用の成果物であり、ホストされたアカウントに何かが自動インストールされるわけではありません。

検出とパッケージ化

# Detection defaults to the current workspace; it does not install candidates.
python /path/to/skill-installer/scripts/detect_skills.py --path ./incoming
python /path/to/skill-installer/scripts/install_skill.py --detect --json

# Package an individually reviewed skill and verify local archives.
python /path/to/skill-installer/scripts/package_skill.py --source ./incoming/my-skill --output ./dist
python /path/to/skill-installer/scripts/package_skill.py --verify --output ./dist

detect_skills.py --all は検出対象をユーザーディレクトリや旧式の Windows パスにまで広げます。ユーザーがその範囲の読み取りを依頼した場合にのみ使用してください。検出結果の出力には、ローカルのファイル名やメタデータが含まれる場合があります。--detect --auto、--reinstall-all、パッケージャーの --all、--health --repair は一括操作です。内容を確認し、許可された選択対象とワークスペースに対してのみ使用してください。文書に自動修復が記載されているというだけで実行してはいけません。ZIP のパッケージ化では、必要な data/ リソースは保持され、既知のキャッシュは除外されます。また、一部の機密ファイル名は拒否されます。同じスキル名の既存の通常アーカイブは、アトミックに置き換えられます。ファイル名のフィルターだけでは機密情報を含まないことを保証できないため、共有前にアーカイブを確認してください。

メンテナンス

--status、--health、--log [N] は、ワークスペースへのインストール状況とローカルの履歴を確認します。外部レジストリの状態は認証されません。読み取り専用の --health は、構造上の問題や登録上の問題を報告します。正常という結果は、スクリプトが動作することや安全であることを証明するものではありません。--health --repair は登録情報を変更する可能性があり、許可された修復範囲が必要です。ネストされたスキルは、自動修復ではなく明示的なインストールが必要な場合があります。

--uninstall NAME は、正規のコピーをバックアップした後、そのワークスペースのスキルと登録情報を削除します。個別にパッケージ化された ZIP は保持されます。--rollback NAME は、最新の該当バックアップを検証して復元し、再登録します。バックアップの新しさと現在のデータを事前に確認してください。バックアップはローカルにスキルごとに最大 5 件保持され、ログには直近 500 件の操作が保持されますが、いずれもデバイス外の復旧手段ではありません。登録情報のみのデータや同時編集については、手動での復旧が必要になる場合があります。

--dry-run はインストールでのみサポートされています。これをアンインストール、ロールバック、修復、再インストールと組み合わせると、変更が行われる前に拒否されます。このフラグから管理操作のプレビューができると決して推測しないでください。

例

ローカルの incoming/my-skill ツリーの場合、まず SKILL.md、スクリプト、参照資料、ライセンス、データを確認し、バリデーターとドライランを実行してから、ユーザーが要求した場合にインストールしてください。成功後、skills/my-skill と .claude/skills/my-skill のツリー全体を比較し、dist/my-skill.zip を確認してください。元のタスクで必要な権限とデータ範囲を使用して、レビュー済みのプログラムのみを実行してください。

制限事項

• これはローカルのワークスペース用ユーティリティであり、エンタープライズ向けのセキュリティ認証、汎用オーケストレーター、ホスト型製品との互換性の保証ではありません。対象クライアントの現在のスキル読み込み要件とアップロード要件は、別途確認してください。
• インストール時に、インストール済みの不明なスキルコードが実行されることはありません。ネイティブクライアントによる検出と実行、リモートアカウントへのインストール、外部レジストリの更新は、引き続き別の操作です。
• ツリーのダイジェストは整合性を確認するものであり、真正性を確認するものではありません。信頼でき、変更が行われていないローカルディレクトリで作業してください。このユーティリティはサンドボックスではなく、同時に発生するファイルシステムの競合や悪意のあるハードリンクを防ぐものではありません。
• 複数の対象への書き込み、バックアップのローテーション、修復、ロールバックは、一部のみ失敗することがあります。重要な状態については独立したバックアップを保持し、再試行する前に報告された失敗を確認してください。
• 数値によるバージョン比較は近似的なものであり、SemVer のプレリリース順序を完全には実装していません。これに基づく自動アップグレードやダウングレードの権限はありません。