skills-sync

Skills Sync

AI エージェントのスキルを管理および同期するために使用する skills_sync CLI ツールのスキルです。

コンテキスト

skills_sync ツールは設定ファイルを読み取り、ユーザーのローカルスキルディレクトリ（通常は ~/.agents/skills）をリモートリポジトリと同期します。

設定の優先順位：

1. プロジェクト固有：./skills.yaml
2. グローバル：~/.config/skills_sync/skills.yaml

重要な注意：skills-optimizer などの別のスキルが skills.yaml の設定を変更しても、その変更は自動的には適用されません。新しいスキルをダウンロードし、削除されたスキルを削除して、除外設定を適用するには、必ず skills_sync sync を実行してください。

コマンド

skills_sync の主なコマンドは次のとおりです。

skills_sync sync

設定ファイルに基づいてスキルを同期します。デフォルトでは、既存のスキルを先に削除してから「クリーン」同期を行います。

• 使用するタイミング：~/.config/skills_sync/skills.yaml を変更した直後、またはスキルディレクトリが設定と一致していることを徹底的に確認したいとき。
• オプション：
  • --clean：（デフォルト：true）インストール前に既存のスキルを削除します。
  • --no-clean：削除をスキップします。処理は速くなりますが、孤立したスキルが残る場合があります。
  • --agent <name>：対象のエージェントを指定します（デフォルト：antigravity）。すべてを対象にするには * を使用します。
• 動作：リポジトリを取得し、包含・除外設定を適用して、ローカルにインストールされたスキルが設定と一致するようにします。

skills_sync update

先に何も削除せずに、設定済みのスキルの最新バージョンを確認してインストールします。

• 使用するタイミング：完全な同期を行わず、手軽にスキルの更新を確認したいとき。
• オプション：
  • --agent <name>：対象のエージェントを指定します（デフォルト：antigravity）。
• 動作：設定済みのすべての対象パスで npx skills update を実行します。

skills_sync list

現在の設定と、ローカルにインストールされているスキルを一覧表示します。

• 使用するタイミング：現在の設定内容と実際にインストールされている内容を確認するとき、または現在の構成をユーザーに提示するとき。

skills_sync config

ユーザーのデフォルトエディター（または $EDITOR で指定されたエディター）で skills.yaml 設定ファイルを開きます。

• 使用するタイミング：AI に編集させるのではなく、ユーザーが設定を手動で編集したいとき。

skills_sync init

存在しない場合に、デフォルトのグローバル設定ファイル（~/.config/skills_sync/skills.yaml）を生成します。

• 使用するタイミング：通常、ファイルが存在しない場合の初回セットアップでのみ必要です。

skills.yaml の仕様

skills.yaml ファイルでは、インストールするスキルとそのインストール先を定義します。

対象ディレクトリ（ルートキー）

• global：ここに記載されたスキルは、グローバルに ~/.agents/skills へインストールされます。
• <path>（例：~/Git/my-project）：ここに記載されたスキルは、指定されたプロジェクトディレクトリ内の .agents/skills にローカルインストールされます。参照先のパスがユーザーのファイルシステムに存在しない場合、skills_sync はエラーを出さずにスキップします。

スキルソース

各対象ディレクトリの下で、スキルを取得するソースを定義します。

• owner/repo：GitHub リポジトリの省略表記です。
• https://github.com/owner/repo/tree/branch：リポジトリ内の特定のブランチまたはフォルダーです。
• /local/path/to/skills：スキルを含むローカルディレクトリです。

スキルの選択（フィルター）

各ソースに対して、インストールするスキルを決めるフィルターのリストを指定できます。

• 空／Null：フィルターが指定されていない場合（空のキーのみの場合）、ソース内のすべてのスキルがインストールされます。
• 特定の名前：スキルの正確な名前を指定します（例：flutter-expert）。
• ワイルドカード（*）：複数のスキルに一致するワイルドカードを使用します（例：flutter-* は flutter- で始まるすべてのスキルをインストールします）。
• 除外（!）：パターンの先頭に ! を付けて、一致するスキルを除外します（例：!*-legacy は -legacy で終わるスキルをスキップします）。除外は包含より優先されます。

ワークフローとの統合（例：skills-optimizer の場合）

ユーザーの skills.yaml を変更する場合（スキルの追加や削除など）：

1. 設定ファイルを特定する：プロジェクトローカルに skills.yaml があるか確認します。ない場合は、グローバルの ~/.config/skills_sync/skills.yaml を使用します。
2. 設定を変更する：特定した skills.yaml ファイルを、ユーザーの指示または最適化ロジックに従って編集します。
3. 変更を適用する：コマンドラインから skills_sync sync を実行し、変更が反映されるようにします。
4. 確認する：必要に応じて skills_sync list を実行し、インストール内容が期待どおりか確認します。

ベストプラクティス

• sync を自動実行しない：ユーザーの明示的な許可なしに、絶対に skills_sync sync を実行しないでください。設定を変更した後、変更を適用するかどうかを必ずユーザーに確認してください。
• 設定の透明性を保つ：skills.yaml を黙って変更しないでください。追加または削除するスキルとその理由を明確に説明し、ユーザーがインストール済みのスキルを常に把握できるようにしてください。
• ファイルパスを推測しない：インストール処理、クローン、コピーは必ず skills_sync ツールに任せてください。ツールを使わずに進めるよう明示的に依頼された場合を除き、ZIP ファイルを手動でダウンロードしたり、git でリポジトリを ~/.agents/skills にクローンしたりしないでください。
• 完了を待つ：大きなリポジトリのダウンロードが必要な場合、skills_sync sync の実行には時間がかかることがあります。コマンドが完了するまで待ってください。
• ドライラン：--dry-run を使うと、実際には実行せずに skills_sync が実行するコマンドを確認できます。