skill-maintainer

スキルメンテナー

概要

スキルライブラリを管理するエージェント向けのメタスキルです。ライブラリには、自作のスキル、外部リポジトリから適応したスキル、共有リポジトリに公開したスキルが含まれます。作成から整理、追跡、同期、公開まで、ライフサイクル全体を扱います。

数十個のスキルで構築され、実運用で検証されたワークフローをまとめたものです。エージェントに依存しないため、ツール名（例：write_file、terminal、delegate_task）は、お使いのプラットフォームに相当するものに置き換えてください。マニフェストによる追跡、階層型同期、差分の並列処理、cron によるドリフト検出といったパターンは、どのエージェントランタイムにも適用できます。

使用するタイミング

• 新しいスキルをゼロから作成するとき
• 外部リポジトリやコレクションからスキルをインポート、または適応するとき
• ローカルのスキルが上流から乖離していないか確認するとき
• 追跡されていない外部ツール依存関係をスキャンするとき
• ローカルのスキルを共有リポジトリに公開するとき
• 毎月の同期チェックを自動化するとき
• 蓄積したスキルライブラリを整理、削減するとき

使用しない場面： 上流の追跡が不要な単発のスキル作成（プラットフォームのスキル作成ツールを直接使用してください）。このスキルが役立つのは、スキルが 5 個以上ある場合、または追跡する外部依存関係が 1 個以上ある場合です。

基本概念

3 つの同期レイヤー

レイヤー	方向	何が乖離するか	例
1. 外部 → ローカル	上流リポジトリ → 自分のスキル	上流で機能追加、バグ修正、API 変更が発生する	baoyu-skills v1.56 → v1.117
2. ローカル → 公開リポジトリ	自分のスキル → 自分の GitHub リポジトリ	ローカルで改善を続けるうちに、リポジトリのコピーが古くなる	ローカルのスキルには新しいフラグがあるが、リポジトリにはない
3. ローカル → 単独リポジトリ	自分のスキル → コードプロジェクトのリポジトリ	スキルに記載されたワークフローと、進化したコードが乖離する	スキルでは CLI v1 を説明しているが、CLI は v3 になっている

3 つすべてを追跡する必要があります。最もよく問題になるのはレイヤー 1 です。最も忘れられやすいのはレイヤー 2 です。一度公開した後も改善を続けると、リポジトリの内容が古くなります。

マニフェスト

スキルのルートに置く単一の UPSTREAM_MANIFEST.md ファイルで、外部に由来するすべてのスキルを追跡します。各スキルにつき 1 行を使用し、3 つすべてのレイヤーを記録します。ファイル形式については templates/upstream-manifest.md を参照してください。

cron ジョブ

自動化スクリプト（scripts/upstream_check.py）が毎月実行され、上流のバージョンを取得して乖離を報告します。Cron の設定セクションを参照してください。

---

スキル作成ワークフロー

0. 作成前に重複を確認する

新しいスキルを作成する前に：

1. 対象カテゴリの既存スキルを一覧表示する
2. 同じ機能を扱うスキルがないか確認する。あれば、兄弟スキルを作成するのではなく、既存のスキルを拡張する
3. 無効化済みまたは廃止済みのスキルが対象を扱っていないか確認する。該当する場合は、重複して作成するのではなく再有効化する

1. 同種のスキルを調査する

対象カテゴリの既存スキルを 2～3 個読み、文体、構成、フロントマターの規約に合わせます。

2. フロントマター

すべてのスキルに必要なもの：

---
name: my-skill-name         # lowercase, hyphens, ≤64 chars
description: >              # ≤1024 chars, starts with trigger context
  Use when <trigger>. <one-line behavior>.
license: MIT
metadata:
  version: 1.0.0            # spec allows only name/description/license/
  author: your-name         # compatibility/metadata/allowed-tools top-level
  platforms: [linux, macos, windows]
---

3. 構成

# <Title>

## Overview          — what and why (1-2 paragraphs)
## When to Use       — bullet triggers + "Don't use for"
## <Topic sections>  — quick-reference tables, exact commands, recipes
## Common Pitfalls   — numbered list of mistakes and fixes
## Verification Checklist — checkbox list

4. サイズの目安

• 説明：1024 文字以下
• SKILL.md 全体：10 万文字以下（8,000～15,000 文字を目安にする）
• 大量の資料やブランチ固有の資料 → references/*.md に配置し、SKILL.md からリンクする
• スクリプト → scripts/*.py に配置し、決定論的に動作させ、可能な限り標準ライブラリのみを使用する

5. 品質の原則

1. プロセスの予測可能性を最適化する — エージェントの動作を変えない行は削除する
2. 各ステップを完了基準で締めくくる — 「変更したすべてのファイルを確認済み」のほうが、「変更を要約する」より適切です
3. ルールは対象の概念のそばに配置する — 1 つの考えをファイル内に散在させない
4. 要点を強い言葉で示す — 長い説明より、「短い反復サイクル」「トレーサーバレット」「根本原因」などを使う
5. 重複や実質的な意味のない記述を削る — それぞれの意味は、信頼できる唯一の情報源にまとめる
6. 早すぎる完了に注意する — エージェントがステップを急いで終える場合は、完了基準を明確にする

よくある品質上の問題：早すぎる完了、重複、堆積（古くなった記述）、肥大化（常に表示される資料が多すぎること）、実質的な意味のない文章。

6. 検証

• フロントマターが YAML として解析でき、バイト 0 から始まり、\n---\n で閉じていること
• name と description が存在し、description が 1024 文字以下であること
• 閉じる --- の後に空でない本文があること

7. マニフェストを更新する

スキルに外部の出自がある場合（上流のものをベースにしている、サードパーティ製ツールをラップしている、またはリポジトリに公開されている場合）、UPSTREAM_MANIFEST.md に行を追加します。これは必須です。追跡されていないスキルは、月次同期チェックで見つかりません。外部依存がまったくないオリジナルのスキルに限り、マニフェストへの記載を省略できます。

---

スキルのキュレーションワークフロー

1. 一覧化して分類する

外部コレクションからスキルを移植するときは、それぞれを分類します。

分類	対応
保持 — 独自性があり、有用で、重複がない	自分の形式に合わせる
重複 — すでに同等のものがある	独自の部分を統合するか、スキップする
内容が薄い／ポインター — URL だけで、実質的な内容がない	スキップする
ジョーク／おもちゃ — 実用的な価値がない	スキップする
機能レイヤー／ルーター — インストーラーとルーターが上流の CLI に処理を委譲する	各バックエンドを評価する。ネイティブのスキルを一括して置き換えない

2. 重複を評価する

各候補を既存のスキルと比較します。内容が重複する場合は、外部のスキルに明確な価値がない限り、ネイティブのスキルを優先します。統合する場合は、既存のスキルに独自の内容を反映し、外部のコピーは破棄します。

3. 自分の形式に合わせる

フロントマター： フレームワーク固有のフィールドをすべて削除します。name、description、version（適合時に更新）、author（例： "Source (adapted)"）は残します。

本文： コピー＆ペーストではなく、全面的に書き直します。

• 英語以外の内容はすべて英語に翻訳する
• フレームワーク固有の参照、サンドボックスのパス、独自ツール名を削除する
• 標準のセクション構成（使用する場面、本文、落とし穴、検証）に組み直す
• 分野固有の詳細をすべて保持する — 正確な 16 進コード、ピクセル寸法、フォント名、タイミング、禁止パターンなどは、スキルの価値そのものです
• 実用的なトリガーワードを追加する

4. 品質監査

# Non-English characters remaining (if source was non-EN)
grep -cP '[\x{4e00}-\x{9fff}]' SKILL.md
# Framework jargon remaining
grep -c 'framework-specific-term\|upstream-field' SKILL.md
# Version/author consistency
grep '^version:\|^author:' SKILL.md

5. 適切なカテゴリに配置する

既存のカテゴリを使用します。安易に新しいトップレベルカテゴリを作らないでください。

6. マニフェストを更新する

適合したスキルごとに、UPSTREAM_MANIFEST.md に行を追加します。エントリーの種類については、「上流の追跡」セクションを参照してください。

---

上流の追跡マニフェスト

スキルのルートに UPSTREAM_MANIFEST.md を維持します。外部の出自があるスキルごとに 1 行を記載します。完全なテンプレートについては templates/upstream-manifest.md を参照してください。

エントリーの種類 — 適切な表を選ぶ

種類	追跡対象	監査方法
適合したスキル	上流のスキルリポジトリにあるスキルを適合したもの	上流の SKILL.md との差分を確認し、バージョンフィールドを比較する
エンジン依存関係	サードパーティ製の CLI／pip ツールをラップするスキル	tool --version と GitHub のリリースを比較する
エンジン追跡スキル	サードパーティ製エンジンを中心に構築されたオリジナルのスキル	pip show <pkg> と GitHub のリリースを確認する
サードパーティ製スキル	外部リポジトリをベースにしたもの（厳密にはスキルリポジトリではないもの）	README／最新版を取得し、概念を比較する
公開済みスキル	自分のリポジトリにプッシュしたローカルのスキル	ローカルのコピーとリポジトリのコピーの diff を取る

外部依存がまったくないオリジナルのスキルは、マニフェストへの記載を省略します。

PORT_NOTES のパターン（複雑な適合作業のゴールドスタンダード）

構造を大きく変更したスキルでは、スキルのディレクトリ内に PORT_NOTES.md を維持します。

# Port Notes — <skill-name>

Ported from <repo-url> v<upstream-version>.

## Changes from upstream
| Change | Upstream | Ours |

### What was preserved
<list of verbatim-copied files>

## Syncing with upstream
<exact curl/diff commands>
<files safe to overwrite vs requiring manual merge>

---

同期監査ワークフロー

毎月、または指示があったときに実行します。

1. マニフェストを読む

最終確認日を確認します。古い行（最終同期から 60 日超）を特定します。

2. レイヤー 1 — 外部 → ローカル

適応した各スキルについて、次の手順を実行します。

1. 上流のバージョンを取得します（GitHub の raw URL または GitHub API）
2. マニフェストに固定されたバージョンと比較します
3. 異なる場合は、ソースを分類して適切な同期方法を適用します。

ソースの種類	同期方法
バージョン管理され、逐語的な内容が多い	逐語的なファイルは上書きし、適応したファイルはマージします
バージョン管理されておらず、全面的な書き換えが必要	現状を維持し、新しい分野の内容のみ差分を確認します
活発に更新中	内容をマージし、上流のセクションを追加して、ローカルの連携部分は維持します
アーカイブ済み／移動済み	URL のみ更新します。上流では形式が変更されている可能性があります
活動が低調	一度だけ確認し、通常は対応不要です

3. レイヤー 2 — ローカル → 公開リポジトリ

公開する各スキルについて、ローカル版とリポジトリのコピーを diff で比較します。ローカル版のほうが新しい場合は、再公開します（ブランド要素を除去し、汎用化して、プッシュします）。

4. レイヤー 3 — ローカル → スタンドアロンリポジトリ

コードリポジトリに関連付けられたスキルについて、リポジトリのワークフロー／CLI に変更がないか確認します。

5. エンジン依存関係のスキャン

# List installed CLI binaries
for tool in <your-tools>; do
  path=$(which $tool 2>/dev/null) && echo "$tool: $path" || echo "$tool: not installed"
done

# List pip packages
for pkg in <your-packages>; do
  pip show $pkg 2>/dev/null | grep -E '^Version:'
done

# Check latest releases
curl -s https://api.github.com/repos/<owner>/<repo>/releases/latest | grep tag_name

マニフェストと照合します。スキルを動作させるためにインストールされているツールのうち、マニフェストに記載されていないものは、未追跡の依存関係です。追加してください。

6. マニフェストを更新

最終確認日、新しい上流バージョン、実施した同期作業を記録します。

並列差分の振り分け

複数の上流ソースを同時に監査する場合：

1. すべての上流ファイルを一括で取得します
2. ソースごとにサブエージェントを並列で振り分け、差分の確認と分類を行います
3. 簡単な更新（URL の修正、逐語的な上書き）は自分で処理します
4. 構造化された推奨事項（維持／マージ／再移植）を集めます
5. 推奨事項に基づいてマージを実行します

これにより、逐次的に行うと 30 分かかる監査を、並列処理で 5 分に短縮できます。

---

スキルを公開リポジトリに公開する

ブランド要素の除去

クライアントや組織に固有のソースを基にしたスキルを公開する場合：

1. すべてのファイルからブランドへの言及を grep で検索します
2. ブランド名、独自のカラーパレット、規制に関する記述、組織内部のファイルパス、社内スタイルを削除または汎用化します
3. ブランド固有の参照ファイルを削除します
4. 具体的な金額を汎用的な表現に置き換えます
5. grep でクリーンな状態になっていることを確認します
6. 公開版のバージョンを上げます

汎用化

プラットフォーム固有の用語	置き換え先
プラットフォームのツール名（image_generate など）	汎用的な説明
プラットフォームのメタデータフィールド	フロントマターから削除
ハードコードされたパス	フォールバック付きの環境変数、または <skill_dir>/...
兄弟スキルへの依存関係	フォールバック付きの環境変数による解決
プラットフォーム固有の配信方法	汎用的な「ユーザーのチャネル経由で送信」

公開版のテスト

• スクリプトを解析します：python3 -c "import ast; ast.parse(open('scripts/main.py').read())"
• インポートが解決されることを確認します：python3 -c "from script import main_func"
• グレースフルデグラデーションが機能することを確認します（任意の依存関係がない状態をシミュレートします）

相互排他性

各スキルを選んで使用するリポジトリでは、兄弟スキル間でコードが重複することになっても、各スキルは自己完結し、単独で実行できる必要があります。共有モジュールを切り出してはいけません。スキルを 1 つだけクローンしたユーザーが、別のスキルのファイルを必要としないようにしてください。

---

Cron の設定 — ドリフトの自動検出

上流とのドリフトを自動で確認するため、月次の cron ジョブを設定します。

1. マニフェストのテンプレートをコピー

cp templates/upstream-manifest.md /path/to/your/skills/UPSTREAM_MANIFEST.md

実際のスキル、上流リポジトリ、バージョンを記載するように編集します。

2. チェックスクリプトをコピーする

cp scripts/upstream_check.py /path/to/your/scripts/

スクリプトは、UPSTREAM_MANIFEST.md からレイヤー 1 とレイヤー 2 のテーブルを直接読み込みます。スキルの一覧はハードコードされておらず、マニフェストが唯一の信頼できる情報源です。

エンジンの依存関係（ENGINE_DEPS）は、マニフェストではなくスクリプトファイル自体で設定します。これは意図的なセキュリティ境界です。マニフェストの内容は外部から編集される可能性がある Markdown なので、その内容から生成されたシェルコマンドは実行しません。次のようなエントリーを追加してください。

ENGINE_DEPS = [
    {"name": "my-cli-tool", "command": ["my-cli", "--version"], "version_regex": r"(\d+\.\d+\.\d+)"},
    {"name": "my-pip-pkg", "command": ["pip", "show", "my-pip-pkg"], "version_regex": r"(\d+\.\d+\.\d+)"},
]

信頼できない設定によるシェルインジェクションを防ぐため、コマンドはリストとして渡します（shell=True は使用しません）。

また、スクリプトの先頭で、または SKILLS_ROOT と LAYER_2_REPO の環境変数を使って、SKILLS_ROOT と LAYER_2_REPO を設定する必要がある場合もあります。

3. cron ジョブを設定する

汎用 cron スケジューラーを使用する場合（プラットフォームに合わせて調整してください）：

# Monthly upstream sync check — 9am on the 1st
0 9 1 * * /path/to/python3 /path/to/scripts/upstream_check.py

エージェントプラットフォームの cron ツールを使用する場合：

{
  "name": "Monthly Upstream Sync Check",
  "schedule": "0 9 1 * *",
  "prompt": "Run the upstream sync check script at /path/to/scripts/upstream_check.py. Report any drift detected. If drift is found, summarize which skills need attention and what changed upstream.",
  "no_agent": true
}

すべて同期されている場合、スクリプトは 0 で終了し、差異が検出された場合は 1 で終了します。標準出力が空でない場合はメッセージとして配信され、空の場合は何も報告されず、通知も行われません。

4. スクリプトによるチェック内容

• レイヤー 1： マニフェストのテーブルを解析し、GitHub から上流の SKILL.md を取得して、バージョンフィールドを比較します。バージョンフィールドがないソースについては、GitHub API を使って最終コミット日を報告します。リポジトリのデフォルトブランチを使用し（なければ master にフォールバックします）、上流ファイルの場所は**skills/<name>/SKILL.md と推定されます**。上流のレイアウトが異なる場合は、オプションの Upstream path 列をマニフェストの行に追加してください。そうしないと、実行のたびに「could not fetch upstream」という警告が表示されます。
• レイヤー 2： ローカルリポジトリと公開済みリポジトリを、バージョンフィールドと SHA-256 コンテンツハッシュの両方で比較します。バージョンの差異（バージョン番号が異なる場合）とコンテンツの差異（バージョンは同じでも内容が異なる場合。たとえば、ローカルで編集したもののバージョンを更新していない、または再公開していない場合）の両方を検出します。
• エンジンの依存関係： 設定されたバージョンチェックコマンド（シェルを使わないリスト形式）を実行し、バージョン文字列を抽出します。

5. 差異レポートへの対応

cron から差異が報告された場合：

1. レポートを読み、変更されたスキルとバージョンの差分を確認します
2. 上流ファイルを一時ディレクトリに取得します
3. 各ファイルがそのまま使えるもの（上書き）か、調整済みのもの（マージ）かを分類します
4. マージする場合は、上流版をベースにして、ローカルでの調整を再適用します
5. 専門用語のチェックを実行し、含まれているべきではない上流固有の用語を grep で検索します
6. PORT_NOTES.md を同期ログで更新します
7. マニフェストを新しいバージョン、日付、ステータスで更新します

---

スキルの拡張と新規作成

新しい機能が既存のスキルと重複する場合：

1. 既存のスキルが中核となる機能をカバーしていますか？ → 不足している部分（リファレンスファイル、スクリプト、ルーティングエントリー）を追加して拡張します
2. 根本的に異なるワークフローやツールセットが必要ですか？ → 新しいスキルが妥当な場合もありますが、まずその理由を明確にしてください
3. 既存のインフラストラクチャー上の薄いレイヤーですか？ → 新しいスキルではなく、リファレンスファイルと必要に応じたスクリプトを用意します

サブトピックが、専用スキルを設けるほど大きくなった場合、包括的なスキルは、重複する内容を残すのではなく、新しいスキルを必ず参照してください。インラインの詳細を参照先に置き換えます：「→ 専用の <skill-name> スキルを参照：…」。内容を重複させると食い違いが生じますが、参照先を示せば信頼できる情報源を一元化できます。

---

落とし穴

1. 浅い移植に価値はありません — ソース固有の用語が残り、トリガーが不足し、構成も見直されていないスキルでは、誰の役にも立ちません。必ず全面的に適応させてください。
2. スキルの水増し — 139 個のスキルを移植するのではなく、価値のある 35 個を選びましょう。適応させる前に、内容の薄いもの、参照だけのもの、重複するもの、目新しさだけのものは容赦なく削除してください。
3. コピー＆ペーストの罠 — ソースの形式がそのまま移植先の形式になることはありません。見出しを翻訳するだけではなく、本文の構成を見直してください。
4. ドメインの詳細不足 — 正確な 16 進コード、ピクセルサイズ、フォントのウェイト、禁止パターンこそがスキルの本質です。それらを削ると価値が失われます。
5. 重複の見落とし — 追加する前に、必ず既存のスキルを確認してください。同じことをするスキルが 2 つあるのは、1 つだけの場合よりもよくありません。
6. 逆方向の同期漏れ（レイヤー 2） — 公開後もローカルで改善を続けます。マニフェストで追跡しないと、リポジトリ側のコピーが気づかないうちに古くなります。必ずプッシュ日を記録してください。
7. 「こちらのバージョンを維持する」という判断も有効です — 上流の差分をすべてマージする必要はありません。こちらのバージョンに上流の内容がすべて含まれている場合は、その判断を記録して次に進んでください。
8. マージを行うサブエージェントには、明示的な保持リストが必要です — 削除してはならないものを列挙しないと、マージを行うサブエージェントが上流の内容ですべて上書きするおそれがあります。
9. エンジン追跡用のスキルには、異なる同期方法が必要です — SKILL.md の内容ではなく、インストール済みのバージョンと最新リリースを比較してください。SKILL.md が最新でも、バイナリが古ければスキルは動作しません。
10. 認証依存の見落とし — 開発者のデスクトップでは「そのまま動く」バックエンドでも、サーバーでは利用できない Cookie、QR ログイン、ブラウザー拡張機能が必要な場合があります。認証が必要になる境界を明示してください。
11. スキルのアトミック性の原則 — スキルはアトミックに保ち、1 つのスキルにつき 1 つの能力を持たせてください。エージェントは設計時ではなく、実行時にスキルを連鎖させます。
12. 移植可能なリポジトリでは相互依存を避ける — 各スキルは自己完結している必要があります。共有モジュールを切り出さないでください。独立性を保つための代償は重複です。
13. 堆積 — スキルは時間とともに短くなるか、明確になるべきです。ルールを追加する際は、そのルールで置き換える古い記述を削除してください。
14. 実質のない文章 — 「注意する」「徹底する」といった記述では、動作が変わることはほとんどありません。確認可能な完了基準に置き換えてください。

検証チェックリスト

• 重複を確認済み — 同じ能力を対象とする既存のスキルがない
• Frontmatter が有効 — --- で始まり、\n---\n で閉じられ、YAML として解析できる
• name（64 文字以下、小文字とハイフンのみ）と description（1024 文字以下）がある
• 構成：概要 → 使用する場面 → 本文 → 落とし穴 → 検証
• 各ステップに確認可能な完了基準がある
• 実質のない文章や重複したルールがない
• ファイル全体が 100k 文字以下（8–15k を目標とする）
• 大量の参考資料は、リンク先の references/*.md ファイルに置かれている
• スクリプトは決定論的で、可能な限り純粋な標準ライブラリのみを使用している
• スキルに外部由来の要素がある場合、UPSTREAM_MANIFEST.md を更新済み
• 複雑な適応の場合、PORT_NOTES.md を作成済み
• 専門用語のチェックに合格 — 適応済みファイルに上流固有の用語がない
• 公開バージョンのブランド表記を削除し、汎用化して、テスト済み
• ドリフト検出用の Cron ジョブを毎月実行するよう設定済み
• tests/test_upstream_check.py（このスキル独自のテストスイート）に合格 — スキルのディレクトリから python3 -m pytest tests/ -q を実行