skill-architecture

スキルアーキテクチャ

セキュリティと段階的開示アーキテクチャを重視し、Anthropic の公式基準に沿って効果的な Claude Code スキルを作成するための包括的なガイドです。

自己進化するスキル：このスキルは使用を通じて改善されます。手順に誤りがある、パラメーターがずれている、あるいは回避策が必要だった場合は、先延ばしにせず、すぐにこのファイルを修正してください。実際に再現可能な問題がある場合のみ更新します。

対象範囲：Claude Code Agent Skills（~/.claude/skills/）であり、Claude.ai API のスキルではありません。

自己進化プロトコル

このスキルと、このスキルが作成するすべてのスキルは、使用を通じて積極的に進化する必要があります。このセクションを最初に置いているのは、ほかのすべてのセクションを規定するためです。

実行中は、手順の使いにくさ、考慮されていないエッジケース、より良いパターンの発見、繰り返し発生する手動の手順、ドキュメントと実態のずれに注意してください。

変更を書く前に、次の3つの判定基準をすべて満たしていることを確認してください。

判定基準	質問	不合格の場合 →
VALUE	推測ではなく、実際に観察された問題を解決しますか？	スキップ
REDUNDANCY	すでに記載されている内容、またはコードから明らかな内容ではありませんか？	スキップ
FRESHNESS	来月も有効な内容ですか？それとも一時的なものですか？	スキップ

ほとんどの実行では、進化は発生しないはずです。安定状態への収束は成功であり、停滞ではありません。

すべての判定基準を満たした場合：現在の作業を一時停止 → SKILL.md または参照ファイルを修正 → 発生のきっかけと根拠を添えて evolution-log.md に記録 → 作業を再開します。先延ばしにしてはいけません。次回の実行では、残された状態が引き継がれます。

判定基準を決して満たさないもの：大規模な構造変更（先にユーザーと相談する）、実証的な根拠のない推測による改善、見た目の好み。

---

このスキルを使う場面

次のような場合に、このスキルを使います。

• Claude Code スキルをゼロから新規作成する
• スキルの YAML フロントマターと構造要件を学ぶ
• スキルファイルの形式と移植性を検証する
• スキルの段階的開示パターンを理解する

---

タスクテンプレート

スキルの作業を始める前に、適切なテンプレートを選択してください。テンプレートには一般的なワークフローが組み込まれており、見落としによる気づきにくい失敗を防ぎます。

すべてのテンプレート（A～F）と品質チェックリストについては、タスクテンプレートを参照してください。

テンプレート	目的
A	スキルを新規作成する
B	既存のスキルを更新する
C	スキルにリソースを追加する
D	自己進化するスキルに変換する
E	スキルが起動しない問題をトラブルシューティングする
F	ライフサイクル一式を作成する

---

変更後のチェックリスト（自己メンテナンス）

このスキル（skill-architecture）を変更した後は、次の項目を確認します。

1. テンプレートと6 Steps チュートリアルの整合性が保たれている
2. スキル品質チェックリストが最新のベストプラクティスを反映している
3. references/ に記載されているすべてのファイルが存在する
4. 変更を evolution-log.md に追記した
5. トリガーを変更した場合、ユーザーの CLAUDE.md を更新した

---

---

スキルについて

スキルは、専門知識、ワークフロー、ツールを通じて Claude の能力を拡張する、モジュール式で自己完結型のパッケージです。特定の分野に関する「オンボーディングガイド」と考えるとよいでしょう。Claude を汎用的なものから、どのモデルも単独では持ち得ない手続き的知識を備えた専門エージェントへと変えます。

スキルが提供するもの

1. 専門的なワークフロー - 特定の分野における複数手順のプロセス
2. ツール連携 - 特定のファイル形式や API を扱うための手順
3. 分野の専門知識 - 企業固有の知識、スキーマ、ビジネスロジック
4. 同梱リソース - 複雑なタスクや繰り返し発生するタスクのためのスクリプト、参照資料、アセット

スキルの検出と優先順位

スキルは複数の場所から検出されます。同名のスキルがある場合は、優先順位の高いものが使われます。

1. エンタープライズ（管理設定）-- 最優先
2. 個人用（~/.claude/skills/）
3. プロジェクト（リポジトリ内の .claude/skills/）
4. プラグイン（名前空間付き：plugin:skill-name）
5. ネスト（サブディレクトリ内のモノレポの .claude/skills/ -- 自動検出）
6. --add-dir（CLI フラグ、変更をリアルタイムで検出）-- 最低

管理コマンド：

• claude plugin enable <name> / claude plugin disable <name> -- プラグインの有効化／無効化
• claude skill list -- 検出されたすべてのスキルとそのソースの場所を表示

モノレポのサポート：Claude Code は、モノレポ内のネストされたプロジェクトルートにある .claude/skills/ ディレクトリを自動的に検出します。設定は不要です。

---

cc-skills プラグインのアーキテクチャ

このセクションは、cc-skills マーケットプレイスのプラグイン構造にのみ適用されます。汎用のスタンドアロン型スキルには影響しません。

標準構成

plugins/<plugin>/
└── skills/
    └── <skill-name>/
        └── SKILL.md   <- single canonical file (context AND user-invocable)

skills/<name>/SKILL.md が唯一の信頼できる情報源です。別個の commands/ レイヤーは廃止されました。各スキルについて同じファイルを2つ管理する必要があり、Skill() の呼び出しで「Unknown skill」が返される原因にもなっていたためです。詳しくは移行に関するイシューをご覧ください。

スキルがスラッシュコマンドになる仕組み

どちらのインストール方法もサポートされています。

方法	仕組み	備考
自動（主要）	moon run repo:release-full -> sync-commands-to-settings.sh が skills/*/SKILL.md を読み込み -> ~/.claude/commands/<plugin>:<name>.md に書き込み	リリース後に完全自動で実行されます。Anthropic のキャッシュの不具合 #17361、#14061 を回避します
公式 CLI	claude plugin install itp@cc-skills -> プラグインのキャッシュ内にある skills/ から読み込み	アップデート後にキャッシュが更新されない場合があります。新しいリリース後に claude plugin update を実行してください

フック

sync-hooks-to-settings.sh が hooks/hooks.json を直接読み込み、~/.claude/settings.json にマージします。パスの再展開に関する不具合 #18517 を回避します。

cc-skills で新しいスキルを作成する

plugins/<plugin>/skills/<name>/SKILL.md に SKILL.md を配置します。commands/ へのコピーは不要です。バリデーター（bun scripts/validate-plugins.mjs）がフロントマターの完全性を確認します。

---

スキル作成の手順

詳しい6ステップの手順については作成チュートリアルを、例を含む包括的なガイドについては作成ワークフローをご覧ください。

概要：要件の収集 -> リソースの計画 -> 初期化 -> SKILL.md の編集 -> 検証 -> 登録と反復。

---

テストと反復

優れたスキルは、初稿を完璧に仕上げることではなく、テストとフィードバックを通じて生まれます。スキルを作成または更新した後は、現実的なプロンプトに対して実行し、正しく動作することを確認してください。

テスト用プロンプトを作成する

実際のユーザーが使いそうな、現実的なテスト用プロンプトを2～3個考えます。抽象的な依頼ではなく、スキルの動作を試せるだけの詳細が含まれた、具体的なタスクにしてください。実行する前にユーザーに提示し、確認を得てください。

実行して評価する

テスト用プロンプトごとにスキルを実行し、出力を確認します。

• スキルは起動しましたか？ 起動しなかった場合は、説明により強いトリガー表現が必要かもしれません。
• ワークフローに従いましたか？ 指示が守られたか、無視されたかを確認します。
• 出力は役に立ちましたか？ 熟練した人が出すと期待される内容と比較します。

サブエージェントが利用できる場合は、スキルを使う場合と使わない場合を並行して実行し、スキルが実際にもたらす価値を測定します。利用できない場合は、自分でテストケースを実行し、妥当性を確認します。

フィードバックに基づいて反復する

評価後、スキルを改善して再テストします。ユーザーが満足するか、フィードバックが一貫して肯定的になるまで反復を続けます。各反復では、次の原則を重視してください。

1. 個別のフィードバックから一般化する。 スキルは多様なプロンプトに使われます。細かく限定的な修正でテストケースに過剰適合しないようにしてください。同じパターンの失敗が続く場合は、制約を追加するのではなく、別のアプローチやたとえを試してください。

2. スキルを簡潔に保つ。 すべてのセクションに、それだけの価値が必要です。実行ログを読み、スキルが生産性のない手順にモデルを費やさせていないか確認してください。そうした指示を削除して、結果を確かめます。

3. 何をするかだけでなく、なぜそうするのかを説明する。 LLM は、厳格なルールを命じられるより、その理由を理解するほうが適切に応答します。すべて大文字の MUST／NEVER／ALWAYS を書きたくなったら、表現を見直す合図です。モデルがルールを恣意的な制約として扱うのではなく、その原則を内面化できるよう、理由を説明してください。モデルの能力を信頼し、命令するだけでなく、理解を促してください。

4. テストケース間で繰り返される作業を探す。 すべてのテスト実行で同じヘルパースクリプトが作成されたり、同じ複数ステップの手順が繰り返されたりする場合は、そのスクリプトを scripts/ にまとめます。そうすれば、今後の実行で同じものを作り直さずに済みます。

5. よくあるパターンをスクリプトにまとめる。 テスト実行で、モデルが毎回よく似た定型コードを書くことが分かった場合は、それをバンドル済みのスクリプトに切り出します。これにより、トークンを節約し、信頼性を高められます。

---

スキル作成の原則

Anthropic の公式ガイダンスに沿った次の原則は、すべてのスキルの内容に適用されます。

• 命令形を使う： 「スクリプトを実行する」「出力を確認する」のように書きます。受動的な表現や遠回しな表現は避けてください。
• 厳格なルールより理由を説明する： MUST／NEVER／ALWAYS をすべて大文字で書きたくなったら、表現を見直してください。モデルが原則を内面化できるよう、理由を説明します。恣意的な命令として扱わせないようにしてください。モデルの能力を信頼し、ただ命じるのではなく、理解を促してください。
• 起動を促す説明にする： Claude はスキルを起動しない傾向があります。説明では、対象範囲を積極的に示してください。「ユーザーが明示的に依頼していなくても、X、Y、Z に言及した場合は必ずこのスキルを使ってください」のようにします。否定的なトリガーも含めます。「A または B には使わないでください」のように記述します。
• 自然な言葉で説明する： 説明はキーワードの羅列ではなく、人が読んで分かる文章にします。「このスキルは、次のような場合に必ず使ってください」のような表現が、「トリガー - キーワード1、キーワード2」より適切です。
• 説明に実行手順を含めない： 説明では Claude がいつスキルを起動するかを伝えます。スキルの本文では、どのように実行するかを伝えます。両者を混在させないでください。

例を含む詳細なガイダンスについては、執筆ガイドを参照してください。

---

スキルの構成

skill-name/
├── SKILL.md                      # Required: YAML frontmatter + instructions
├── scripts/                      # Optional: Executable code (Python/Bash)
├── references/                   # Optional: Documentation loaded as needed
│   └── evolution-log.md          # Required for self-evolving: Change history
└── assets/                       # Optional: Files used in output

YAML フロントマター（必須）

フィールドの完全なリファレンス、呼び出し制御の表、権限に関するルール、説明文のガイドライン、YAML の注意点については、YAML フロントマターのリファレンスを参照してください。

最小限の例：

---
name: my-skill
description: Does X when user mentions Y. Use for Z workflows.
---

主なルール： name は小文字とハイフンを使用し、description はトリガーキーワードを含む1024文字以内の1行にします。説明文にコロンを入れないでください。

段階的な開示（3 レベル）

スキルでは、コンテキストを効率的に管理するために段階的な読み込みを使用します。

1. メタデータ（名前 + 説明）- 常にコンテキスト内にあります（約 100 語）
2. SKILL.md の本文 - スキルがトリガーされたときに読み込まれます（5,000 語未満）
3. バンドルされたリソース - Claude が必要に応じて読み込みます（無制限*）

*スクリプトは、コンテキストに読み込まずに実行できます。

スキルの説明の予算

スキルは、説明の関連性に基づいてコンテキストウィンドウに読み込まれます。予算を超えると、大きなスキルは除外される場合があります。

• 予算：コンテキストウィンドウの約 2%（フォールバック時は 16K 文字）
• 確認：/context を実行して、読み込まれたスキルと除外されたスキルを確認します
• 上書き：SLASH_COMMAND_TOOL_CHAR_BUDGET 環境変数を設定して、予算を増やします
• 対処方法：SKILL.md の本文を簡潔に保ち、詳細は references/ に移動します

---

バンドルされたリソース

スキルには scripts/、references/、assets/ ディレクトリを含めることができます。それぞれをいつ使用するかについての詳しいガイダンスは、段階的な開示を参照してください。

---

CLI 固有の機能

CLI スキルでは allowed-tools を使用して、使用ごとの承認なしでツールへのアクセスを許可できます。詳細はセキュリティ対策を参照してください。

文字列の置換

スキルの本文では、以下の置換を使用できます（読み込み時に解決されます）。

変数	解決結果	例
$ARGUMENTS	/name arg1 arg2 から渡される引数文字列全体	Process: $ARGUMENTS
$ARGUMENTS[N]	N 番目の引数（インデックスは 0 から始まります）	File: $ARGUMENTS[0]
$N	$ARGUMENTS[N] の省略形	$0 = 最初の引数
${CLAUDE_SESSION_ID}	現在のセッション UUID	ログの相関付け

動的コンテキストの挿入

スキルの本文で ! + `command` のパターン（感嘆符の後にバッククォートで囲んだコマンドを続ける）を使用すると、読み込み時にコマンドの出力を挿入できます。

Current branch: <exclamation>`git branch --show-current`
Last commit: <exclamation>`git log -1 --oneline`

（実際に使用する際は、<exclamation> を ! に置き換えてください。）

コマンドはスキルの読み込み時に実行され、出力がパターンの位置にインラインで置き換えられます。

拡張思考

スキルの実行で拡張思考モードを有効にするには、スキルの本文にキーワード ultrathink を含めます。

---

構造パターン

以下の使用方法について詳しいガイダンスは、構造パターンを参照してください。

1. ワークフローパターン - 順次実行する複数ステップの手順
2. タスクパターン - 具体的で範囲が明確なタスク
3. リファレンスパターン - ナレッジリポジトリ
4. 機能パターン - ツールとの統合
5. スイートパターン - 複数のスキルのライフサイクル管理（初期設定、運用、診断、構成、アップグレード、削除）

---

ユーザー規約との統合

このスキルは、一般的なユーザー規約に従います。

• 絶対パス：常にフルパスを使用します（ターミナルでの Cmd+クリックに対応）
• Unix のみ：macOS、Linux（Windows はサポート対象外）
• Python：PEP 723 のインライン依存関係を使用する uv run script.py
• 計画：適切な場合は OpenAPI 3.1.1 の仕様を使用します

---

マーケットプレイスのスクリプト

マーケットプレイスのスクリプトの使用方法については、スクリプトのリファレンスを参照してください。

---

リファレンスドキュメント

詳しくは、以下を参照してください。

• タスクテンプレート - テンプレート A〜F と品質チェックリスト
• 作成チュートリアル - 6 ステップの作成プロセスの解説
• YAML Frontmatter - フィールドのリファレンス、呼び出し制御、説明のガイドライン
• 構造パターン - 5 つのスキルアーキテクチャパターン（Suite Pattern を含む）
• ワークフローパターン - ワークフロースキルの実装パターン
• 段階的な開示 - コンテキスト管理パターン
• 作成ワークフロー - 例を含むステップごとのプロセス
• スクリプトリファレンス - Marketplace スクリプトの使用方法
• セキュリティ対策 - 脅威と防御（CVE の参照）
• フェーズ実行 - Preflight／Execute／Verify／Reflect／Rectify のパターンとバリエーション
• 実行後の振り返り - ステップ型スキル向けの必須自己修正パターン
• 理論：自己進化するスキル - Gemini DR #70（6 スレッド）の研究内容の統合
• 呼び出し制御 - スキルの呼び出しモード、権限ルール、レガシーコマンドの移行
• 対話パターン - AskUserQuestion の統合パターン
• トークン効率 - コンテキストの最適化
• 高度なトピック - CLI と API、合成、バグ
• パスパターン - 安全／危険なパス参照（既知のバグを記録）
• Bash の互換性 - シェルの移植性パターン
• 検証リファレンス - 品質チェックリスト
• ライティングガイド - トーン、推論に基づく指示、説明の最適化
• スクリプト設計 - エージェントによる利用を想定したスクリプトの設計
• トラブルシューティング - よくある問題と解決策
• SYNC-TRACKING - Marketplace のバージョン追跡
• 進化ログ - このスキルの変更履歴

---

実行後の振り返り（必須）

このセクションは最後に配置されています。スキルが終了する直前に処理される最後の項目となり、直近性効果を最大化します。

すべてのスキルには、ワークフロースキル、タスクスキル、機能スキルを問わず、実行後の振り返りセクションを必ず含めてください。これは推奨事項ではなく、構造上の要件です。このセクションがなければ、エラーや乖離がセッションをまたいで気付かれないまま繰り返されます。タスクパターンのスキルも例外ではありません。スクリプトのインターフェースが変わったり、パラメーターが追加されたり、エラーメッセージがドキュメントと食い違ったりすることがあります。

このスキルの完了後、終了する前に振り返る

0. 自分の場所を確認します。 — 編集する前に、この SKILL.md の正規パスを特定します（このスキルの名前を Glob で検索）。修正対象はこのファイルとその兄弟にあたる references/ のみです。他のドキュメントは対象にしません。
1. 何が失敗しましたか？ — 原因となった指示を修正します。再発する可能性がある場合は、アンチパターンとして追加します。
2. 予想以上にうまくいったのは何ですか？ — 推奨される実践方法にします。その理由も記録します。
3. 何が現状と乖離していますか？ — 実態と一致しなくなったスクリプト、リファレンス、外部依存関係があれば、ここで修正します。
4. 受け入れゲートを通過します。 — Self-Evolution Protocol（このファイルの冒頭）を適用します。変更を書き込む前に、VALUE + REDUNDANCY + FRESHNESS のすべてを満たす必要があります。
5. 記録します。 — 変更のたびに、きっかけ、修正内容、根拠を含む進化ログのエントリーを追加します。

先延ばしにしないでください。次回の呼び出しでは、ここに残した内容が引き継がれます。

テンプレート：ワークフロー型／ステップ型スキル

複数のフェーズ、evolution-log、references/ を含むスキル向け：

## Post-Execution Reflection

After this skill completes, reflect before closing the task:

0. **Locate yourself.** — Find this SKILL.md's canonical path before editing.
1. **What failed?** — Fix the instruction that caused it.
2. **What worked better than expected?** — Promote to recommended practice.
3. **What drifted?** — Fix any script, reference, or dependency that no longer matches reality.
4. **Log it.** — Evolution-log entry with trigger, fix, and evidence.

Do NOT defer. The next invocation inherits whatever you leave behind.

テンプレート：タスクパターンのスキル

CLI コマンドまたはスクリプトをラップする、単一アクションのスキルの場合：

## Post-Execution Reflection

After this skill completes, check before closing:

1. **Did the command succeed?** — If not, fix the instruction or error table that caused the failure.
2. **Did parameters or output change?** — If the script's interface drifted, update Usage examples and Parameters table to match.
3. **Was a workaround needed?** — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.

パターンの全体像、検証要件、例については、実行後の振り返りに関するリファレンスを参照してください。