skillctl は何をしますか?
Agent Skills を skillctl CLI で管理するための運用プレイブック。実際のコマンドを実行すること。出力のシミュレーションや、SKILL.md ファイルをエージェントディレクトリ間で手動コピーしてはいけません。
ゴールデンルール
- 単一の正規ストア — スキルは
~/.skillctl/skills/<name>/に配置され、エージェントはsyncによってシンボリックリンクを受け取ります。 - マニフェスト + ロックをコミットする — チームの再現性のために
agent-skills.jsonとagent-skills.lockを git で追跡します。 - ポータブル指定子のみ使用する —
file:./<path>、local:imported/<name>、github:、npm:、skills.sh/を使用し、絶対パスのホームディレクトリをコミットしてはいけません。 - 同期前にインストールする —
installでストアを実体化し、syncはエージェントの再リンクのみ行います。 - 変更後に検証する —
skillctl doctor(および CI ではskillctl audit)を実行します。 - 手動コピーよりインポートを優先する — スキルフォルダを複製する代わりに
import from-projectまたはimport from-npxを使用します。
決定木
| 状況 | コマンド |
|---|---|
| 新規プロジェクト、マニフェストなし | skillctl init または skillctl init --with-skill |
| リモートまたはローカルのスキルを追加 | skillctl add <specifier> その後 skillctl install |
スキルが既に .claude/skills、.codex/skills 等にある | skillctl import from-project |
npx skills からの移行 | skillctl import from-npx |
| 再リンクのみ(ロックは変更なし) | skillctl sync |
| アップストリームから再取得 | skillctl update または skillctl update <name> |
| CI での再現可能なインストール | skillctl install --frozen その後 skillctl audit --strict |
| ロック内の非ポータブルパス | skillctl install で書き換え。skillctl doctor の警告を確認 |
クイックレシピ
# ブートストラップ
skillctl init --with-skill
skillctl add github:vercel-labs/agent-skills#web-design-guidelines
skillctl install
# プロジェクトローカルスキル
skillctl add file:./my-skill
skillctl install
skillctl sync
# 既存のエージェントディレクトリをインポート
skillctl import from-project --dry-run
skillctl import from-project
# 確認
skillctl list
skillctl doctor
skillctl audit --json
add file:./my-skill + install 後の期待結果: マニフェスト指定子 file:./my-skill、ロック canonicalPath は ~/.skillctl/skills/my-skill のようになります。
ポータビリティ (0.3.1+)
- ポータブル:
file:./rel、local:imported/<name>、リモート指定子、canonicalPath: ~/.skillctl/skills/<name>。 - 非ポータブル: 絶対パスの
file:/Users/...、local:/abs/path、別のマシンからの絶対canonicalPath。 doctorが非ポータブルパスに関する警告を出した場合、skillctl installを実行してマニフェストからロックを書き換えてください。
障害モード
| 症状 | アクション |
|---|---|
canonical path missing | skillctl install |
| 整合性不一致 | skillctl update <name> または skillctl install |
| シンボリックリンク失敗(Windows) | doctor が通知。defaultMode: copy で設定 |
| エージェントがリンクされていない | skillctl sync。~/.skillctl/config.json でエージェントを有効化 |
Frozen install failed | ストアの同期が取れていない。--frozen なしで install を実行 |
参考
- commands.md — 全コマンド早見表
- specifiers.md — 指定子の文法
- manifest-lock.md — マニフェストとロックのセマンティクス
- workflows.md — チームオンボーディング、移行、CI
- troubleshooting.md — doctor、Windows、共存