skill-creator-doctor

スキル作成ドクター

このスキルは、スキルの作成、修復、保守を含む包括的なライフサイクル管理を提供します。

スキルについて

スキルは、専門知識、ワークフロー、ツールを提供することで Claude の機能を拡張する、モジュール式の自己完結型パッケージです。特定の分野やタスクに関する「オンボーディングガイド」のようなものと考えてください。Claude を汎用エージェントから、どのモデルも完全には備えられない手続き的な知識を持つ特化型エージェントへと変えます。

スキルが提供するもの

1. 専門的なワークフロー - 特定の分野における複数ステップの手順
2. ツール連携 - 特定のファイル形式や API を扱うための手順
3. 分野の専門知識 - 企業固有の知識、スキーマ、ビジネスロジック
4. 同梱リソース - 複雑で反復的なタスクに役立つスクリプト、リファレンス、アセット

スキルの構成

すべてのスキルは、必須の SKILL.md ファイルと、任意の同梱リソースで構成されます。

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)

SKILL.md（必須）

メタデータの品質： YAML フロントマターの name と description によって、Claude がスキルを使用するタイミングが決まります。スキルが何を行い、いつ使用するかを具体的に記述してください。「このスキルを使用してください」ではなく、「このスキルは〜の場合に使用します」のように、三人称で記述してください。

同梱リソース（任意）

スクリプト（scripts/）

確定的な信頼性が求められるタスクや、繰り返し書き直されるタスクのための実行可能なコード（Python／Bash など）です。

• 含める場合： 同じコードを何度も書き直している場合、または確定的な信頼性が必要な場合
• 例： PDF 回転タスク用の scripts/rotate_pdf.py
• メリット： トークン効率が高く、動作が確定的で、コンテキストに読み込まずに実行できる場合があります
• 注： パッチ適用や環境固有の調整のために、Claude がスクリプトを読む必要がある場合もあります

リファレンス（references/）

Claude の作業や思考の参考として、必要に応じてコンテキストに読み込むドキュメントや参考資料です。

• 含める場合： Claude が作業中に参照すべきドキュメント
• 例： 財務スキーマ用の references/finance.md、企業の NDA テンプレート用の references/mnda.md、企業ポリシー用の references/policies.md、API 仕様書用の references/api_docs.md
• 用途： データベーススキーマ、API ドキュメント、分野の知識、企業ポリシー、詳細なワークフローガイド
• メリット： SKILL.md を簡潔に保ち、必要だと Claude が判断したときだけ読み込めます
• ベストプラクティス： ファイルが大きい場合（>10k words）は、SKILL.md に grep 検索パターンを含めてください
• 重複を避ける： 情報は SKILL.md かリファレンスファイルのどちらか一方に記載し、両方には記載しないでください。本当にスキルの中核となる情報でない限り、詳細な情報はリファレンスファイルに記載してください。これにより、コンテキストウィンドウを圧迫せずに情報を見つけやすくしながら、SKILL.md を簡潔に保てます。SKILL.md には必須の手順とワークフローのガイダンスだけを残し、詳細な参考資料、スキーマ、例はリファレンスファイルに移してください。

アセット（assets/）

コンテキストに読み込むのではなく、Claude が生成する出力で使用するファイルです。

• 含める場合： スキルで最終出力に使用するファイルが必要な場合
• 例： ブランド素材用の assets/logo.png、PowerPoint テンプレート用の assets/slides.pptx、HTML／React のボイラープレート用の assets/frontend-template/、タイポグラフィ用の assets/font.ttf
• 用途： コピーまたは変更されるテンプレート、画像、アイコン、ボイラープレートコード、フォント、サンプルドキュメント
• メリット： 出力リソースをドキュメントから分離し、Claude がファイルをコンテキストに読み込まずに使用できるようにします

段階的開示の設計原則

スキルでは、コンテキストを効率よく管理するために、3 段階の読み込みシステムを使用します。

1. メタデータ（name + description） - 常にコンテキスト内にあります（約100語）
2. SKILL.md 本文 - スキルが起動したときに読み込まれます（<5k words）
3. 同梱リソース - Claude が必要に応じて読み込みます（無制限*）

*スクリプトはコンテキストウィンドウに読み込まずに実行できるため、無制限です。

スキル作成プロセス

スキルを作成するには、明確な理由があって該当しない場合を除き、「スキル作成プロセス」を順番に進めてください。

ステップ 1：具体例を通じてスキルを理解する

スキルの使用パターンをすでに明確に理解している場合に限り、このステップを省略してください。既存のスキルを扱う場合でも、このステップは役に立ちます。

効果的なスキルを作成するには、そのスキルがどのように使われるか、具体例を通じて明確に理解してください。この理解は、ユーザーから直接例を示してもらうか、例を作成してユーザーのフィードバックで検証することで得られます。

たとえば、画像編集スキルを作成する場合、次のような質問が考えられます。

• 「画像編集スキルでは、どのような機能をサポートすべきですか？編集、回転、それ以外にもありますか？」
• 「このスキルがどのように使われるか、いくつか例を挙げてもらえますか？」
• 「『この画像の赤目を修正して』や『この画像を回転して』といった依頼が考えられます。他にも、このスキルの使い方として思い当たるものはありますか？」
• 「どのような依頼があれば、このスキルを使うべきでしょうか？」

ユーザーに一度に多くの質問をして負担をかけないようにしてください。最も重要な質問から始め、必要に応じて効果を高めるための質問を続けてください。

このステップは、スキルがサポートすべき機能を明確に把握できた時点で完了です。

ステップ 2：再利用可能なスキルの内容を計画する

具体例を効果的なスキルにするには、各例を次のように分析します。

1. その例を一から実行する方法を検討する
2. これらのワークフローを繰り返し実行する際に役立つスクリプト、リファレンス、アセットを特定する

例：「この PDF を回転するのを手伝って」という依頼に対応する pdf-editor スキルを作成する場合、分析結果は次のようになります。

1. PDF を回転するには、毎回同じコードを書き直す必要がある
2. スキルに保存する scripts/rotate_pdf.py スクリプトが役立つ

例：「ToDo アプリを作って」や「歩数を追跡するダッシュボードを作って」という依頼に対応する frontend-webapp-builder スキルを設計する場合、分析結果は次のようになります。

1. フロントエンドのウェブアプリを作成するには、毎回同じ HTML／React のボイラープレートを書く必要がある
2. ボイラープレートを含む HTML／React プロジェクトファイルを格納した assets/hello-world/ テンプレートが役立つ

例：「今日ログインしたユーザー数は？」という依頼に対応する big-query スキルを作成する場合、分析結果は次のようになります。

1. BigQuery でクエリを実行するには、毎回テーブルスキーマとその関係を調べ直す必要がある
2. テーブルスキーマを記載した references/schema.md ファイルが役立つ

スキルの内容を決めるため、各具体例を分析し、含める再利用可能なリソース（スクリプト、リファレンス、アセット）のリストを作成してください。

ステップ 3：スキルを初期化する

ここから、実際にスキルを作成します。

開発対象のスキルがすでに存在し、反復やパッケージ化が必要な場合に限り、このステップを省略してください。その場合は、次のステップに進みます。

新しいスキルをゼロから作成する場合は、必ず init_skill.py スクリプトを実行してください。このスクリプトは、スキルに必要なものがすべて含まれた新しいスキルのテンプレートディレクトリを生成し、スキルの作成をより効率的かつ確実にします。

使い方：

scripts/init_skill.py <skill-name> --path <output-directory>

このスクリプトは次の処理を行います。

• 指定したパスにスキルディレクトリを作成する
• 適切なフロントマターと TODO プレースホルダーを含む SKILL.md テンプレートを生成する
• サンプルリソースディレクトリ scripts/、references/、assets/ を作成する
• 各ディレクトリに、カスタマイズまたは削除できるサンプルファイルを追加する

初期化後、必要に応じて、生成された SKILL.md とサンプルファイルをカスタマイズするか削除してください。

ステップ 4：スキルを編集する

新規作成または既存のスキルを編集する際は、そのスキルが別の Claude インスタンスによって使用されることを念頭に置いてください。Claude にとって有益で、かつ自明ではない情報を含めることに重点を置きます。別の Claude インスタンスがタスクをより効果的に実行するうえで役立つ、手順に関する知識、ドメイン固有の詳細、再利用可能なアセットを検討してください。

まず再利用可能なスキルの内容から始める

実装を始めるには、上で特定した再利用可能なリソースである scripts/、references/、assets/ のファイルから着手します。このステップでは、ユーザーからの情報が必要になる場合があります。たとえば、brand-guidelines スキルを実装する際、ユーザーにブランドアセットやテンプレートを assets/ に、ドキュメントを references/ に提供してもらう必要があるかもしれません。

また、スキルに不要なサンプルファイルやディレクトリは削除してください。初期化スクリプトは構成例として scripts/、references/、assets/ にサンプルファイルを作成しますが、ほとんどのスキルではすべてが必要になるわけではありません。

SKILL.md を更新する

文体： スキル全体を、二人称ではなく命令形／不定詞形（動詞から始まる指示）で記述してください。客観的で指示的な表現を使います（「X を実行するには、Y を行う」のように記述し、「X を行うべきです」や「X を行う必要がある場合は」のような表現は避けます）。これにより、AI が利用する際の一貫性と明確さを保てます。

SKILL.md を完成させるため、次の質問に答えてください。

1. このスキルの目的は何ですか。数文で説明してください。
2. どのようなときにこのスキルを使用すべきですか。
3. 実際には、Claude はこのスキルをどのように使用すべきですか。Claude が使い方を理解できるよう、上で作成した再利用可能なスキルの内容をすべて参照してください。

ステップ 5：スキルをパッケージ化する

スキルの準備ができたら、ユーザーと共有するため、配布可能な zip ファイルにパッケージ化します。パッケージ化の処理では、すべての要件を満たしていることを確認するため、まずスキルが自動的に検証されます。

scripts/package_skill.py <path/to/skill-folder>

出力ディレクトリの指定は任意です。

scripts/package_skill.py <path/to/skill-folder> ./dist

パッケージ化スクリプトは次の処理を行います。

1. 検証：スキルを自動的に検証し、次の項目を確認します。

   • YAML フロントマターの形式と必須フィールド
   • スキルの命名規則とディレクトリ構成
   • 説明の完全性と品質
   • ファイルの整理とリソース参照

2. パッケージ化：検証に合格すると、スキル名にちなんだ名前（例：my-skill.zip）の zip ファイルを作成します。配布に適したディレクトリ構成を維持しながら、すべてのファイルを含めます。

検証に失敗すると、スクリプトはエラーを報告し、パッケージを作成せずに終了します。検証エラーを修正してから、パッケージ化コマンドを再実行してください。

ステップ 6：反復する

スキルをテストした後、ユーザーから改善の依頼がある場合があります。スキルを使用した直後に、スキルの動作に関する最新の状況を踏まえて依頼されることもよくあります。

反復ワークフロー：

1. 実際のタスクでスキルを使用する
2. 問題点や非効率な点に気づく
3. SKILL.md または同梱リソースで更新すべき内容を特定する
4. 変更を実装し、再度テストする

スキルの修復とメンテナンス

スキルが動作しなくなったとき

さまざまな問題が原因で、スキルを読み込めないことがあります。よくある症状は次のとおりです。

• スキルを有効にしようとしたときの 「Unknown skill」エラー
• skills.json 内の レジストリエントリの欠落
• SKILL.md のフロントマターにおける メタデータ形式の不備
• ディレクトリやファイルの欠落などの 構造上の問題

スキルの自動修復

組み込みの修復機能を使用して、よくある問題を自動的に診断し、修正します。

# Repair a specific skill
scripts/repair_skill.py <skill-name>

# Diagnose without repairing
scripts/repair_skill.py --diagnose <skill-name>

# List all skills with issues
scripts/repair_skill.py --list-issues

よくある修復シナリオ

シナリオ 1：スキルがレジストリに見つからない

問題：「Error: Unknown skill: my-skill-name」 解決策：修復スクリプトは、SKILL.md から抽出した適切なメタデータを使って、欠落しているスキルを skills.json レジストリに自動的に追加します。

シナリオ 2：フロントマターの形式が無効

問題：YAML の解析エラー、または必須フィールドの欠落 解決策：修復スクリプトはフロントマターの形式を修正し、必須フィールド（name、description）の欠落を補い、適切な YAML 構造に整えます。

シナリオ 3: スキル構造の欠落

問題: SKILL.md または必須ディレクトリの欠落 解決策: 修復スクリプトが構造上の問題を特定し、修正のためのガイダンスを提供します。

シナリオ 4: カテゴリが定義されていない

問題: スキルがレジストリ内で未定義のカテゴリを参照している 解決策: 修復スクリプトが不足しているカテゴリ定義を skills.json に追加します。

手動によるレジストリの修正

上級ユーザーは、skills.json を手動で編集できます。

{
  "skills": {
    "my-skill": {
      "name": "My Skill Display Name",
      "category": "create",
      "triggers": ["using my skill", "activate my skill"],
      "keywords": ["my", "skill", "automation"],
      "activation_count": 0,
      "last_used": null,
      "related_skills": ["skill-creator-doctor"],
      "description": "Skill description for discovery"
    }
  },
  "categories": {
    "create": {
      "description": "Skills for building new components and features",
      "color": "#45B7D1"
    }
  }
}

スキルのヘルスモニタリング

定期的なメンテナンスにより、スキルが機能し続けることを保証します。

# Validate a single skill
python scripts/quick_validate.py <path/to/skill>

# Comprehensive system health check
scripts/repair_skill.py --list-issues

予防のためのベストプラクティス

1. 作成後は必ずパッケージングスクリプトでスキルを検証する
2. 作成または変更後すぐにスキルの読み込みをテストする
3. ディレクトリ名とレジストリエントリで一貫した命名を使用する
4. SKILL.md の frontmatter で適切な YAML 形式を維持する
5. スキルのメタデータを変更する際はレジストリエントリを更新する

実例: ts-foundation-restorer

ts-foundation-restorer スキルは、このシステムを使用して正常に修復されました。

問題: スキルはファイルシステムに存在していたが、検出できなかった 根本原因: skills.json にレジストリエントリが欠落していた 解決策: SKILL.md から抽出したメタデータを含む適切なレジストリエントリを追加した 結果: スキルが検出可能かつ機能するようになった

これは、修復システムが手動介入なしでスキル読み込みの失敗を迅速に解決できることを示しています。

高度なトラブルシューティングガイド

Claude Code のスキル検出の仕組みを理解する

Claude Code は、スキル検出に宣言型のプロンプトベースのシステムを使用します。このシステムは複数の場所からスキルをスキャンし、メタデータをシステムプロンプトに読み込みます。Claude はテキストによる説明に基づいてスキルをいつ呼び出すかを決定します。コードレベルでのアルゴリズム的なマッチングはありません。

重要な YAML Frontmatter の要件

「Unknown skill」エラーの最も一般的な原因は、YAML frontmatter の検証失敗です。

必須フィールド:

• name: 小文字、数字、ハイフンのみ(ケバブケース)を使用する必要があり、最大 64 文字
• description: 簡単な説明(最大 1024 文字)

正しい形式:

---
name: my-skill-name
description: Brief description of what the skill does and when to use it
---

よくある検証失敗:

❌ タイトルケース: name: My Skill Name ❌ snake_case: name: my_skill_name ❌ camelCase: name: mySkillName ❌ アンダースコア: name: my_skill_name ❌ XML タグ: <name>my-skill</name> ❌ 予約語: "anthropic"、"claude" を含む名前

体系的なトラブルシューティングプロセス

1. YAML Frontmatter の形式を検証する

よくある問題を確認します。

# View the frontmatter
cat .claude/skills/my-skill/SKILL.md | head -n 15

# Common issues to look for:
# - Missing opening or closing ---
# - Tabs instead of spaces (use spaces only)
# - Unquoted strings with special characters
# - Extra spaces or hidden characters

2. 不可視文字とエンコーディングを確認する

YAML が正しく見えても、不可視文字が解析失敗の原因になることがあります。

# Check for hidden characters
cat -A .claude/skills/my-skill/SKILL.md | head -n 15

# Verify UTF-8 encoding
file .claude/skills/my-skill/SKILL.md

3. ファイル構造を検証する

ディレクトリ構造が正しいことを確認します。

.claude/skills/my-skill/
└── SKILL.md  (required, exact capitalization)

ファイルは SKILL.md(すべて大文字)という名前でなければなりません。

4. Claude Code のキャッシュをクリアする

Claude Code は、スキル変更後に更新されない可能性のあるキャッシュを保持しています。

# Option 1: Use /clear command (may not fully clear skill cache)
# In Claude Code session, type:
/clear

# Option 2: Completely restart Claude Code (recommended)
# Exit current session and restart:
claude

キャッシュの問題が持続する場合:

• Claude Code を完全に終了する
• キャッシュディレクトリをクリアする(存在する場合):
  • macOS: ~/Library/Caches/Claude/
• 残っている一時ファイルをクリアする
• Claude Code を再起動する

5. 最小構成のスキルでテストする

問題を切り分けるためのテストスキルを作成します。

mkdir -p .claude/skills/test-skill
cat > .claude/skills/test-skill/SKILL.md << 'EOF'
---
name: test-skill
description: Simple test skill for validation
---

# Test Skill

This is a test skill.
EOF

Claude Code を再起動し、最小構成のスキルが機能するかテストします。

既知の問題と制限事項

1. SDK と CLI の動作の違い

スタンドアロンの CLI と比較して、Claude Agent SDK を使用する場合、スキルが正しく読み込まれないことがあります。SDK を使用している場合、これは既知の問題であり、設定が正しくてもスキルが自動検出されません。

2. スキルシステムのキャッシュの不整合

• /clear コマンドは、スキル関連のキャッシュを完全にクリアしない可能性があります
• セッション中に追加または変更されたスキルは、認識されるために完全な再起動が必要になる場合があります
• 一部のユーザーは、Claude Code を完全に終了して再起動した後にのみスキルが読み込まれると報告しています

3. フロントマターのパーサーの厳密さ

フロントマターのパーサーは非常に厳格で、一見有効に見えるファイルも拒否する場合があります。パーサーは特に次の点を確認します。

• YAML の正確な構文（タブを使わず、適切なスペースを使用すること）
• ケバブケースの命名規則
• 予約語が含まれていないこと
• メタデータに XML タグや特殊文字が含まれていないこと

高度なデバッグ手法

1. 動作するスキルと動作しないスキルを比較する

一部のスキルは正常に動作するため、フロントマターの形式を正確に比較してください。

# View working skill
cat .claude/skills/working-skill/SKILL.md | head -n 15

# View broken skill
cat .claude/skills/broken-skill/SKILL.md | head -n 15

# Look for differences in:
# - Spacing (tabs vs spaces)
# - Line endings (CRLF vs LF)
# - Character encoding
# - YAML structure

2. Claude Code のログを確認する

ログを表示して、スキルの読み込みエラーの詳細を確認してください。

• macOS：~/Library/Logs/Claude/
• Linux：--verbose フラグを付けて、ターミナルの出力を確認します
• 解析エラーやスキルの検証失敗を探します

推奨する解決手順

トラブルシューティングの経験に基づき、次の手順を順番に実行してください。

1. SKILL.md ファイルを作り直し、確実に問題のない形式にします。

   • 内容を新しいファイルにコピーします
   • 名前には小文字、数字、ハイフンのみを使用します
   • インデントにはタブではなくスペースを使用します
   • UTF-8 エンコーディング、Unix 改行コード（LF）で保存します

2. 名前の形式を正確に確認する：

   ---
   name: my-skill-name
   description: Your description here
   ---
   

3. Claude Code を完全に再起動する：

   • 現在のセッションを終了します
   • すべてのターミナルウィンドウを閉じます
   • claude を実行して新たに起動します

4. スキルが認識されるかテストする：

   • 「利用可能なすべてのスキルを一覧表示して」と尋ねます
   • 自分のスキルが表示されるか確認します

5. それでも失敗する場合は、スキル名を変更してみてください。

   • my-skill や skill-fix のような、よりシンプルな名前に変更します
   • 短い名前のほうがうまくいく場合があります

一部のスキルは動作し、ほかは動作しない理由

一部のスキルは読み込まれる一方、形式が同じでもほかのスキルが読み込まれないという不整合は、次の原因を示唆しています。

1. 目視ではわからない微妙な形式の違い（タブとスペースの違い、改行コードなど）
2. 特定のファイルにおける文字エンコーディングの問題
3. そのスキルに限ったキャッシュの破損
4. 名前の検証における特殊なケース

名前を変更しても解決しないことから、問題は名前ではなく、ファイルの内容（エンコーディング、隠し文字、YAML 構造など）にある可能性が高いと考えられます。

スキルの統合と最適化

重複の特定、競合の解決、類似スキルの統合、古くなったスキルのアーカイブによって、増え続けるスキルコレクションを管理します。これにより、スキルのエコシステムを効率的で保守しやすく、冗長性のない状態に保てます。

使用する場面

• 増え続けるスキルコレクション（10 個以上）の管理
• 目的が似ているスキルの重複や重なりが疑われる場合
• 技術スタックを変更する場合（例：MongoDB から PostgreSQL への移行）
• 非推奨の機能や古くなったワークフローを削除する場合
• 似た名前、トリガー、キーワードによって有効化の混乱が起きている場合
• 整理を改善するため、スキルのエコシステムを最適化したい場合

主なワークフロー

ワークフロー 1：スキャンと一覧の作成

使用統計やメタデータを含む、すべてのスキルの包括的な一覧を作成します。

# Generate skill inventory
python scripts/scan_skills.py --output skill_inventory.json

実行内容：

• skills/ ディレクトリ内のすべてのスキルをスキャンします
• メタデータ（名前、説明、カテゴリ、トリガー、キーワード）を抽出します
• config/skills.json から使用統計を読み取ります
• 同梱リソース（スクリプト、リファレンス、アセット）を分析します
• 要約統計を含む構造化 JSON を出力します

出力に含まれる内容：

• スキルのメタデータと目的
• 有効化回数と最終使用日
• リソース分析（スクリプト、リファレンス、アセット）
• カテゴリの分布
• 使用パターンと傾向

ワークフロー 2：類似性を分析する

統合候補、トリガーの競合、古くなったスキルを特定します。

# Analyze for consolidation opportunities
python scripts/analyze_similarity.py --inventory skill_inventory.json --threshold 0.65

# Custom threshold
python scripts/analyze_similarity.py --inventory skill_inventory.json --threshold 0.80

類似性の検出方法：

1. キーワード／トリガーの重複（Jaccard 類似度）

   • J(A,B) = |A ∩ B| / |A ∪ B|
   • 共通のトリガーを持つスキル（競合）を特定します
   • トリガーの重複率が 50% を超えるものを検出します

2. コンテンツの類似性

   • スキルの説明とメタデータを比較します
   • 意味的な類似性を分析します
   • 相互に補完するワークフローを特定します

3. カテゴリの照合

   • 同じカテゴリのスキルは、統合できる可能性が高くなります
   • 関連するドメイン固有のスキルをグループ化します

4. 使用統計

   • 未使用のスキル（activation_count = 0）を特定します
   • 古くなったスキル（last_used > 6 months）を見つけます
   • 使用パターンに基づいて優先順位を付けます

出力：

• skill_consolidation_report.md（人が読める形式の推奨事項）
• skill_analysis.json（詳細な分析データ）
• 優先度の分類：高（>80%）、中（65～80%）、要確認（<65%）

ワークフロー 3：統合レポートを確認する

生成されたレポートを分析し、十分な情報に基づいて判断します。

# Open the generated report
cat skill_consolidation_report.md

# Key sections to review:
# - High Priority Merge Candidates (>80% similarity)
# - Trigger Conflicts (ambiguous activations)
# - Obsolete Skills (unused or outdated)
# - Medium Priority Candidates (65-80% similarity)

判断基準：

次の場合は統合します：

• 機能が重複し、類似度が 80% 以上の場合
• トリガーの競合により、起動が曖昧になる場合
• 同じドメイン内でワークフローが相互に補完し合う場合
• ほとんど使用されないスキルが、別のスキルに自然に組み込める場合

次の場合はアーカイブします：

• 一度も使用されていない場合（activation_count = 0）
• 6 か月以上使用されていない場合
• 技術スタックが変更された場合（古い技術への言及）
• プロジェクトから機能が削除された場合

ワークフロー 4：スキルの統合を実行する

機能を維持しながら、類似するスキルを安全に統合します。

自然言語コマンド：

"Merge task-creator and task-manager based on the consolidation report"
"Combine these duplicate Vue debugging skills"
"Merge skill-a into skill-b, keep skill-b as primary"

統合プロセス：

1. 両方のスキルを分析する - SKILL.md ファイルをすべて読みます
2. 固有のコンテンツを特定する - それぞれのスキルに含まれる異なる、または価値のあるコンテンツを見つけます
3. 統合した SKILL.md を作成する - 固有の機能をすべて維持します
4. メタデータを統合する - トリガー、キーワード、related_skills を統合します
5. 同梱リソースをコピーする - スクリプト／リファレンス／アセットをメインのスキルに移動します
6. レジストリを更新する - 統合したメタデータで config/skills.json を変更します
7. 2 つ目のスキルをアーカイブする - ドキュメントとともに skills/archive/ に移動します
8. 統合したスキルを検証する - 正しく読み込まれ、機能することを確認します
9. 完了を報告する - 統合したトリガー／キーワードと変更内容を一覧表示します

レジストリの更新：

{
  "merged_from": ["task-creator", "task-editor"],
  "activation_count": 37,  // Sum of both skills
  "triggers": ["create task", "edit task", "manage tasks", "task operations"],
  "last_used": "2025-11-13"  // Most recent date
}

ワークフロー 5：古くなったスキルをアーカイブ／削除する

未使用または古くなったスキルを安全に整理します。

自然言語コマンド：

"Archive old-mongodb-helper skill, we migrated to PostgreSQL"
"Remove unused-experimental-skill, it was never activated"
"Archive all skills related to deprecated feature X"

アーカイブプロセス：

1. アーカイブディレクトリを作成する - skills/archive/[skill-name]archived[date]/
2. スキルを移動する - スキルディレクトリ全体を移動します
3. ARCHIVED.md を作成する - 理由、日付、復元手順を記録します
4. レジストリを更新する - config/skills.json からスキルのエントリを削除します
5. 参照を更新する - 他のスキルの related_skills から削除します
6. アーカイブインデックスを更新する - skills/archive/ARCHIVE_INDEX.md に追加します

ARCHIVED.md のテンプレート：

# Archived: [skill-name]

**Archive Date:** 2025-11-13
**Reason:** [Archive reason]
**Original Description:** [Skill description]

## Archive Reason
[Detailed explanation of why skill was archived]

## Restoration Instructions
To restore this skill:
1. Move directory from `archive/` back to `skills/`
2. Add entry to `config/skills.json`
3. Update any related_skills references
4. Test skill loading

## Related Skills
[List of skills that referenced this skill]

自然言語インターフェース

自然な会話を通じて統合機能を使用します。

分析コマンド：

• 「スキルをスキャンして重複を見つけて」
• 「統合できるスキルがあるか分析して」
• 「6 か月間使っていないスキルを見つけて」
• 「スキルのトリガーに競合がないか確認して」
• 「統合できるものはある？」

アクションコマンド：

• 「[skill-a] と [skill-b] を統合して」
• 「[reason] のため [old-skill] をアーカイブして」
• 「これらの Vue のデバッグスキルを統合して」
• 「MongoDB から PostgreSQL に移行したので、古いスキルを整理して」
• 「『create task』のトリガーの競合を解消して」

例

例 1：重複するスキル

User: "I created task-creator and later task-manager. Are they duplicates?"

Claude analyzes:
- task-creator: "Create new tasks" (triggers: ["create task", "new task"], activations: 25)
- task-manager: "Create, edit, delete tasks" (triggers: ["manage tasks", "create task"], activations: 12)

Finding: 87% similar (overlapping triggers, similar purpose)

Recommendation: Merge into task-manager (more used, broader scope)

Execution:
- Merges both skills into task-manager
- Archives task-creator
- Updates registry with merged_from field
- Reports completion with consolidated triggers

例 2：技術スタックの移行

User: "We migrated from MongoDB to PostgreSQL. Which skills should I clean up?"

Claude:
- Scans all skills
- Finds: mongodb-helper, mongo-query-builder, mongodb-schema
- Recommends: Archive all three, update database-helper to focus on PostgreSQL

Execution:
- Archives MongoDB skills with proper documentation
- Updates database-helper with PostgreSQL-specific content
- Removes MongoDB skills from registry
- Updates related_skills references

例 3：トリガーの競合

User: "Check for trigger conflicts"

Claude finds:
- "create task" used by: task-creator, task-manager, project-tasks

Recommendation:
- task-creator: Change to "create new task", "add task"
- task-manager: Keep "manage tasks", "organize tasks"
- project-tasks: Change to "create project task", "add to project"

Execution:
- Updates triggers in each skill's registry entry
- Validates no conflicts remain
- Reports updated trigger mappings

ベストプラクティス

統合したスキルの命名

• より広い範囲を表す名前を使います：task-creator + task-editor → task-manager
• ドメイン + アクションのパターンを使います：[domain]-[action]
• 曖昧な名前（「helper」、「utils」）は避けます
• 名前は 64 文字以内にし、ケバブケースを使います

メンテナンススケジュール

• 毎月（5分）： 明らかな重複がないか簡単に確認します
• 四半期ごと（30～60分）： 全体を分析し、統合します
• 大規模な変更の後： 技術スタックの移行、機能の削除

品質保証

• 元のスキルをアーカイブする前に、必ず統合したスキルをテストします
• アーカイブのドキュメントを充実させます
• 変更後にレジストリの整合性を検証します
• 大規模な統合の後にスキルの読み込みをテストします

実装スクリプト

scan_skills.py

スキルディレクトリをスキャンし、メタデータ、使用統計、同梱リソースの分析、絵文字の割り当てを含む包括的なインベントリを抽出します。

analyze_similarity.py

複数の類似性検出手法を使用してスキルのインベントリを分析し、統合候補、トリガーの競合、古くなったスキルを特定します。絵文字を活用した表示で、詳細な統合レポートを生成します。

assign_emoji.py

スキルのための包括的な絵文字管理ユーティリティです。カスタム絵文字の割り当て、競合検出、カテゴリ別のデフォルト設定、一括操作に対応しています。レジストリと SKILL.md のフロントマターの両方と連携します。

参考資料

• references/skill-consolidation-guide.md - 例を含むクイックスタートガイド
• skill_consolidation_report.md - 生成された分析レポート
• skill_analysis.json - 詳細な分析データ

スキルの絵文字管理

カスタム絵文字を割り当てて、スキルを視覚的に識別できるようにします。絵文字はスキルの有効化時や実行時に表示され、アクティブなスキルをすぐに認識できるため、ユーザーエクスペリエンスが向上します。

絵文字管理を使用する場面

• 視覚的なスキル識別： 有効化時にスキルをすぐに認識できるようにします
• カテゴリの整理： スキルカテゴリで一貫した絵文字を使用します（🐛 デバッグ、⚡ 作成、🔧 修正）
• カスタムブランディング： 重要なスキルや頻繁に使用するスキルに、特定の絵文字を割り当てます
• フォルダーの整理： フォルダー名をレジストリの絵文字割り当てと一致させます
• チーム内の一貫性： チームのスキルコレクション全体で、絵文字の使い方を統一します

絵文字の割り当てワークフロー

ワークフロー 1：個々のスキルへの絵文字の割り当て

自然言語コマンド：

"Assign 🎨 emoji to ui-design skill"
"Set custom emoji for vue-debugging to 🐛"
"Give the database-helper skill the 🗃️ emoji"

スクリプトの実行：

# Assign specific emoji to skill
python scripts/assign_emoji.py --skill vue-debugging --emoji "🐛"

# The system will:
# 1. Validate emoji character
# 2. Check for conflicts with other skills
# 3. Update skills.json registry
# 4. Update SKILL.md frontmatter
# 5. Report success or conflicts

ワークフロー 2：カテゴリ別の絵文字の割り当て

自然言語コマンド：

"Assign 🐛 emoji to all debug skills"
"Set ⚡ emoji for create category skills"
"Apply default emojis to all skills in fix category"

スクリプトの実行：

# Assign emoji to entire category
python scripts/assign_emoji.py --category debug --emoji "🐛"

# System will:
# 1. Find all skills in the category
# 2. Check for emoji conflicts
# 3. Update all skills in category
# 4. Handle conflicts with user confirmation

ワークフロー 3：絵文字の自動割り当て

自然言語コマンド：

"Auto-assign default emojis to all skills"
"Apply category-based emojis to skills without custom assignments"
"Set up emoji defaults for my entire skill collection"

スクリプトの実行：

# Auto-assign based on categories
python scripts/assign_emoji.py --auto-assign

# System will:
# 1. Identify skills without emojis
# 2. Apply category default emojis
# 3. Handle conflicts intelligently
# 4. Report assignments and any conflicts

ワークフロー 4：絵文字の競合解決

自然言語コマンド：

"Check for emoji conflicts in my skills"
"Show me which skills have duplicate emojis"
"Suggest alternative emojis for conflicting skills"

スクリプトの実行：

# List all emoji assignments and conflicts
python scripts/assign_emoji.py --list

# The system will:
# 1. Show all emoji assignments
# 2. Highlight conflicts (multiple skills with same emoji)
# 3. List skills without emojis
# 4. Provide suggestions for resolution

ワークフロー 5：絵文字の提案

自然言語コマンド：

"Suggest emojis for my new skill"
"What emoji would work best for api-integration skill?"
"Recommend emojis based on my skill description"

スクリプトの実行：

# Get emoji suggestions for a skill
python scripts/assign_emoji.py --suggest skill-name

# System will:
# 1. Analyze skill name, category, and description
# 2. Suggest relevant emojis based on keywords
# 3. Check for conflicts with existing assignments
# 4. Provide context for each suggestion

絵文字カテゴリのデフォルト設定

システムには、一般的なスキルカテゴリ向けの組み込み絵文字デフォルト設定が用意されています。

{
  "emoji_defaults": {
    "debug": "🐛",      // Bug fixing and troubleshooting
    "create": "⚡",     // Building and creating
    "fix": "🔧",        // Maintenance and repair
    "optimize": "🚀",   // Performance and optimization
    "test": "🧪",      // Testing and validation
    "analyze": "📊",    // Analysis and reporting
    "implement": "🛠️",  // Implementation and development
    "specialized": "⭐", // Specialized functionality
    "meta": "🎯",       // Meta-skills and management
    "emergency": "🚨",   // Emergency and critical issues
    "default": "⚙️"     // Generic fallback
  }
}

フォルダー名との連携

skill-folder-emoji-updater スキルを使って、フォルダー名をレジストリの割り当てと同期します。

自然言語コマンド：

"Update all skill folders to match their registry emojis"
"Add 🐛 emoji to all debug skill folders"
"Make sure my skill folders have emoji prefixes"

スクリプトの実行：

# Update all folders to match registry
python ../skill-folder-emoji-updater/scripts/update_folder_emojis.py --all

# Update specific category folders
python ../skill-folder-emoji-updater/scripts/update_folder_emojis.py --category debug

# Dry run to see what would change
python ../skill-folder-emoji-updater/scripts/update_folder_emojis.py --all --dry-run

自然言語インターフェース

絵文字の割り当て：

• 「ui-design スキルに 🎨 絵文字を割り当てて」
• 「vue-debugging に 🐛 絵文字を付けて」
• 「task-manager にカスタム絵文字を設定して」

カテゴリの管理：

• 「すべてのデバッグスキルにバグの絵文字を適用して」
• 「作成カテゴリには稲妻を使って」
• 「自分のスキルのデフォルト絵文字を設定して」

競合解決：

• 「絵文字の競合を確認して」
• 「重複した絵文字を使っているスキルを表示して」
• 「絵文字の競合を自動で修正して」

フォルダーとの連携：

• 「スキルフォルダーを絵文字で更新して」
• 「フォルダー名をレジストリと同期して」
• 「すべてのスキルフォルダー名の先頭に絵文字を追加して」

検索と分析：

• 「新しいスキルに絵文字を提案して」
• 「すべての絵文字の割り当てを一覧表示して」
• 「絵文字が必要なスキルを表示して」

例

例 1：個々のスキルへの割り当て

User: "Assign 🎨 emoji to ui-design skill"

System:
✅ Assigned emoji 🎨 to skill: ui-design
✅ Updated skills.json registry
✅ Updated SKILL.md frontmatter
✅ Updated display name: 🎨 UI Design

Natural Language Usage:
- "🎨 Using ui-design skill for component styling"
- "🎨 UI Design skill activated for layout fixes"

例 2：カテゴリへの割り当て

User: "Assign 🐛 emoji to all debug skills"

System:
⚠️ Emoji conflicts detected for 🐛:
   - component-debugger (existing)
   - vue-debugger (existing)

Continue anyway? (y/N): y

✅ Assigned emoji 🐛 to 5 skills in category 'debug'
   - api-debugger → 🐛 API Debugger
   - performance-debug → 🐛 Performance Debug
   - state-debugger → 🐛 State Debugger
   - render-debug → 🐛 Render Debug
   - memory-debug → 🐛 Memory Debug

例 3：フォルダーとの連携

User: "Update all skill folders to match their registry emojis"

System:
📋 Would rename 8 skill folders:
   🐛 vue-debugging (from: vue-debugging)
   ⚡ task-creator (from: task-creator)
   🔧 pinia-fixer (from: pinia-fixer)
   📊 analytics (from: analytics)
   ...

Apply changes? (y/N): y

✅ Updated 8 skill folders with emojis

技術的な実装

レジストリへの保存

{
  "skills": {
    "vue-debugging": {
      "name": "Vue Debugging",
      "emoji": "🐛",
      "display_name": "🐛 Vue Debugging",
      "category": "debug"
    }
  }
}

フロントマターとの連携

---
name: vue-debugging
emoji: "🐛"
description: Debug Vue.js applications
---

検証機能

• 絵文字の検証：有効なUnicode絵文字のみが使われていることを確認します
• 競合の検出：重複した絵文字の割り当てを特定します
• カテゴリの一貫性：絵文字とカテゴリの論理的な関係を維持します
• 相互参照の同期：レジストリとSKILL.mdの内容を一致させます

ベストプラクティス

絵文字の選択ガイドライン

1. 関連性：スキルの目的に関連する絵文字を選びます
2. カテゴリの一貫性：可能な場合はカテゴリのデフォルトを使用します
3. 一意性：同じカテゴリ内での絵文字の重複を避けます
4. 明確さ：広く認識されている絵文字を使用します（🐛、⚡、🔧など）
5. アクセシビリティ：絵文字がさまざまなプラットフォームで正しく表示されることを確認します

割り当てのワークフロー

1. 競合を避けるため、既存の割り当てを確認します
2. まずカテゴリのデフォルトを検討します
3. 広範囲に割り当てる前に絵文字をテストします
4. レジストリとフロントマターの両方を更新します
5. 変更後にスキルが読み込まれることを確認します

メンテナンススケジュール

• 毎月：新しいスキルの絵文字割り当てを確認します
• 四半期ごと：絵文字の競合と一貫性を確認します
• スキル作成後：作成プロセスの一環として絵文字を割り当てます
• 統合時：統合したスキルの絵文字を維持または更新します

スキルエコシステムとの連携

連携対象：

• skill-creator-doctor：絵文字の割り当てと管理に使用します
• skill-folder-emoji-updater：フォルダー名の同期に使用します
• スキル統合システム：絵文字で強化されたレポートと表示に使用します
• skills.jsonレジストリ：絵文字の割り当てを一元管理します

強化機能：

• 有効化時のスキルの視覚的な識別
• 一貫した絵文字によるカテゴリ別の整理
• レジストリと一致するフォルダーの視覚的な整理
• 検出と解決による競合の防止

---

ユーザーによる検証の必須要件

ポリシー：ユーザーの確認なしに修正を主張しない

重要：「修正済み」「解決済み」「動作している」「完了」と、問題、バグ、課題について主張する前に、以下の検証手順を必ず実施してください。

ステップ1：技術的な検証

• 該当するテストをすべて実行します（ビルド、型チェック、単体テスト）
• コンソールエラーがないことを確認します
• 修正のスクリーンショットや証拠を取得します

ステップ2：ユーザーへの検証依頼

必須：AskUserQuestionツールを使用して、修正を検証するようユーザーに明示的に依頼します。

"I've implemented [description of fix]. Before I mark this as complete, please verify:
1. [Specific thing to check #1]
2. [Specific thing to check #2]
3. Does this fix the issue you were experiencing?

Please confirm the fix works as expected, or let me know what's still not working."

ステップ3：ユーザーの確認を待つ

• ユーザーの返信があるまで、成功したと主張してはいけません
• ユーザーの確認なしにタスクを「完了」としてはいけません
• ユーザーによる検証なしに「修正済み」「解決済み」「動作している」といった表現を使ってはいけません

ステップ4：ユーザーからのフィードバックへの対応

• ユーザーが確認した場合：修正を記録し、完了としてマークします
• ユーザーが問題を報告した場合：デバッグを続け、検証サイクルを繰り返します

ユーザーの検証なしに禁止される行為

• バグが「修正済み」と主張すること
• 機能が「動作している」と述べること
• 問題を「解決済み」としてマークすること
• 機能が「完了」と宣言すること
• 修正に関して成功を主張すること

ユーザーへの検証依頼前に必要な証拠

1. 技術テストに合格していること
2. Playwrightやスクリーンショットによる視覚的な確認
3. 具体的なテストシナリオの実行
4. 変更内容の明確な説明

ユーザーが何かを修正済みと判断する最終権限を持ちます。例外はありません。