manage-skills

まず最初に

1. 最初に CLI を解決し、表示されたパスを使います。 POSIX シェルで、これを 1 回実行します。

   D="$HOME/.skills-manager/bin"
   B="$D/skills-manager-cli"; [ -e "$B" ] || B="$B.exe"   # .exe on Windows
   if [ -s "$D/.version" ] && [ -x "$B" ]; then
     echo "$B"
   elif [ -s "$D/.version" ] || [ -e "$B" ]; then
     echo BRIDGE_BROKEN
   else
     P="$(command -v skills-manager-cli 2>/dev/null || true)"
     [ -x "$P" ] && echo "$P"
   fi
   

   表示されたパスを、以下のすべてのコマンドで $SM と書かれている箇所に 置き換えてください。 $SM をシェル変数として使い続けないでください。 実行するコマンドごとに新しいシェルが起動するため、ここで設定した変数は次の コマンドでは失われます。

   結果は次の 3 通りです。

   • ~/.skills-manager/bin 配下のパス — デスクトップアプリがこのコピーを 公開しています。.version スタンプは検証後にのみ付与されるため、常に ユーザーが実行中のアプリと一致します。これを使います。
   • BRIDGE_BROKEN — アプリが残したものはありますが、状態が整合していません。 スタンプのないバイナリ、または隣にバイナリのないスタンプのどちらかです。 いずれも、コピーが途中で失敗したときに残る状態です。ここで止めてください。 別の CLI を探しに行かないでください。そのバイナリは安全性修正より前のものかも しれず、このマシンには、そのバージョンと照合できるものが何もないデスクトップ アプリがあります。Skills Manager アプリを一度開くようユーザーに依頼してください。 アプリが CLI を再公開します。
   • PATH からのパス — ここには一度も公開されていないため、古いコピーを心配する 必要はありません。これは CLI のみのマシンです（サーバーへのインストール、 単体ダウンロード、手動ビルドしたバイナリなど）。これを使います。ただし、 デスクトップアプリもインストールされている場合、こちらのほうが古い可能性が あることに注意してください。

   何も表示されない場合、このスキルは適用されません。find-skills に切り替えるか、 Skills Manager のインストールをユーザーに案内してください。

2. 自分で出力を解析する場合は、必ず --json を渡してください。 整形済みの出力は ユーザー向け、JSON はあなた向けです。エラー時は終了コードが 0 以外になり、 stderr に ok=false、安定した code、および message が含まれます。

"$SM" --json skills list

デプロイが拒否された場合

こちらが所有していないものを上書きするデプロイは、無条件に拒否されます。 該当パスのファイルは削除されず、バッチ内のほかの処理も適用されません。 この失敗は機械可読なので、エラーメッセージではなく実際のパスを報告してください。

{"ok": false, "code": "TARGET_CONFLICT", "kind": "target_conflict",
 "message": "Refusing to deploy: 1 of 2 target(s) …",
 "details": {"conflicts": [{"path": "/Users/me/.claude/skills/db",
                            "reason": "is not a managed deployment"}]}}

どのパスが妨げになっているか、その内容には手を加えていないことをユーザーに伝え、 解決方法を 2 つ提示してください。そのパスをライブラリに取り込む（skills adopt） か、別の場所に移動してから再試行する方法です。ユーザーに代わって削除しては いけません。

基本的な考え方

すべてのエージェントが共有する中央ライブラリは ~/.skills-manager/skills/ に 1 つあります。各スキルにはソースメタデータ、プリセットへの所属、タグ、および エージェントのディレクトリにある 0 個以上の実際のデプロイが含まれます。 プリセットは再利用可能なグループです。複数のプリセットを同時にデプロイできます。

次の 3 つの状態は区別してください。

• ライブラリ：インストール／削除によって、Skills Manager がそのスキルを管理するかどうかを制御します。
• プリセットへの所属：presets add-skill/remove-skill はライブラリ内の整理のみを行います。
• デプロイ：skills deploy/undeploy と presets deploy/undeploy によって、エージェントが実際にスキルを参照できるかどうかを制御します。

内部的には、Git Backup との後方互換性のため、プリセットは引き続きシナリオとして保存されます。CLI と UI ではプリセットと呼びます。

インストール

# From skills.sh marketplace
"$SM" skills install vercel-labs/agent-skills@react-best-practices

# Any git URL (use /tree/branch/subpath form when the skill lives in a sub-directory)
"$SM" skills install https://github.com/anthropics/skills.git
"$SM" skills install https://github.com/foo/bar/tree/main/skills/baz

# Local folder
"$SM" skills install ./my-skill

# Force a source type when the ref is ambiguous
"$SM" skills install foo/bar --skillssh
"$SM" skills install ./looks-like/owner-repo --local

デフォルトではライブラリにのみ追加されます。スキルは DB に登録されますが、 どのエージェントにもまだ表示されません。対象範囲を明確にするため、続けて明示的に デプロイしてください。

"$SM" skills deploy <skill> --agent claude_code --agent codex

--sync と --sync-preset は、排他的なアクティブプリセットのワークフロー向けの レガシーなショートカットとして引き続き利用できます。

参照先の解決は決定的であり、パスの存在を推測しません。

1. ./、../、/、または ~/ で始まる → ローカルパス
2. :// を含む、.git で終わる、または git@ で始まる → Git URL
3. owner/repo、owner/repo/skill、または owner/repo@skill に一致する → skillssh
4. それ以外 → エラー。区別するには --local／--git／--skillssh を渡します。

インストール後は必ず skills list または skills show <name> で確認し、 スキルが正しく追加されたことを確かめてから、プリセット／同期の状態をユーザーに 報告してください。

検索

"$SM" --json skills search "react performance" --limit 5

各結果には、skills install にそのまま貼り付けられる install_ref、人気度の目安となる installs、および skills_sh_url が含まれています。インストールする前に、インストール数とともに上位1～3件を表示してください。インストール数が10K以上のものは実績が豊富で、100未満のものはソースリポジトリを慎重に確認する必要があります。

更新／確認

# Re-fetch one skill (git/skillssh re-clones, local/import re-imports source dir)
"$SM" skills update <skill-name-or-id>

# Re-fetch all eligible skills
"$SM" skills update --all

# Just probe remote revisions, don't touch files
"$SM" skills check --all

check は update に対応するドライランです。ローカルフォルダーからインストールされたスキルは、Git リモートではなく、そのフォルダーと比較されます。update_available はインポート後にフォルダーが変更されたことを意味し、source_missing はフォルダーが存在しないことを意味します。この確認は常に実行されます。Git リモートへの再接続を1時間以内は省略するキャッシュ（--force で無効化できます）は、この確認には適用されません。ウェブサイトのスキルは比較対象がないため、skipped: true を返します。

更新するとスキルのディレクトリ全体が置き換えられるため、新しいバージョンにないものがその中に書き込まれていると、削除されます。CLI がそのようなファイルを検出すると、何も適用せずにパスを報告します。

{ "name": "ppt-master", "refreshed": false,
  "held_back_removals": ["library: templates/mine.pptx"] }

何も保留されていない場合、このフィールドは完全に省略されるため、空の配列ではなく、フィールドの有無を確認してください。held_back_removals を伴う refreshed: false は、失敗ではなく、再試行するものでもありません。スキルは変更されず、以前のバージョンのままです。表示されたパスをユーザーに示して、どうするか確認してください。これを上書きする CLI フラグはありません。確認して続行できるのはデスクトップアプリだけです。これらのファイルが不要かどうか判断できるのは人だけだからです。パスには、保存場所（library、またはデプロイされたコピーの場合はエージェントキー）が先頭に付けられます。

この仕組みで対象にならないケースにも注意してください。ユーザーが編集したファイルが新しいバージョンにも含まれている場合、そのパスは維持されるため、更新後も残るものとして報告されます。つまり、更新によって編集内容が通知なく上書きされます。スキルフォルダー内にローカルの変更を保持しているユーザーには警告してください。

削除

# Always preview first when removing more than one
"$SM" skills remove <skill> --dry-run

# --yes is required for the actual delete; --json mode does NOT auto-confirm
"$SM" skills remove <skill> --yes

Remove は、中央ライブラリのコピー、すべてのエージェントに同期されたターゲット、および DB の行を削除します。再インストールしない限り、元に戻せません。

デプロイ／デプロイ解除

"$SM" skills deploy <skill> --agent claude_code
"$SM" skills undeploy <skill> --agent codex
"$SM" skills deploy <skill-a> <skill-b> --agent codex --dry-run
"$SM" skills deploy <skill> --agent claude_code --agent codex
"$SM" --json skills status <skill>

これらのコマンドは、中央ライブラリのコピーを削除したり、プリセットへの所属を変更したりせずに、実際の管理対象デプロイを変更します。skills enable/disable は互換性維持のための非推奨コマンドであり、デプロイには変更を加えません。絶対に使用しないでください。

skills deploy と skills undeploy では、1つのスキルを指定する場合も複数のスキルを指定する場合も、明示的な --agent が少なくとも1つ必要です。skills status は、登録解除されたカスタムエージェントが残したターゲット行も報告するため、古いデプロイも表示され、行が存在する間は明示的なデプロイ解除でクリーンアップできます。

従来の排他的同期

# Sync current active preset to all enabled agents
"$SM" skills sync

# Preview the target list — safe, no writes
"$SM" skills sync --dry-run

# Switch the one legacy active preset, then sync
"$SM" skills sync --preset "Web Dev"

# Only sync to a single agent (useful when one agent's directory got out of sync)
"$SM" skills sync --tool claude_code

別の場所にインストール済みのスキルを取り込む

スキルがすでにエージェントのディレクトリに存在するものの（例：npx skills add でのインストールや手動の git clone）、中央ライブラリにはない場合は、取り込んでください。

# Dry-run scan first — lists candidates without writing
"$SM" skills adopt ~/.claude/skills --dry-run

# Adopt everything found — each becomes source_type=local (can't auto-update from git)
"$SM" skills adopt ~/.claude/skills

# Adopt a single skill and pin it to a git source so `update` works later
"$SM" skills adopt ~/.claude/skills/react-best-practices \
  --git-url https://github.com/vercel-labs/agent-skills/tree/main/react-best-practices

# Or pass --git-subpath explicitly when the URL is just the repo root
"$SM" skills adopt ~/.claude/skills/react-best-practices \
  --git-url https://github.com/vercel-labs/agent-skills \
  --git-subpath react-best-practices

# Skill lives at the repo root? Pass an empty subpath
"$SM" skills adopt ~/.claude/skills/my-skill \
  --git-url https://github.com/me/my-skill --git-subpath ""

adopt は、すでに DB に登録されているもの、またはすでに同期ターゲットになっているものを自動的に除外するため、安全に再実行できます。--git-url には、サブパスを含む URL（/tree/branch/path）か、明示的な --git-subpath のいずれかが必要です。どちらも指定しないと、今後の update で誤ったディレクトリが再クローンされるため、CLI は推測による処理を拒否します。

--git-url が適用されるのは、ディレクトリがまだ管理対象外である取り込み時のみです。スキルがライブラリに入った後は、以下の set-source を使用してください。

スキルの参照先を Git ソースに変更する

# Preview: resolves the source and reports whether content differs. It clones to
# a temp dir, but writes nothing to the library or the DB.
"$SM" --json skills set-source <skill> --git-url you/skills --subpath my-skill --dry-run

# A GitHub /tree/ URL carries the branch and subpath already
"$SM" skills set-source <skill> --git-url https://github.com/you/skills/tree/main/my-skill

これは、local スキルを Git 管理に切り替えて update を使えるようにする方法と、間違ったリポジトリを参照しているスキルを修正する方法です。行をその場で更新するため、スキル ID は維持され、それに紐づくタグ、プリセットへの所属、エージェントごとのデプロイもすべてそのまま保たれます。

• ここで使うフラグは --git-subpath ではなく --subpath です。--git-subpath は adopt 用です。スキルがリポジトリのルートにある場合は --subpath "" を渡してください。リポジトリのルート自体に SKILL.md が必要です。
• --branch は URL に指定されたブランチを上書きします。
• レポートには content_changed が含まれます。これは単一のブール値であり、ファイル一覧ではありません。新しいソースを、ライブラリのコピーについて現在記録されているハッシュと比較します。ディスク上のディレクトリを新たにハッシュ化して比較するわけではないため、その後に中央コピー内で行った編集は差分として検出されません。値が false の場合、ライブラリのコピーはそのまま維持され、編集内容も保持されます。コピー方式のデプロイは、どちらの場合も再同期されます。

--force は破壊的な操作で、ユーザーのファイルを保護するものは何もありません。 内容に差分がある場合、--force を指定しないと処理は拒否されます。指定すると、スキルディレクトリ全体が置き換えられます。ステージング後に入れ替えられ、古いコピーは削除されるため、新しいソースに含まれないライブラリコピー内のファイルはすべて失われます。skills update と異なり、この処理には held_back_removals の確認がありません。削除は一切保留されず、確認も行われません。--dry-run では、どのファイルが影響を受けるかは分からず、差分があることしか確認できません。ユーザーに代わって --force を指定してはいけません。content_changed: true と報告し、続行するとライブラリコピー全体が上書きされることを伝えて、判断はユーザーに委ねてください。

タグ

"$SM" skills tag add <skill> web frontend
"$SM" skills tag remove <skill> frontend
"$SM" skills tag set <skill> web frontend
"$SM" skills tag rename frontend web
"$SM" skills tag delete obsolete --dry-run
"$SM" skills tag delete obsolete --yes
"$SM" skills tag list <skill>   # tags on one skill
"$SM" skills tag list           # all distinct tags

便利な整理用クエリ：

"$SM" --json skills list --untagged
"$SM" --json skills list --no-preset
"$SM" --json skills list --tag frontend
"$SM" --json skills list --preset "Web Dev"
"$SM" --json skills list --deployed-to codex

プリセット

"$SM" presets list
"$SM" presets current
"$SM" presets show "Web Dev"
"$SM" presets create "Web Dev" --description "Frontend work"
"$SM" presets update "Web Dev" --name "Frontend"
"$SM" presets delete "Old" --dry-run
"$SM" presets delete "Old" --yes

"$SM" presets add-skill <preset> <skill>...
"$SM" presets remove-skill <preset> <skill>...

"$SM" presets deploy <preset>                  # all enabled coding agents
"$SM" presets deploy <preset> --agent codex
"$SM" presets undeploy <preset> --agent claude_code
"$SM" presets undeploy <preset>                # every agent with target rows for this preset
"$SM" --json presets status <preset>

deploy/undeploy は追加型で、アプリのプリセット用ピルと一致します。明示的な presets apply/deactivate コマンドは、従来の排他的なアクティブプリセットモデル用です。通常の「このプリセットをオン／オフにする」という依頼には使用しないでください。

--agent を省略した場合のデフォルト動作は、意図的に異なります。deploy はインストール済みで有効なコーディングエージェントすべてを対象とします。undeploy はプリセットの実際の対象行を検出し、エージェントが現在無効、未インストール、または登録解除済みであっても、それらを削除します。「このプリセットをすべての場所でオフにして」という依頼には、エージェントを指定しない undeploy を使用してください。

プリセットの作成／更新／削除、およびスキルの追加／削除は、整理用の CLI 操作に限られます。エージェントのファイルを暗黙的にデプロイまたはデプロイ解除することはありません。

ヘルスチェック

同期が正常に動作しない場合や、コマンドが分かりにくいエラーを返す場合：

"$SM" --json repo status   # base dir, skill / preset counts, active preset
"$SM" --json agents list  # detected agents and their target paths
"$SM" agents enable codex
"$SM" agents disable claude_code

repo status と agents list は読み取り専用で、「なぜこのスキルが Cursor に表示されないのか」という質問に対する最初の確認に使います。agents disable は実際に状態を変更し、そのエージェントの管理対象デプロイをすべて削除します。agents enable を実行するとエージェントが再びグローバルに使用可能になり、従来のアクティブプリセットがあれば再同期されます。追加型の状態を求められている場合は、その後に明示的なスキルまたはプリセットのデプロイを使用してください。

エージェント連携全体をオフにしたい場合や、そのエージェントから管理対象のスキルをすべて削除したい場合は、agents disable <agent> を使用してください。エージェントは今後もデプロイできる状態に保ったまま、1 つのスキルまたはプリセットだけを削除したい場合は、代わりに skills undeploy または presets undeploy を使用してください。

一般的なワークフロー

「X 用のスキルを探して」／「X を実行するスキルをインストールして」

1. skills search "X" --limit 5 — インストール数とソースを添えて、上位 1～3 件を提示します。
2. 明確な候補がある場合：skills install <install_ref>。
3. 候補が複数ある場合：ユーザーに選んでもらいます。
4. skills deploy を使って、ユーザーが指定したエージェントにデプロイします。
5. skills status <name> でライブラリとデプロイの状態を確認します。

「自分が持っているスキルは？」

"$SM" --json skills list

通常、最も参考になるフィールドは preset_ids、presets、deployed_to、tags、source_type です。従来の enabled フィールドはデプロイ状態を示すものではありません。

「エージェントのディレクトリにすでにインストールされているスキルを取り込む」

1. skills adopt ~/.claude/skills --dry-run（ユーザーが言及したほかのエージェントディレクトリも対象にします）を実行し、候補の一覧を表示します。
2. ユーザーの確認後、skills adopt ~/.claude/skills を実行します。
3. 取り込んだスキルのうち、元のリポジトリをユーザーが把握しているものについては、skills set-source <skill> --git-url ... --subpath ... を使って更新リンクを復元します。

「すべて更新する」

"$SM" skills check --all     # see what has upstream changes
"$SM" skills update --all    # apply

JSON の refreshed: true を確認し、実際に更新されたスキルと、すでに最新だったスキルを報告します。

注意点

• インストールは成功したのに、エージェントにスキルが表示されない → インストール先はデフォルトでライブラリのみです。skills deploy <skill> --agent <key> を使います。
• プリセットのメンバーシップは変更されたが、エージェントのファイルは変更されていない → メンバーシップの変更は組織内に限られます。ユーザーが表示も求めている場合は、続けて presets deploy または skills deploy を実行します。
• アクティブなプリセットがない場合に影響するのは、従来の skills sync／presets apply のみです。追加型のデプロイコマンドでは、アクティブなプリセットは必要ありません。
• 取り込んだスキルは Git から update できない → npx skills add と手動の git clone ではソースメタデータが残らないため、取り込み時には local として扱う必要があります。skills set-source を使って参照先を設定し直します。ここで adopt --git-url を使ってはいけません。adopt が新しいライブラリエントリを作成するのは、この場合に限られます。また、エラーが遅れて発生します。--dry-run はスキルが skipped に入った状態で ok: true を返しますが、実際に実行すると --git-url requires exactly one adoptable skill, found 0 というエラーになります。削除してから再インストールする方法も使わないでください。スキル ID が失われ、それに伴ってタグ、プリセットのメンバーシップ、エージェントごとのすべてのデプロイも失われます。
• 一括削除、タグ削除、プリセット削除、デプロイ、またはデプロイ解除の操作を行う前に --dry-run を使います。update の前には check を実行します。