shunk031-manage-public-private-skills

メモ

この SKILL.md を読んだ後、次のように言ってください：🧰 I read shunk031-manage-public-private-skills.

公開スキルと非公開スキルの管理

スキルの内容は、専用の2つのリポジトリにあります。どちらの dotfiles リポジトリにもスキルの内容は置かれていないため、スキルの変更依頼は、今いる可能性が高いチェックアウトではなく、これらのリポジトリのいずれかを変更する依頼です。

スキルの保管場所

リポジトリ	内容
shunk031/skills	公開可能なすべてのスキル
shunk031/skills-private	内部ホスト、認証情報、内部エンドポイント、または組織内プロセスが本文に記載されたスキル
shunk031/dotfiles	調整スクリプトと公開サブスクリプション。スキルの内容はありません
shunk031/dotfiles-private	非公開サブスクリプション。スキルの内容はありません

判断の基準は、そのスキルの本文に関する一つの質問です。仕事向けに書かれているだけでは非公開にはなりません。内部システムが記載されている場合は非公開になります。判断が難しい場合は、非公開を選び、その理由を伝えてください。

依頼の振り分け

1. スキルを名前で特定します。~/.agents/skills/<name> はインストール済みのコピーです。スキルが存在することはわかりますが、ソースの場所はわかりません。
2. 上記の基準を適用するか、すでにどのリポジトリにあるかを確認して、管理元のリポジトリを決めます。
3. そのリポジトリのタスク用ワークツリーで作業します。インストール済みのコピーは編集しないでください。
4. 変更が両方のスキルリポジトリにまたがる場合は、ワークツリー、コミット、プルリクエストを別々にし、作業の順序を明記してください。

インストール済みのコピーは編集しないでください

~/.agents/skills/<name> は、skills CLI が書き込む実ディレクトリです。ソースへのリンクではなくコピーなので、ここで行った編集は次の skills update で予告なく破棄されます。

これは、プール内の項目が chezmoi のソースツリーへのシンボリックリンクだった以前の構成とは異なります。そのときは、配置済みのスキルを編集するとソースも編集されました。

実行中のバージョンを確認する

スキルの更新が見つからない、または反映されない問題を調査するときは、サブスクライブ先の ref における GitHub の最新の内容、インストール済みの ~/.agents/skills/<name> のコピー、対象セッションが実際に読み込んだ内容を比較します。ローカルのチェックアウトや origin/main はインストール済みのコピーと一致していても古い可能性があるため、リモートを通じて現在の GitHub のコミットまたは blob を確認してください。対象セッションのトランスクリプトを確認するか、許可を得て再読み込みを行ってください。ファイルが更新されているだけでは、そのセッションが読み込んだ証拠にはなりません。比較できない項目は未検証として明示してください。同期を推奨する前に、未デプロイの変更と、現在のソースではもはや規定されていない動作を区別してください。

編集からスキルの実行までのループ

edit in the skill repository worktree
  → gates pass locally
  → pull request
  → merge
  → chezmoi apply on the machine, which runs skills add/update

chezmoi apply は、ファイル監視ループで保存のたびに取得が行われないよう、skills update の実行を1日1回に制限します。マージ直後に強制実行するには、次のコマンドを使います。

DOTFILES_SKILLS_FORCE_UPDATE=1 chezmoi apply    # or: make skills-update

スキルのソース	サブスクリプションの管理
shunk031/skills	リポジトリ全体のサブスクリプションによって追加が検出されます。調整スクリプトは上流での削除として報告された名前を削除します。警告で対応できない名前変更やケースについては、shunk031/dotfiles の SKILLS_RETIRED_NAMES に古い名前を追加します
shunk031/skills-private	shunk031/dotfiles-private の home/dot_config/agents/skills-private.allowlist で該当するエントリーを追加または削除します
サードパーティのリポジトリ	shunk031/dotfiles の install/common/skills.sh で、選択したエントリーを追加または削除します

公開スキルの変更をマージした後は、DOTFILES_SKILLS_FORCE_UPDATE=1 chezmoi apply または make skills-update を実行して、1日ごとの検出制限を回避します。通常の調整では、追加は1日以内に検出され、skills update の上流削除警告で報告された名前は削除されます。警告で確認できない名前変更や削除には、SKILLS_RETIRED_NAMES を使用してください。

非公開スキルの名前を shunk031/dotfiles に絶対に記載しないでください。 これは公開リポジトリであり、名前だけで、スキルを非公開リポジトリに置いて隠そうとしていた内部ホスト、サービス、またはプロセスが明らかになります。調整スクリプトは公開のままにします。移動するのは非公開の名前の一覧だけです。

調整スクリプトは調整時に適用済みの非公開ファイルを読み込み、そのエントリーを公開リストに追加するため、両方のセットが1回の処理でインストールされます。公開ソースしかないマシンにはそのファイルがありませんが、これは正常な状態であり、エラーではありません。

このファイルでは、先頭の # だけがコメントの開始を表します。エントリーにブランチやタグを固定する #<ref> サフィックスが付く場合があるためです。

間違えやすいレイアウトのルール

• skills/<category>/<name>/ にスキルごとのディレクトリを1つ作成し、その中に SKILL.md を置きます。フロントマターの name は、末端のディレクトリ名と一致している必要があります。
• リポジトリのルートに SKILL.md を置かないでください。skills CLI はそこで検出を停止し、そのスキルだけを返すため、インストーラーからほかのすべてのスキルが見えなくなります。
• カテゴリのレイアウトは、skills/ の直下1階層に正確に保ちます：skills/<category>/<name>/。
• evals/evals.json には、任意の動作ケースとして Anthropic の skill-creator 形式を使用します。
• スキルが実行時に必要とするスクリプトは、スキルディレクトリ内に置きます。CLI はスキルディレクトリ全体をプールにコピーするため、ディレクトリ外にあるものはスキルの実行時に存在しません。

評価ケースの作成

動作ケースは evals/evals.json に記述します。ケースを追加または変更する際は、references/eval-authoring.md を参照してください。このリポジトリには、これらのケースを実行または採点するコマンドはありません。

スキルの作成とレビュー

SKILL.md を1つ作成します。エージェントごとのバリアントは作成しないでください。グローバルインストールでは ~/.agents/skills/<name> に単一の正本を置き、各エージェントから参照します。

共通のスキル説明、評価プロンプト、複数エージェント向けのガイダンスでは、別のスキルを <skill-name> skill と表記します。一般的な参照として、Codex の $skill-name や Claude Code の /skill-name の呼び出し構文は使わないでください。これらの表記は、そのエージェント固有の呼び出し構文を説明する場合にのみ使用します。

意見の違いが有益なため、両エージェントのスキル作成用スキルを使って草稿をレビューします。

• Claude Code：/skill-creator
• Codex：$skill-creator（組み込みのもの。場所は ~/.codex/skills/.system/skill-creator）

完了前に

変更を所有するリポジトリを明記し、それぞれのリポジトリのチェックを実行して、どのリポジトリが各変更を所有するかを報告します。コマンド出力、引用した差分、要約に認証情報の値を含めないでください。評価プロンプトが平文でコミットされ、プレースホルダーを使用する必要があるプライベートリポジトリでは、特に重要です。

プルリクエストの作成または更新は通常の作業に含まれます。マージ、chezmoi apply の実行、ランタイム状態の変更は含まれません。これらを行う前に確認してください。