skill-maker

スキルの作成

Claude Code、Codex、OpenCode 向けのスキルを作成、リンティング、公開します。skills パッケージマネージャーで配布されるスキルは、ソースを別の Git リポジトリに保存します。一方、リポジトリ内で所有するローカルスキルは、利用するリポジトリに直接配置できます。

パッケージマネージャーのポリシー：skills@latest を継続的に使用します。 このスキルと README の例では、対話形式で実行するワークステーションコマンドおよび SessionStart フックに npx -y skills@latest を使用してください。これは、新しく公開されたサードパーティーのインストーラーコードをセッション開始時に無人で実行させる代わりに、パッケージマネージャーの修正や機能を自動的に利用するための意図的な選択です。スキルのソース URL と参照先は、それとは独立して管理されます。レビュー済みで再現可能な実行コードが必要となる CI、特権を伴う自動化、またはその他の環境では、パッケージマネージャーを固定してください。

編集前にスキルを分類する

スキルのパスは、作成したソースか、パッケージマネージャーが管理するインストール済みコピーのいずれかです。作成したソースのみ編集してください。

種類	場所	編集しますか？
公開済みソース	スキルのソースリポジトリ（<name>/SKILL.md）	はい
リポジトリローカルのソース	複数のエージェントで使うスキルは<repo>/.agents/skills/<name>/、意図的に Claude 専用とする場合のみ<repo>/.claude/skills/<name>/	はい
npx でインストールされたコピー	グローバルまたはプロジェクトのインストール先ディレクトリ、または正式な .agents/skills ストアとその投影先	いいえ — 派生物です。npx -y skills@latest add／update によって上書きされます

公開済みスキルの公開は、ライブ編集ではなくプル方式です。ソースリポジトリを変更し、その後 npx -y skills@latest update を実行して再取得し、インストール済みコピーを書き換えます。インストール済みコピーを直接編集しても、次回の更新で破棄されます。リポジトリローカルのソースの場合は、実ディレクトリとその互換性シンボリックリンクを利用するリポジトリにコミットしてください。パッケージマネージャーのインストール手順は必要ありません。

• ソースリポジトリを所有している場合：<name>/SKILL.md を編集してコミット、プッシュし、その後 npx -y skills@latest update を実行してください。
• 所有していない場合（インストールしただけの場合）：実際にはインストール済みコピーは読み取り専用です。変更するには、ソースリポジトリをフォークして npx -y skills@latest add <your-fork> を実行するか、上流リポジトリに PR／issue を作成してください。所有していないリポジトリにはプッシュできません。

インストール済みスキルの入手元を確認するには、ロックファイルに記録されているソースを確認してください。グローバルインストールの場合は ~/.agents/.skill-lock.json（または設定されている場合は $XDG_STATE_HOME/skills/.skill-lock.json）、プロジェクトへのインストールの場合は <project-root>/skills-lock.json です。そこにスキル名が記載されている場合、ディスク上のスキルは .agents/skills 以下にあり通常のディレクトリに見えるとしても、派生物として扱ってください。

Claude Code、Codex、OpenCode 向けのリポジトリローカルスキル

1 つのリポジトリで作成し、そのリポジトリでのみ役立つスキルは、リポジトリルートの .agents/skills 以下に正式な実ディレクトリを配置してください。Codex は現在のディレクトリからリポジトリルートまで .agents/skills を検索し、シンボリックリンクされたスキルフォルダーにも対応しています。また、OpenCode は同じプロジェクトパスとグローバルパスを検索します。Claude Code はプロジェクトスキルを .claude/skills 以下から検出するため、追跡対象となる次のいずれかのレイアウトを使って、同じ内容を公開してください。

1 つのディレクトリシンボリックリンク

リポジトリ内のすべてのスキルがエージェント間で共通しており、プロジェクトスコープの npx skills add を一度も使用しない場合は、このシンプルな形式を推奨します。skills-lock.json が存在しないことを確認してください。

<repo>/
├── .agents/skills/
│   └── <name>/
│       ├── SKILL.md
│       └── scripts/                  # optional
└── .claude/skills -> ../.agents/skills

既存のスキルがすべて実際の .claude/skills ディレクトリにあり、.agents/skills がまだ存在しない場合は、ツリー全体を移動して履歴を保持します。

mkdir -p .agents
git mv .claude/skills .agents/skills
ln -s ../.agents/skills .claude/skills

.agents/skills にすでにスキルがある場合は、残りのスキルディレクトリを名前ごとに git mv で移動し、空になった .claude/skills ディレクトリを相対シンボリックリンクに置き換えます。

この形式には 2 つのデメリットがあります。1 つ目は、すべてのスキルが Codex と OpenCode から見えるようになるため、Claude 専用のスキルを Claude だけに非公開にできないことです。2 つ目は、プロジェクトスコープの npx インストールでは使用しないことです。パッケージマネージャーの .claude/skills/<name> プロジェクションが、独立したプロジェクションとしてではなく、正規の .agents/skills/<name> ストア上に解決されるためです。いずれかのデメリットが当てはまる場合は、以下のスキルごとの形式を使用してください。

スキルごとのシンボリックリンク

リポジトリ内にエージェント間で共通するスキルと Claude 専用のスキルが混在している場合、またはプロジェクトスコープの npx インストールが存在する場合は、この形式を使用します。エージェント間のシンボリックリンク、Claude 専用のスキル、npx 管理のプロジェクションを共存させられるよう、.claude/skills 自体は実際のディレクトリとして維持します。

<repo>/
├── .agents/skills/<name>/
│   ├── SKILL.md
│   └── scripts/                  # optional
└── .claude/skills/<name> -> ../../.agents/skills/<name>

新しいルートスコープのエージェント間共通スキルを作成する場合は、まず実際のフォルダーを作成し、次に Claude 用のプロジェクションを作成します。

mkdir -p .agents/skills/<name> .claude/skills
ln -s ../../.agents/skills/<name> .claude/skills/<name>

既存のリポジトリ作成の Claude スキルについては、まずその名前が skills-lock.json に存在しないことを確認してから、移動して履歴を保持します。

mkdir -p .agents/skills
git mv .claude/skills/<name> .agents/skills/<name>
ln -s ../../.agents/skills/<name> .claude/skills/<name>

実際のディレクトリとシンボリックリンクの両方を追跡します。ロックファイルが管理する依存関係をこの方法で移動しないでください。上流のソースまたはパッケージの選択を変更し、npx によってストアとプロジェクションが再生成されるようにします。本当に Claude 専用のスキルは、実際の .claude/skills/<name> ディレクトリとして残します。

どちらのレイアウトでも、~/.agents/skills ではなく <repo>/.agents/skills を使用します。チルダで始まるパスはユーザー全体に適用されるため、リポジトリの契約がマシン固有になってしまいます。共有パスによって 1 つの本体を検出できるようにはなりますが、ハーネス固有の動作が変換されるわけではありません。スキルをエージェント間で共通と宣言する前に、フロントマター、ツール名、スラッシュコマンド、ライフサイクルの前提、.claude/skills/... というリテラルなパスを確認してください。name、description、本文は移植可能な形に保ち、ホスト固有のメタデータはそのホストで必要な場合にのみ残してください。また、セキュリティ境界として別のホストがフィールドを無視することに依存しないでください。補助ファイルは、どちらかの検出パスをハードコードするのではなく、実行環境から提供されるスキルのベースディレクトリを通じて参照してください。

製品に関する注意点：uzi のワーカーは現在、実際の .claude/skills ディレクトリからのみリポジトリのスキルを列挙し、ADR-0246 の封じ込めガードにより、2 種類のシンボリックリンク形式をどちらもスキップします。そのため、repo_skills_enabled が設定されたリポジトリでは、vtmocanu/uzi#1205 によって .agents/skills が 2 つ目の実ディレクトリルートとして追加されるまで、ワーカーの実行時にそれらのスキルが利用できません。

エージェント定義はポータブルなスキルディレクトリではありません

.agents/skills のレイアウトを .agents/agents にそのまま一般化しないでください。これらのランタイム間で共有されるエージェント定義の検出パスやファイルスキーマはありません。

• Claude Code は .claude/agents/ から Markdown 形式のエージェント定義を読み込みます。

• Codex は .codex/agents/ から TOML 形式のカスタムエージェント定義を読み込みます。各ファイルには name、description、developer_instructions が必要です。

• OpenCode は .opencode/agents/ から、OpenCode 固有のフロントマターを含む Markdown 形式のエージェント定義を読み込みます。

• Cursor は .cursor/agents/ に加えて .claude/agents/ と .codex/agents/ も読み込み、同名の場合は優先順位に従います。後者 2 つのディレクトリの両方に生成されたロールが重複して表示されるかどうかは未確認です。

• Claude Code、Codex、OpenCode、Cursor、Gemini CLI のいずれも .agents/agents/ を読み込みません。

1 つのエージェント定義ファイルをこれらのディレクトリ間でシンボリックリンクしないでください。複数のエージェントにまたがるロールカタログを作成する場合は、roles.yaml などの中立的なソースデータを保持し、各ランタイム向けにネイティブな形式を生成して検証してください。agent-team スキルは、これらのアダプターに対応するまでは Claude Code ネイティブです（vtmocanu/skills#43）。

レイアウト：フォルダ形式のスキル

すべてのスキルは、内部に SKILL.md を含むフォルダとして作成してください。skills CLI が検出するのは <name>/SKILL.md のみで、単独の <name>.md は検出されません。

<name>/
├── SKILL.md            # required — frontmatter + body
├── scripts/foo.sh      # optional supporting files
└── references/bar.md   # optional

補助ファイルは、スキルの読み込み時にハーネスから提供されるスキル自身のベースディレクトリを基準に参照してください（Base directory for this skill: … という行）。たとえば、<this skill's directory>/scripts/foo.sh のようにします。./scripts/foo.sh のような相対パスのみの指定は使用しないでください。実行時の作業ディレクトリはスキルのディレクトリではなくユーザーのプロジェクトなので、./ は誤った場所を指します。同梱スクリプトは直接実行してください（bash <dir>/scan.sh ではなく <dir>/scan.sh）。実行可能ファイルとして (0o755) 書き込みます。直接実行すれば Claude Code の Bash(/path/to/scan.sh:*) 権限スコープに一致しますが、bash … でははるかに広範な Bash(bash:*) が必要になります。

フォルダを使う理由は補助ファイルにあります。SKILL.md しか含まないフォルダは単独のプロンプトと同じように動作しますが、npx が検出できるよう、引き続きフォルダ形式を使用してください。

サブパスの下にネストする場合は .claude-plugin/plugin.json マニフェストが必要です

リポジトリ全体をインストールする場合（コンテナ skills/）、カタログのネストを追加設定なしで深さ3レベルまで検出します（skills/<cat>/<name>/SKILL.md、skills/<cat>/<cat>/<name>/SKILL.md）。一方、サブパスをインストールする場合（npx -y skills@latest add owner/repo/skills/<sub>）はそうではありません。CLI はサブパスのディレクトリを1レベルだけたどるため、<sub>/<group>/<name>/SKILL.md にあるスキルは黙って除外されます（エラーはなく、バンドルに含まれないだけです）。この深さの上限はフェッチエンジンとは無関係です。CLI はハードコードされたオーナーの許可リスト（vercel、vercel-labs、heygen-com、およびセルフホストのリポジトリ数件）に含まれる場合に限り、高速な GitHub tree-API を使います。それ以外のすべてのオーナーについてはリポジトリをクローンしてファイルシステムをたどりますが、どちらの経路でもサブパスの深さは1レベルに制限されます。

解決策：<sub>/.claude-plugin/plugin.json マニフェストです。マニフェストで宣言したスキルパスは深さの走査を迂回します（npx の説明：「宣言された深さで検索され、深さ3に制限されたカタログ走査の対象になりません」）。

// skills/agent-kit/.claude-plugin/plugin.json
{ "name": "agent-kit", "skills": ["./agent-team", "./prd/prd-create", "./prd/prds-get"] }

CLI は各エントリをサブパスのディレクトリ内で解決し、その親ディレクトリを登録してから、そのディレクトリを1レベル走査して SKILL.md を探します。そのため、./prd/<any-skill> というエントリを1つ登録すれば prd/ フォルダー全体が登録され、その直下にあるすべてのスキルが検出されます。登録済みフォルダーに追加された新しいスキルは、マニフェストを編集しなくても自動的に加わります。マニフェストだけでは解消されないのは、どのエントリからも登録されていない新しいネストフォルダーです。CI でカバレッジチェックを行い、サブパスのインストールで検出される対象を再計算して、ディスク上の SKILL.md に到達できないものがあれば失敗させてください（scripts/check_bundle_coverage.py を参照）。

レイアウトを変更した場合は、デフォルトブランチに対して実際に add を実行して確認してください。add --branch <x> と add … -l では、SessionStart フックが使うデフォルトブランチのインストールとは異なるパスになる場合があります。

フロントマター

name：

• 必須です。 インストール名／表示名です。ディレクトリ名が使われるのはフォールバックの場合のみです。
• 最大64文字。小文字、数字、ハイフンのみ使用できます。XML タグは使えません。
• 予約された部分文字列は anthropic、claude です — name: では使わないでください。

description — 検出はここで行われます。適切に記述してください。

• 1行にしてください。 移植性（Anthropic Skills API）とクリーンな自動呼び出しのため、説明は1行に収めてください。
• 引用符で囲まれていない : （コロン＋スペース）は使わないでください。 通常の YAML スカラー内のコロン＋スペースはマッピングインジケーターとして解釈されます。skills CLI パーサーはこれを拒否し（mapping values are not allowed here）、null を返してスキルを黙ってスキップします — ⚠ Skipped の警告が表示されますが、エラーはなく、終了コードは0のため、インストールされません。: を避けて言い換えるか、説明全体を二重引用符で囲んでください。
• 三人称（「X を生成します」「Y を管理します」）で記述してください。システムプロンプトに挿入されるため、一人称や二人称では自動呼び出しが適切に機能しません。
• 「いつ使うか」に関する情報はすべてここに記載し、本文には書かないでください：Use when (1)… (2)… および Triggers include "…"。
• やや積極的に促す表現にしてください — モデルはスキルの呼び出しが控えめになる傾向があります。「関連があれば使う」ではなく、モデルがスキルを使うよう促すトリガーを記述してください。
• スタイル上の目安は約500～700文字です。Anthropic Skills API の上限は1024文字です（npx 自体は上限を適用しませんが、agnix はエラーとして報告します）。トリガーを追加したら、再度リントしてください。すべてのセッションで読み込まれるため、文字数を水増ししないでください。

常時読み込みのコスト／名前のみ。 スキルが起動するかどうかにかかわらず、description はすべてのセッションで読み込まれるため、用途が限定的なスキルや過剰にマッチするスキルには、セッションごとに実質的なコストが発生する場合があります。Claude Code では、settings.json の skillOverrides（"<skill>": "name-only"）を使って、明示的に呼び出した場合にのみスキルを起動できます — 説明は読み込まれなくなりますが、名前で呼び出すことはできます。単一目的のスキルや、トリガーが過剰にマッチするスキルに使用してください。

設計原則

Anthropic の上流 skill-creator（Apache 2.0）をベースにしています。

• 簡潔に。 モデルがすでに知っていることは追加しません。命令形（「コミット前に agnix を実行する」）を使い、曖昧な表現（「〜するべきです」「〜を推奨します」）は避けます。
• 対象読者は実行時のモデルであり、人間ではありません。 導入の説明、根拠の羅列、変更履歴、インストールガイドは省きます。
• 指示を記し、経緯は省きます。 ルール、トリガー、コマンド、制約、例外を残します。日付、インシデントの経緯、観察・検証・測定に関する逸話、追加理由の説明、根本原因の履歴は削除します。根拠はコミットまたは PR に記載します。動作がバージョンに依存する場合に限り、バージョンを残します。
• 公開時にバイト列を維持します。 更新スクリプトや公開スクリプトで文章を自動的に書き換えてはいけません。作成したソースはレビューしながら簡潔にします。
• ハードコードせず、調べられるようにします。 変更される値（バージョン、IP、名前空間、シークレットのパス）については、値そのものではなく取得コマンドを示します。「X の調べ方」なら正確な状態を保てますが、「X は 1.2.3」とすると古くなります。具体的な値を示す場合は例だと明記し、モデルに再取得するよう伝えます。
• 詳細度を変更の起こりやすさに合わせます。 判断にばらつきがある場合は文章の指示、パターンがある場合はパラメーター化されたスクリプト、順序が重要な場合は専用スクリプトを使います。
• 選択肢の一覧ではなく、既定の方法を示します。 推奨するツールや方法を1つ選び、明確に異なるケースに限って代替案を示します。
• 用語を統一します。 スキル全体で、概念ごとに用語を1つだけ使います。

本文の予算と段階的な読み込み

レベル	内容	読み込み時期	目安の上限
1. メタデータ	フロントマター（name + description）	常時、すべてのセッション	約100語
2. 本文	フロントマターの後に続く SKILL.md	スキルがトリガーされたとき	500行未満／5Kトークン未満
3. リソース	scripts/、references/、assets/	必要に応じて	無制限

本文が約500行を超えたら、詳細を references/*.md に分割します（階層は1段まで）。情報は SKILL.md かリファレンスのどちらか一方に記載し、両方には記載しません。重複はすぐに古くなります。

スクリプトを同梱する場合

次のいずれかに当てはまる場合は、インラインのコード片より同梱スクリプトを優先します。同じ curl … | jq … の連鎖を3回以上使うような、繰り返しの複数ステップのオーケストレーション、複雑なデータ変換、重要なエラー処理（401 の場合の再試行、部分的な失敗時のロールバック）、または自然な CLI の操作体系（list／get／add の動詞）がある場合です。単一のコマンドである場合、ユーザーが読む正確な表現が重要な場合、またはスキルが小規模な場合はインラインのままにします。

スクリプトの規約：可能な限り標準ライブラリのみを使用します（実行時の pip install は避けます）。用途ごとに実行可能ファイルを1つにします（何でも詰め込んだ helpers.sh は作りません）。直接実行できるようにします。Windows でもパスにはスラッシュを使います。

命名

動名詞（processing-pdfs）、名詞句（pdf-processing）、動詞（process-pdfs）のいずれでも構いません。曖昧な名前（helper、utils、tools）や、汎用的すぎる名前（data、documents）は避けます。

コンテンツ作成時の注意点

• 時間が経つと古くなる内容を避けます。 「2025年8月以前なら X を実行する」とは書きません。代わりにバージョンを指定します（「ripgrep 14.0 以降」）。非推奨の方法は「古いパターン」というセクションや <details> の中に隔離します。
• 問題を解決し、先送りしません（スクリプトを使うスキルの場合）。モデルに復旧を求めて失敗させるのではなく、スクリプト内で FileNotFoundError／PermissionError を処理します。
• 重要なブロックで弱い表現を使いません。 指示では should を MUST や命令形に置き換えます。引用されたユーザー発話のトリガー例は例外として、リンターがデータとして認識できるようフェンスで囲みます。否定事項は肯定的な代替案とともに示します（「浅いクローンは避ける」だけではなく、「通常のクローンを使う」と記します）。

コードブロック内に単独の $1 / $2 を記述しないでください

スキルが引数付きで呼び出される場合（/<skill> some args）、ランナーはレンダリングされた本文のすべての場所で、コードブロック内を含めて、引数トークンを $N に置換します。コードブロックでは $N を避け、代わりに cut -f1、jq -r '.[0]'、名前付き正規表現キャプチャなどを使ってください。$N がどうしても必要な場合は、$1 が文字どおりの値であることを示す警告をスニペットの隣に記載してください。$$1 / \$1 のエスケープがそのまま維持されると思い込まず、必ず確認してください。

agnix によるリンティング

スキルを変更してコミットする前に、<skill-file> を実際に作成したソースに解決してください。公開フォルダーのソースなら <name>/SKILL.md、リポジトリ内のエージェント横断ソースなら .agents/skills/<name>/SKILL.md です。その後、リンティングを実行してください。agnix はトークンの冗長さ、弱い表現、曖昧な指示、不適切なキーワード配置を検出します。

agnix --target claude-code <skill-file>

エージェント横断スキルでは、両方のコンシューマーを検証してください。

agnix --target claude-code <skill-file>
agnix --target codex <skill-file>

--target は引き続き使用でき、agnix --help にも掲載されていますが、最近の agnix バージョンでは Field 'target' is deprecated と表示され、設定ファイルの tools 配列を使うよう案内されます（--tools CLI フラグはありません）。この警告は問題ありません。頻繁にリンティングするリポジトリで警告を抑えるには、.agnix.toml（agnix init）を追加し、tools = ["claude-code"] を設定して、フラグを外してください：agnix <skill-file>。

書き換えをプレビューするには --show-fixes、確度の高い修正を適用するには --fix-safe を追加します（必ず差分を再確認してください。「修正可能」は「文脈上正しい」と同じ意味ではありません）。ファイルだけでなく、スキルのディレクトリもリンティングしてください：agnix <skill-dir> は references/ やその他の同梱 Markdown もチェックしますが、agnix <skill-file> ではチェックされません。

agnix は、複数行にまたがるインラインコードスパン内の <placeholder> を Unclosed XML tag エラーとして扱います。同じスパンを1行で記述すれば問題ありません。各インラインコードスパンは1行に収めるか、プレースホルダーを UPPER_CASE で記述してください。

エラーはコミット前に修正する必要があります。警告は参考情報ですが、実際に該当するものは修正してください。変更前からある警告も対象です：実際の編集のためにファイルを開いたときに、変更前からある警告を見つけた場合は、警告数が同じままのファイルを何度もコミットするのではなく、同じコミットでの修正を提案してください。

agnix は過去からのノイズを検出しません。 リンティングに合格した後、編集したすべての SKILL.md、リファレンス、テンプレート、アセットを、上記の「指示のみ」のルールに照らして確認してください。編集時に見つかった既存のノイズは削除してください。

ワークフロー

まず、ソースがすでに SessionStart フックに組み込まれているか確認してください。 ~/.claude/settings.json と ~/.codex/hooks.json の両方を調べてください。2つのエージェントを併用する設定では、共有ラッパーを参照している場合があるため、そのソース引数も確認してください。組み込まれている場合、そのソースへの新規または編集済みスキルの公開は、コミットしてプッシュするだけです。リフレッシャーが次回のセッション開始時に新しいスキルを検出し、更新されたファイルを公開します。すぐに使うには、インストール済みのリフレッシャーを直接呼び出してください。ストアの利用者がすべて終了している場合に限り、ファイルを置き換える直接変更型の npx skills コマンドを使用してください。このフックが行わない処理は2つあります。削除または名前変更されたスキルの整理（npx -y skills@latest remove）と、settings.json の name-only など、マシン固有の skillOverrides 状態の設定です。

ソースを初めてインストールする

npx -y skills@latest update はロックファイルにすでに記録されているスキルのみを更新するため、新しいスキル（またはこのマシンにまだインストールされていないソース）は、まず追加する必要があります。

npx -y skills@latest add <source> -a claude-code codex -g  # canonical store + Claude projection; omit -g for project scope

<source> には、GitHub の owner/repo 形式または完全な URL を指定できます。プライベートリポジトリの場合は、既存の Git 認証情報（SSH エージェント／認証情報ヘルパー）を使ってクローンできるよう、SSH 形式の git@host:owner/repo.git を使用してください。

• インストールせずにソースを監査する：npx -y skills@latest add <source> -l を実行すると、リポジトリで提供されているすべてのスキル（名前＋説明）が一覧表示されます。ソースの内容を調べるときや、上流で追加されたスキルを見つけるときに使用してください。update は新しいスキルを検出しないため、スキルの存在を確認するにはこの方法を使います。
• --skill は追加するスキルのみを指定します。除外フラグはありません。 一部を除いてすべてインストールするには、名前のリストを指定する（--skill a b c）か、--skill '*' でインストールしてから npx -y skills@latest remove <name> -g -y を実行してください。除外する理由：name: が組み込みスキルと重複するスキルがある場合（「有効化／無効化」の名前衝突に関する注意を参照）。

セッション開始時に新しいスキルを自動インストールし、更新する（フック）

自動インストールと更新には、同梱のリフレッシャーを使用してください。

~/.agents/skills/skill-maker/scripts/refresh_skills.py --source <source>

この明示的な組み合わせは重要です。skills CLI 1.5.23 では、ユニバーサルではない claude-code ディレクトリのみを対象にするとコピーモードが選択され、.claude/skills にしか書き込まれません。Codex や OpenCode が検出できる正規の .agents/skills エントリは存在しません。claude-code codex を対象にすると、正規ストアとシンボリックリンクを使うモードが選択されます。Codex によってユニバーサルな .agents/skills のターゲットが提供され、Claude にはシンボリックリンクが作成されます。また、OpenCode は余分な 3 つ目のターゲットを設定しなくても、同じ正規ストアを検出します。パッケージマネージャーのバージョンを変更する際は、プローブを再実行してください。

macOS／Linux の標準ライブラリラッパーは、ステージングから公開までの間、~/.agents/.skills-refresh.lock に対して fcntl.flock を保持します。Vercel の CLI を使用して、設定済みカタログを --skill '*' で一時プロジェクトにインストールし、その後、記録済みの名前と参照先を使って、その他の追跡対象のグローバル依存関係および現在のプロジェクトの依存関係をインストールします。新しいカタログ内のスキルは自動的に検出されます。skills-lock.json にないリポジトリ作成のスキルは変更されません。デフォルトのカタログはこの公開リポジトリです。別の必須カタログには --source を、任意のカタログには --best-effort-source を繰り返し指定してください。取得、検出、ステージング環境へのインストールは Vercel が処理します。ラッパーは完全なファイルを稼働中の正規ストアと Claude ストアに公開し、ステージングされたロックメタデータを適切な形式にします。

読み取り側はラッパーのロックを取得しません。 保護には、ステージングとファイル置換のアトミックな実行を使用し、補助ファイルを SKILL.md より先に公開します。既存のパスや削除済みの補助ファイルは引き続き読み取り可能で、変更されていないファイルは書き換えられません。これはファイルごとのアトミック性であり、スキル全体のスナップショットではありません。スクリプトを変更するとき、ファイル不足の警告を調査するとき、またはメタデータとクリーンアップの制限に対処するときは、更新の安全性を参照してください。

skill-maker のインストール後は、実際にインストールされたスクリプトのパスを直接使用してください。フックコマンドの信頼性を安定させる必要がある場合や、マシン固有のソース引数を指定する必要がある場合は、インストール済みスクリプトをその引数とともに exec する、マシンローカルの薄いトランポリンを指定してください。リフレッシャーの実装を安定したパスにコピーしないでください。npx が更新するのはインストール済みのスキルであり、切り離されたコピーではないため、フックは古いロジックを実行し続けます。インストール済みスクリプトとトランポリン（使用する場合）が存在し、実行可能になるまでは、どちらのフックも設定しないでください。どのエントリーパスからも、最終的にはインストール済みのリフレッシャーが実行される必要があります。共有の ~/.agents/.skills-refresh.lock に対する fcntl.flock が、直列化の境界となります。

次のフックの場所とマッチャーを使用してください。

エージェント	フックファイル	SessionStart マッチャー	追加手順
Claude Code	~/.claude/settings.json	startup	なし
Codex	~/.codex/hooks.json	startup|resume	/hooks でハンドラーを一度確認して信頼する
Codex の場合、既存のグループの順序を変えずに、ラッパーを別の SessionStart グループとして追加してください。これにより、保存済みの信頼 ID が安定します。

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "~/.agents/skills/skill-maker/scripts/refresh_skills.py",
            "timeout": 300,
            "async": true
          }
        ]
      }
    ]
  }
}

Codex のユーザーフックは ~/.codex/hooks.json から読み込まれ、新規または変更されたフックは /hooks で信頼されるまでスキップされます。詳しくは公式のフックドキュメントを参照してください。段階的なリフレッシャーにより、非同期で実行できます。セッション開始時に古いインベントリが使われる場合がありますが、置き換え中も個々のファイルは読み取り可能です。Codex はセッション終了時に未完了のバックグラウンドフックをキャンセルします。次の startup または resume で再試行されます。リフレッシュの完了を起動の条件にする必要がある場合は、async を削除してください。同期実行だけでは他のセッションの読み取りは保護されないため、いずれの場合も段階的な処理を維持してください。両方のエージェントには、設定済みおよび追跡対象のすべてのソースに対応できるタイムアウトを設定してください。基準値は 300 秒です。

• add … --skill '*' は、現在 <source> にあるすべてのスキルをインストールするため、新しいスキルも自動的に追加されます。--skill '*' は明示的な -a claude-code codex の対象範囲を維持しますが、--all はサポートされているすべてのエージェントに適用します。

• update を直接実行してエージェントを対象指定することはできません。 内部で実行される add は、検出されたすべてのエージェントを対象にします。リフレッシャーは、記録済みの依存関係に対して、対象を明示した add を段階的に実行します。公開するのは正規ストアと Claude のプロジェクションのみです。OpenCode は正規ストアを直接読み込みます。他のエージェントのプライベートコピーは作成も更新もしません。

• 段階的な処理と公開は、直列化された1回のラッパー実行内で行ってください。npx skills を直接実行するコマンドは、そのロックに従いません。

• 到達不能なカタログがインストール済みファイルをそのまま維持し、リフレッシュを失敗させないよう、オプションのソースは個別に宣言してください。

  ~/.agents/skills/skill-maker/scripts/refresh_skills.py --source <reliable-source> --best-effort-source <vpn-only-source>
  

• 非TTYのフックでは、削除や名前変更は引き続き自動整理されません（「名前変更／削除」を参照）。npx -y skills@latest remove <old> -g -y で古い名前を削除してください。

既存のスキルを編集して公開する

1. リポジトリ内のソース <name>/SKILL.md（および関連ファイル）を編集します。

2. 整理：編集したパッケージ内のすべてのファイルから、指示のみを残します。編集時に見つかった既存の不要な内容は削除します。

3. リント：agnix でリントします。エラーを修正し、警告を確認します。

4. コミットしてプッシュ：ソースリポジトリにコミットしてプッシュします。変更したファイルのみをステージングしてください（git add <name>/）。git add -A は実行しないでください。作業ツリーには、他のスキルに関する無関係な作業中の変更が含まれている可能性があります。

5. 公開：インストール済みのリフレッシャーを実行するか、次の SessionStart 実行に任せます。すべてのコンシューマーを終了している場合は、直接 npx -y skills@latest update -g -p を実行できます（-g はグローバル、-p は現在のプロジェクト）。この直接変更コマンドを非同期フックに含めないでください。

6. ソースファイルではなく、モデルが読み取る対象を確認するため、正規のインストール済みストアと各ターゲットのプロジェクションを検証します。

   grep "<distinctive phrase from your edit>" ~/.agents/skills/<name>/SKILL.md
   grep "<distinctive phrase from your edit>" ~/.claude/skills/<name>/SKILL.md
   

名前変更／削除

npx -y skills@latest update は、ロックファイルですでに追跡されているスキルのみを調整します。新しい名前のスキルはインストールせず、自動的に整理することもありません。削除時に非対話型の実行（フック、またはTTYがない場合）を行うと、Skipping deletion in non-interactive mode と表示され、スキルはディスク上とロックファイル内に残ります。-y を指定しても変わらず、--prune フラグもありません。そのため、削除は必ず npx -y skills@latest remove で明示的に行います。

• 名前変更：git mv <old>/ <new>/ を実行し、name: フィールドを更新して、リポジトリ内の参照元を検索します（rg "<old>" .）。その後、コミットしてプッシュします。次に、各マシンで npx -y skills@latest add <source> を実行して新しい名前をインストールし、npx -y skills@latest remove <old> -g -y で古い名前を削除します。
• 削除：git rm -r <name>/ を実行し、参照を検索して、コミットしてプッシュします。その後、各マシンで npx -y skills@latest remove <name> -g -y を実行します（対話型の npx -y skills@latest update でも削除が提案されますが、非対話型の場合は提案されません）。

remove では、スキルの名前（スペース区切り）または --all を指定します。--source <repo> による絞り込みはできないため、削除する各スキルの名前を指定してください。フラグは他のコマンドと同じです。-g はグローバル、-a <agent> は1つのエージェントに限定、-y は確認を省略します。

インストール範囲（skills CLI）

• 範囲：対象に Codex などのユニバーサルエージェントが含まれる場合、npx は .agents/skills に正規のインストール済みストアを保持し、.claude/skills など、エージェント固有のプロジェクションを作成します。ユニバーサルではない対象が 1 つだけの場合は、コピー方式を使い、正規ストアを省略できます。グローバルインストールでは $HOME、プロジェクトインストールではリポジトリを使用します。add／update／remove は、デフォルトでプロジェクト範囲です。グローバル範囲にするには -g を指定します。update -g -p は両方を更新します。
• ロックファイル：グローバル → ~/.agents/.skill-lock.json、プロジェクト → <project-root>/skills-lock.json。各インストール済みスキルのソースを記録します。~/.claude/skills/ にあるインストール済みコピーにはロックファイルがありません。
• ファイルの配置場所（共有ストアと対象へのプロジェクション）：-a claude-code codex を指定すると、グローバルの実ファイルは ~/.agents/skills/<name>/ に、プロジェクトの実ファイルは <repo>/.agents/skills/<name>/ に配置され、Claude には対応する .claude/skills/<name> のシンボリックリンクが作成されます。OpenCode は正規ストアを直接読み取ります。ほかの対象の組み合わせではコピー方式が選ばれる場合があるため、対象リストを変更したあとは正確なパスを確認してください。ドットファイルへの影響：必要に応じて、グローバル共有ストアを追跡してください（たとえば、~/.agents をドットファイル用リポジトリにシンボリックリンクします）。また、追加／更新のたびに書き換えられる、マシン固有のグローバルロックファイルは gitignore に追加してください。
• リポジトリ内で作成したスキルは別扱いです：リポジトリが所有するスキルが skills-lock.json に存在しない場合、編集可能なソースとして <repo>/.agents/skills/<name> を使い、.claude/skills/<name> のシンボリックリンクを意図的に追跡します。npx はこの一組を所有せず、書き換えることもありません。

インストール済みスキルの有効化／無効化

npx には有効化／無効化の機能がありません。スキルはインストール済み（有効）か、削除済みのどちらかです。スキルをディスク上に残したまま無効にするには、Claude Code の ~/.claude/settings.json にある skillOverrides を使用します。スキルの名前（ソースではありません）をキーとする 4 状態の制御機能で、プラグインのブール値である enabledPlugins よりも詳細に設定できます。

状態	モデルへの表示	/ メニュー内	自動起動	手動 /name
on（デフォルト）	名前＋説明	はい	はい	はい
name-only	名前のみ（コンテキストを節約）	はい	はい	はい
user-invocable-only	非表示	はい	いいえ	はい
off	非表示	非表示	いいえ	いいえ

状態は /skills メニューで切り替える（Space で切り替え、Enter で保存）か、skillOverrides を直接編集してください。skillOverrides は settings.json に保存されるため、有効／無効の状態をバージョン管理できます。

• 無効化には permissions.deny: ["Skill(<name>)"] よりも off を優先してください。deny は呼び出し時にブロックするだけで、コンテキストには引き続き表示されます。off にすると完全に削除され（コンテキストを消費せず、自動起動もしません）。
• 名前の重複に関する注意：オーバーライドは名前をキーにするため、組み込みスキル（例：claude-api）と name: が重複するスキルは絶対にインストールしないでください。"claude-api": "off" を設定すると、組み込みスキルも対象になります。そのようなスキルはインストール時に除外してください（Install a source の include-only に関する注記を参照）。