スキルアーキテクト：決定的なメタスキル

エキスパートレベルのエージェントスキルを作成する統一的な権限です。単に「存在する」スキルと「正確に起動し、効率的に教え、ユーザーをすぐに生産的にさせる」スキルを分ける知識をエンコードします。

哲学

優れたスキルは段階的開示マシンです。 表面的な指示ではなく、実際のドメイン専門知識（シビレット）をエンコードします。3層アーキテクチャに従います：発見のための軽量なメタデータ、コアプロセスのためのリーンなSKILL.md、オンデマンドでのみロードされる深掘りのリファレンスファイルです。

---

このスキルを使う時

• ゼロから、または既存の専門知識からスキルを新規作成する場合
• スキルの品質、起動、段階的開示を監査・レビューする場合
• 起動率を向上させ、誤検知を減らす場合
• ドメイン専門知識（シビレット、アンチパターン、時間的知識）をエンコードする場合
• サブエージェントが効果的に消費するスキルを設計する場合
• 自己完結したツール（スクリプト、MCP、サブエージェント）を構築する場合
• スキルが起動しない、または不正に起動する理由をデバッグする場合

対象外：一般的なClaude Code機能（スラッシュコマンド、MCPサーバー実装）、スキル以外のコーディングアドバイスまたはコードレビュー、ランタイムエラーのデバッグ（ドメイン固有のスキルを使用）、実際にエンコードすべきドメイン専門知識のないテンプレート生成。

---

クイックウィン（即座の改善）

既存のスキルについては、優先順にこれらを適用してください：

1. 説明を厳密にする -- [何を][いつ使う]. NOT for [除外] フォーマットに従う
2. 行数をチェックする -- SKILL.mdは500行未満である必要があり、深さを /references に移動する
3. NOT句を追加する -- 明示的な除外で誤検知を防ぐ
4. 1～2個のアンチパターンを追加する -- シビレットテンプレートを使用（初心者/エキスパート/タイムライン）
5. 不要なファイルを削除する -- scripts/ と references/ の未参照ファイルを削除（ファントムなし）
6. 起動をテストする -- トリガーすべき5つのクエリと、すべきでない5つのクエリを書く

---

段階的開示アーキテクチャ

スキルは3層ロードを使用します。ランタイムは起動時にメタデータをスキャンし、起動時にSKILL.mdをロードし、エージェントが必要と判断した場合のみリファレンスファイルをプルします。

レイヤー	コンテンツ	サイズ	ロード
1. メタデータ	frontmatterの name + description	~100トークン	常にコンテキストに入る（カタログスキャン）
2. SKILL.md	コアプロセス、決定木、簡潔なアンチパターン	<5kトークン	スキル起動時
3. リファレンス	深掘り、例、テンプレート、仕様	無制限	オンデマンド、ファイル単位、関連性がある場合のみ

重要なルール：

• SKILL.mdは500行未満に保つ。深さを /references に移動する。
• リファレンスファイルは自動ロードされません。SKILL.mdのみが起動時にコンテキストに入ります。
• SKILL.mdで、各リファレンスファイルを参照する際期を説明する1行の説明を含めてください。
• 「始める前にすべてのリファレンスファイルを読んでください」と指示しないこと。代わりに「現在のステップに関連するファイルのみを読んでください」と指示してください。

---

Frontmatterルール

必須フィールド

キー	目的	制約
name	小文字ハイフン区切り識別子	最大64文字、a-z/0-9/ハイフンのみ、「anthropic」または「claude」なし、XMLタグなし
description	起動トリガー：[何を] [いつ使う]. NOT for [除外]	最大1024文字、XMLタグなし。説明フォーマルを参照

オプションフィールド

キー	目的	例
allowed-tools	コンマ区切りツール名（最小権限）	Read,Write,Grep
argument-hint	予想される引数のオートコンプリートで表示されるヒント	"[path] [format]"
license	ライセンス識別子	MIT
disable-model-invocation	true の場合、ユーザーが /skill-name で起動するのみ	true
user-invocable	スキルがUIメニューに表示されるかどうかを制御	true
context	実行コンテキスト；fork はスキルを独立したサブエージェントで実行	fork
agent	context: fork の場合のサブエージェントタイプ	code-reviewer
model	スキルがアクティブな場合のモデルオーバーライド	sonnet
hooks	このスキルのライフサイクルにスコープされたフック	フックリファレンスを参照
metadata	ツール/ダッシュボード用の任意のキー・バリューマップ	author: your-org

カスタムキー（使用安全）

category、tags、version などのカスタムキーは Claude Codeによって無視されます が、独自のツーリング（ギャラリーウェブサイト、ドキュメント生成器、ダッシュボード）のために含める安全です。混乱を避けるために、これらを metadata: ブロック内に配置して、実行時キーと区別してください。

無効なキー（有効なキーと紛らわしい）

# これらは有効なキーのように見えますが、そうではありません -- 正しい代替を使用してください
tools: Read,Write           # 代わりに 'allowed-tools' を使用
integrates_with: [...]      # 代わりに SKILL.md 本文を使用
outputs: [...]              # 代わりに SKILL.md Output Format セクションを使用
dependencies: [...]         # SKILL.md 本文を使用（実際のfrontmatterキーではありません）
bundled-resources: [...]    # SKILL.md 本文を使用（実際のfrontmatterキーではありません）

ロードを防ぐ一般的な間違い：tools: の代わりに allowed-tools: を使用（サイレント無視）、allowed-toolsでYAMLリスト構文 [Read, Write] を使用（コンマ区切り文字列を使用）、スペース/大文字を含む名前（小文字ハイフン区切りを使用）、ディレクトリ名と一致しない名前（起動ミスマッチを引き起こす）。これらすべてをキャッチするために python scripts/validate_skill.py <path> を実行してください。

プラットフォーム制約（名前：64文字、説明：1024文字、アップロード：8MB、リクエスト当たり8スキル最大、XMLタグなし）：完全な詳細については references/claude-extension-taxonomy.md を参照してください。スキルはClaude.ai、Claude API、Claude Code間で同期されません -- Gitを単一の真実のソースとして保持してください。

---

説明フォーマル

パターン：[何をするのか] [いつ使うか -- やや強引に]. NOT for [除外].

説明はアクティベーションの最も重要な行です。Claudeのランタイムは説明をスキャンして、どのスキルをロードするかを決定します。Claudeは説明を セマンティック に評価します。キーワードマッチングではなく、ユーザーの意図をカバーしているかどうかについて推論します。また、Claudeは 起動不足 する傾向があります -- これと戦うために説明をやや強引にしてください。

問題	悪い例	良い例
曖昧すぎる	「画像を支援する」	「画像テキストマッチングとゼロショット分類のためのCLIPセマンティック検索。数え上げ、空間推論、または生成には対応していません。」
除外なし	「コード変更をレビューする」	「TypeScript/React のdiffとPRを正確性についてレビューします。新しい機能の作成には対応していません。」
キャッチオール	「製品管理を支援する」	「要件定義書（PRD）を作成および改善します。戦略資料には対応していません。」

より多くの例を含む完全ガイド：references/description-guide.md を参照

---

SKILL.mdテンプレート

---
name: your-skill-name
description: [何をするのか] [いつ使うか -- やや強引に]. NOT for [除外].
allowed-tools: Read,Write
---

# スキル名
[1文の目的]

## 使う時
用途：[A、B、C（特定のトリガーキーワード付き）]
対象外：[D、E、F -- 明示的な境界]

## コアプロセス
[決定/フロー用のMermaidダイアグラム。カタログについてはvisual-artifacts.mdを参照]

## アンチパターン
### [パターン名]
**初心者**：[間違った仮定]
**エキスパート**：[なぜそれが間違っているのか + 正しいアプローチ]
**タイムライン**：[これが変わった場合の時期]

## リファレンス
- `references/guide.md` -- [特定の状況]で参照する
- `references/examples.md` -- [Xの実例]で参照する

---

6ステップのスキル作成プロセス

flowchart LR
  S1[1. 例を集める] --> S2[2. コンテンツを計画]
  S2 --> S3[3. 初期化]
  S3 --> S4[4. スキルを書く]
  S4 --> S5[5. 検証]
  S5 --> S6{エラー?}
  S6 -->|はい| S4
  S6 -->|いいえ| S7[6. リリース＆繰り返す]

ステップ1：具体的な例を集める

このスキルをトリガーするべき実際のクエリ3～5個、およびそうでないもの3～5個を収集してください。

ステップ2：再利用可能なコンテンツを計画する

再作業を防ぐスクリプト、リファレンス、資産を特定します。また、シビレットを特定します：ドメインアルゴリズム、時間的知識、フレームワーク進化、一般的な落とし穴。

ステップ3：初期化

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

ステップ4：スキルを書く

順序：最初にスクリプト（動作するコード） -> 次にリファレンス（ドメイン知識） -> 最後にSKILL.md（コアプロセス、リファレンスインデックス）。

命令形で書いてください：「Xを完了するには、Yを実行してください」ではなく「Xをすべきです」。

ステップ5：検証

python scripts/validate_skill.py <path>
python scripts/check_self_contained.py <path>

ERRORSを修正し、WARNINGSを修正し、SUGGESTIONSを修正してください。

ステップ6：繰り返す

実際の使用後：苦労を注意し、SKILL.mdとリソースを改善し、CHANGELOG.mdを更新してください。

---

サブエージェント消費のためのスキル設計

3つのスキルロード層

1. プリロード（2～5個のコアスキル）：サブエージェントのシステムコンテキストに注入されます。
2. 動的に選択：サブエージェントはカタログ（名前+1行説明）を受け取り、マッチする1～3個のスキルを選びます。
3. 実行時：サブエージェントは各スキルの「使う時」セクションを読み、番号付きステップに従い、出力契約を尊重し、QAチェックを実行します。

サブエージェントプロンプト構造

4つのセクション：アイデンティティ（限定的な役割）、スキル使用ルール（標準的な操作手順としてのスキル）、タスクループ（再開、スキル選択、計画、実行、検証、返却）、制約（品質基準、安全性、タイブレーク）。

完全なテンプレートとオーケストレーションパターン：references/subagent-design.md を参照

---

ビジュアルアーティファクト：Mermaidダイアグラム

人間にとって、ダイアグラムはビジュアルフローチャート、状態マシン、タイムラインとしてレンダリングされます。エージェント向け、Mermaidはテキストベースのグラフ言語です -- A -->|Yes| B は明示的で曖昧でないエッジです。両方の視聴者が恩恵を受けます。

ルール：スキルがプロセス、決定木、アーキテクチャ、状態マシン、またはデータ関係を説明する場合、Mermaidダイアグラムを含めてください。

スキルコンテンツ	ダイアグラムタイプ	構文
決定木/トラブルシューティング	フローチャート	flowchart TD
API/エージェント通信プロトコル	シーケンス	sequenceDiagram
ライフサイクル/ステータス遷移	ステート	stateDiagram-v2
時間的知識/進化	タイムライン	timeline
データモデル/スキーマ	ER	erDiagram
ドメイン分類/概念マップ	マインドマップ	mindmap
優先度マトリックス（2軸）	クワドラント	quadrantChart
インフラ/クラウドトポロジー	アーキテクチャ	architecture-beta

完全カタログ（すべて23タイプ）構文、例、YAML設定付き：references/visual-artifacts.md を参照

---

シビレットのエンコード

初心者とエキスパートを分ける専門知識。LLMが古い訓練データや模倣パターンのために間違う事柄。

シビレットテンプレート

### アンチパターン：[名前]
**初心者**：「[間違った仮定]」
**エキスパート**：[なぜそれが間違っているのか、証拠付き]
**タイムライン**：[日付]：[古い方法] -> [日付]：[新しい方法]
**LLM間違い**：[LLMがなぜ古いパターンを提案するのか]
**検出**：[これをコード/設定でどのように発見するか]

事例研究を含む完全なカタログ：references/antipatterns.md を参照

---

自己完結したツールと拡張タクソノミー

スキルは7つのClaude拡張タイプの1つです。ほとんどのスキルはスクリプトを含むべきです。MCPは認証/状態境界のみです。プラグインはチーム/コミュニティ全体でスキルを共有するためです。

ニーズ	拡張タイプ	重要な要件
ドメイン専門知識/プロセス	スキル（SKILL.md）	決定木、アンチパターン、出力契約
パッケージング＆配布	プラグイン（plugin.json）	スキル+フック+MCP+エージェントをバンドル
外部API+認証	MCPサーバー	動作するサーバー+セットアップREADME
繰り返し可能なローカル操作	スクリプト	実際に実行（テンプレートではない）、最小依存
マルチステップオーケストレーション	サブエージェント	4セクションプロンプト、スキル、ワークフロー
ユーザーがトリガーしたアクション	スラッシュコマンド	user-invocable: true を持つスキル
ライフサイクル自動化	フック	17以上のイベント：PreToolUse、PostToolUse、Stopなど
プログラムアクセス	エージェントSDK	npm/pipパッケージ、CI/CDパイプライン

例と一般的な間違いを含む完全なタクソノミー：references/claude-extension-taxonomy.md を参照 詳細なツールパターン：references/self-contained-tools.md を参照 プラグイン作成と配布：references/plugin-architecture.md を参照

---

ツール権限（最小権限）

アクセスレベル	allowed-tools
読み取り専用	Read,Grep,Glob
ファイル修飾子	Read,Write,Edit
ビルド統合	Read,Write,Bash(npm:*,git:*)
信頼されていないものには決して	無制限 Bash

---

アンチパターン要約

#	アンチパターン	修正
1	ドキュメンテーション ダンプ	SKILL.mdの決定木、/references の深さ
2	NOT句がない	常に説明に「NOT for X、Y、Z」を含める
3	ファントムツール	存在し機能するファイルのみを参照
4	テンプレートスープ	動作するコードを発送するか、何もしない
5	過度に許可的なツール	最小権限：特定のツールリスト、スコープ付きBash
6	陳腐な時間的知識	すべてのアドバイスに日付を付け、四半期ごとに更新
7	キャッチオールスキル	ドメイン別ではなく、専門知識タイプ別に分割
8	曖昧な説明	[何を] [いつ使う]. NOT for [除外] を使用
9	イーガーロード	決して「最初にすべてのファイルを読む」ではなく；遅延ロード参照
10	プロズのみのプロセス	決定、ワークフロー、アーキテクチャにMermaidダイアグラムを使用

完全なケーススタディ：references/antipatterns.md を参照

---

検証チェックリスト

[ ] SKILL.mdが存在し、500行未満である
[ ] Frontmatterに名前+説明（最小限必須）がある
[ ] 説明は [何を][いつ使う] NOT [除外] フォーマルに従う
[ ] 説明は具体的でコンテキストが豊富（セマンティックアクティベーション、キーワードリストではなく）
[ ] 名前と説明が一致している（矛盾していない）
[ ] シビレットテンプレート付きの少なくとも1つのアンチパターンがある
[ ] 参照されているすべてのファイルが実際に存在する（ファントムなし）
[ ] スクリプトが機能する（テンプレートではない）、明確なCLIを持つ、エラーを処理する
[ ] 各リファレンスファイルはSKILL.mdで参照される時期の1行説明を持つ
[ ] プロセス/決定/ライフサイクルはプロズではなくMermaidダイアグラムを使用
[ ] CHANGELOG.mdがバージョン履歴を追跡する
[ ] サブエージェントが消費する場合：出力契約が定義されている
[ ] スキルは独自の検証ツール（メタ一貫性）に合格する

自動チェックを実行：python scripts/validate_skill.py <path> および python scripts/validate_mermaid.py <path>

---

成功メトリクス

メトリクス	目標
正しい起動	>90%
誤検知率	<5%
トークン使用量	<5kトークン
生産性までの時間	<5分

---

リファレンスファイル

深掘りのためにこれらを参照してください -- デフォルトではロードされません：

ファイル	参照する時
references/knowledge-engineering.md	スキルへの専門知識抽出のKE方法
references/description-guide.md	スキル説明を書き換える、または書き換える
references/antipatterns.md	シビレット、ケーススタディ、または時間的パターンを探す
references/self-contained-tools.md	スクリプト、MCPサーバー、またはサブエージェントをスキルに追加
references/subagent-design.md	サブエージェント消費またはオーケストレーション用のスキル設計
references/claude-extension-taxonomy.md	スキル対プラグイン対MCP対フック対エージェントSDK
references/plugin-architecture.md	プラグインの作成、パッケージング、配布
references/visual-artifacts.md	Mermaidダイアグラムの追加：すべて23タイプ、YAML設定
references/mcp-template.md	スキルのMCPサーバーを構築
references/subagent-template.md	サブエージェントプロンプトとマルチエージェントパイプラインを定義
references/scoring-rubric.md	定量的スキル評価（0～10スコアリング基準）
references/skill-composition.md	クロススキル依存関係とコンポジションパターン
references/skill-lifecycle.md	メンテナンス、バージョン管理、廃止ガイダンス
references/activation-debugging.md	スキルが起動しない、または誤検知する理由を診断
agents/cross-evaluator.md	クロス評価スキルのテンプレート