skill-architect

スキルアーキテクト：権威あるメタスキル

エキスパートレベルのエージェントスキルを作成するための統一された権威です。単に「存在するだけ」のスキルと、「的確に発動し、効率よく教え、すぐにユーザーの生産性を高める」スキルを分ける知識を体系化します。

哲学

優れたスキルは、段階的開示を実現する仕組みです。 表面的な指示ではなく、実際のドメイン専門知識（見分けるポイント）を体系化します。軽量なメタデータによる発見、コアプロセスをまとめた簡潔な SKILL.md、必要なときだけ読み込む詳細なリファレンスファイルという、3 層アーキテクチャに従います。

---

このスキルを使う場面

✅ 次の場合に使用します：

• 新しいスキルを一から作成する場合や、既存の専門知識をもとに作成する場合
• 品質、発動、段階的開示の観点からスキルを監査・レビューする場合
• 発動率を改善し、誤発動を減らす場合
• ドメイン専門知識（見分けるポイント、アンチパターン、時間的知識）を体系化する場合
• サブエージェントが効果的に利用できるスキルを設計する場合
• 自己完結型のツール（スクリプト、MCP、サブエージェント）を構築する場合
• スキルが発動しない、または誤って発動する理由をデバッグする場合

❌ 次の場合は使用しません：

• 一般的な Claude Code の機能（スラッシュコマンド、MCP サーバーの実装）
• スキル以外のコーディングに関するアドバイスやコードレビュー
• 実行時エラーのデバッグ（ドメイン固有のスキルを使用してください）
• 体系化すべき実際のドメイン専門知識がないテンプレートの生成

---

すぐにできる改善

既存のスキルには、次の優先順位で適用します：

1. 説明を引き締める → [What] [When] [Keywords]. NOT for [Exclusions] の形式に従う
2. 行数を確認する → SKILL.md は <500 行である必要があります。詳細は /references に移します
3. NOT 条項を追加する → 明示的な除外事項で誤発動を防ぐ
4. アンチパターンを 1～2 個追加する → 見分けるポイントのテンプレート（初心者／エキスパート／時間軸）を使用する
5. 使われていないファイルを削除する → 参照されていないスクリプトやリファレンスを削除する（幽霊ファイルを残さない）
6. 発動をテストする → 発動すべきクエリを 5 つ、発動すべきでないクエリを 5 つ作成する

---

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

スキルは 3 層の読み込み方式を使用します。実行時に起動時のメタデータをスキャンし、発動時に SKILL.md を読み込み、エージェントが必要と判断した場合に限り、リファレンスファイルを読み込みます。

層	内容	サイズ	読み込み
1. メタデータ	フロントマターの name + description	約 100 トークン	常にコンテキスト内（カタログのスキャン時）
2. SKILL.md	コアプロセス、判断ツリー、簡潔なアンチパターン	<5k トークン	スキルの発動時
3. リファレンス	詳細解説、例、テンプレート、仕様	無制限	必要に応じて、ファイル単位で、関連する場合のみ

重要なルール：

• SKILL.md は 500 行未満にします。詳細は /references に移します。
• リファレンスファイルは自動で読み込まれません。スキルの発動時にコンテキストに入るのは SKILL.md のみです。
• SKILL.md では、各リファレンスファイルについて、参照するタイミングを 1 行で説明します。ファイルを読み込まずに利用可能な情報をエージェントに伝えられます。
• 「開始前にすべてのリファレンスファイルを読んでください」と指示してはいけません。代わりに、「現在のステップに関連するファイルのみを読んでください」と指示します。
• リファレンスファイルが大きい場合、エージェントはまず見出しをざっと確認し、次に関連するセクションを詳しく読みます。

---

フロントマターのルール

必須フィールド

キー	目的	例
name	小文字とハイフンで構成する識別子	react-server-components
description	発動条件：[What] [When] [Keywords]. NOT for [Exclusions]	Description Formula を参照

オプションのフィールド

キー	目的	例
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 に無視されます が、独自のツール（ギャラリーサイト、ドキュメント生成ツール、ダッシュボード）で使う場合は安全に含められます。実行時の解析とは競合しません。

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

# ❌ These look like valid keys but aren't — use the correct alternatives
tools: Read,Write           # Use 'allowed-tools' instead
integrates_with: [...]      # Use SKILL.md body text instead
triggers: [...]             # Use 'description' keywords instead
outputs: [...]              # Use SKILL.md Output Format section instead
coordinates_with: [...]     # Use SKILL.md body text instead
python_dependencies: [...]  # Use SKILL.md body text instead

---

説明文の公式

パターン：[機能] [使用する場面] [トリガーとなるキーワード]。対象外：[除外事項]。

説明文は、スキルを有効化するうえで最も重要な行です。Claude のランタイムは説明文を調べて、どのスキルを読み込むか判断します。説明文が弱いと、まったく有効化されないか、誤検出が頻発します。

問題	悪い例	良い例
曖昧すぎる	「画像を支援します」	「画像とテキストのマッチング、およびゼロショット分類のための CLIP セマンティック検索。カウント、空間推論、生成には使用しません。」
除外事項がない	「コード変更をレビューします」	「TypeScript／React の差分と PR の正確性をレビューします。新機能の作成には使用しません。」
ミニマニュアル	「調査してから、概要を作成し、次に下書きを作成します……」	「1～3 ページの統合レポートを作成する、構造化された調査。簡単な事実確認には使用しません。」
何でも対応	「プロダクトマネジメントを支援します」	「プロダクト要件書（PRD）を作成し、推敲します。戦略デッキには使用しません。」
名前が一致しない	name: db-migration / desc: "マーケティングメールを作成します"	name: db-migration / desc: "ロールバック戦略を含むデータベーススキーマの移行を計画します。"

例を含む完全ガイド：references/description-guide.md を参照してください。

---

SKILL.md テンプレート

---
name: your-skill-name
description: [What] [When] [Keywords]. NOT for [Exclusions].
allowed-tools: Read,Write
---

# Skill Name
[One sentence purpose]

## When to Use
✅ Use for: [A, B, C with specific trigger keywords]
❌ NOT for: [D, E, F — explicit boundaries]

## Core Process
[Mermaid diagrams — 23 types available. See visual-artifacts.md for full catalog]

## Anti-Patterns
### [Pattern Name]
**Novice**: [Wrong assumption]
**Expert**: [Why it's wrong + correct approach]
**Timeline**: [When this changed, if temporal]

## References
- `references/guide.md` — Consult when [specific situation]
- `references/examples.md` — Consult for [worked examples of X]

---

スキル作成の 6 ステップ

flowchart LR
  S1[1. Gather Examples] --> S2[2. Plan Contents]
  S2 --> S3[3. Initialize]
  S3 --> S4[4. Write Skill]
  S4 --> S5[5. Validate]
  S5 --> S6{Errors?}
  S6 -->|Yes| S4
  S6 -->|No| S7[6. Ship & Iterate]

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

このスキルを起動するべき実際のクエリを 3～5 件と、起動するべきでないものを 3～5 件集めます。

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

各例について、スクリプト、リファレンス、アセットのうち、作業のやり直しを防ぐものを特定します。また、専門知識を示す要素も特定します。たとえば、ドメイン固有のアルゴリズム、時間に依存する知識、フレームワークの進化、よくある落とし穴などです。

ステップ 3：初期化する

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

既存のスキルの場合は、ステップ 4 に進みます。

ステップ 4：スキルを作成する

実装の順序：

1. まずスクリプト（scripts/）— テンプレートではなく、動作するコード
2. 次にリファレンス（references/）— ドメイン知識、スキーマ、ガイド
3. デモとアセット（demo/、assets/、prompts/、templates/）— ビジュアル／デザイン系スキルでは、レンダリング済み HTML デモ、出典を明記した参考画像、画像生成プロンプト、スターターテンプレートを用意します。references/visual-design-skills.md を参照してください。
4. 最後に SKILL.md — 中核となるプロセス、アンチパターン、リファレンスの索引

命令形で記述します。「X を達成するには、Y を実行する」とし、「X を実行するべきです」とは書きません。

SKILL.md では、次の質問に答えます。

1. 目的：このスキルは何のためのものですか？（1～2 文）
2. 有効化：何が起動のきっかけになりますか？何を対象外にしますか？
3. プロセス：Mermaid の図（23 種類）を使います。判断にはフローチャート、プロトコルにはシーケンス図、ライフサイクルには状態遷移図などを使います。
4. アンチパターン：初心者が間違えやすいのはどのような点ですか？
5. 視覚的な成果物：ワークフロー、アーキテクチャ、タイムラインを Mermaid の図として描画します（references/visual-artifacts.md を参照してください）。
6. リファレンス：どのファイルがあり、どのような場合に参照しますか？

ステップ 5：検証

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

エラー → 警告 → 提案の順に修正します。

ステップ 6：反復

実際に使用した後、問題点に気づいたら、SKILL.md とリソースを改善し、CHANGELOG.md を更新します。

---

サブエージェントが利用するスキルの設計

スキルがサブエージェントによって読み込まれる場合（ユーザーが直接呼び出す場合だけではない場合）は、次のパターンを適用します。

スキルを読み込む 3 つのレイヤー

1. 事前読み込み（中核となるスキル 2～5 個）：サブエージェントのシステムコンテキストに注入されます。標準的な運用手順として常に参照できます。
2. 動的選択：サブエージェントはカタログ（名前＋1 行の説明）を受け取り、開始前に該当するスキルを 1～3 個選びます。オーケストレーターが事前に候補を絞り込むこともできます。
3. 実行時：サブエージェントは各スキルの「使用するタイミング」セクションを読み、番号付きの手順を順番に実行し、出力仕様を遵守して、QA チェックを実施します。

サブエージェントによるスキルの使い方

各スキルを小さなプロトコルとして扱うよう、サブエージェントに教えます。

• 「使用するタイミング／使用しないタイミング」セクションを確認し、適用できるか判断する
• 番号付きの手順を順番に実行する（タスクの制約によってやむを得ない場合に限り変更する）
• スキルの出力仕様（テンプレート、JSON の形式、必須セクション）を遵守する
• QA／検証の手順は最後に実行する
• 「refactor-plan-skill のステップ 3 を完了しました」のように、スキルの手順を番号で参照する

サブエージェントのプロンプト構成

サブエージェントのプロンプトには、次の 4 つのセクションを含めます。

1. 役割：「あなたは[役割]です。[限定された領域]を担当します。範囲外の場合は、その旨を伝えてください。」
2. スキルの使用ルール：「スキルは作業手順を定めます。どのスキルが適用されるか判断し、そのワークフローに従ってください。」
3. タスクの進行手順：要約 → スキルの選択 → 確認 → 計画 → 手順に沿った実行 → 検証 → 返却（成果物＋使用したスキル＋残るリスク）。
4. 制約：品質基準、安全規則、優先順位を決める基準。

テンプレートとオーケストレーションのパターンの詳細：references/subagent-design.md を参照してください。

---

ビジュアル成果物：Mermaid ダイアグラムとコード

Mermaid ダイアグラムを含むスキルは、同時に 2 種類の利用者に役立ちます。人間にとっては、ダイアグラムは視覚的なフローチャート、状態機械、タイムラインとして表示され、すぐに把握できます。エージェントにとっては、Mermaid はテキストベースのグラフ DSL です。A -->|Yes| B は明示的で曖昧さのないエッジであり、同じ内容を文章で表現するよりも実際には推論しやすくなります。エージェントはテキストを読み、人間は図を見ます。双方にメリットがあります。

ルール：スキルでプロセス、決定木、アーキテクチャ、状態機械、タイムライン、またはデータ間の関係を説明する場合は、Mermaid ダイアグラムを含めてください。外側の Markdown フェンスで囲まず、```mermaid ブロックをそのまま SKILL.md に記述してください。

Mermaid の 23 種類の図

Mermaid は23 種類の図に対応しています。内容に最も適した図を使用してください。ライフサイクルを表す場合は、「戻る」矢印付きのフローチャートよりも状態図の方が適しています。

スキルの内容	図の種類	構文
決定木／トラブルシューティング	フローチャート	flowchart TD
API／エージェント間の通信プロトコル	シーケンス	sequenceDiagram
ライフサイクル／状態遷移	状態図	stateDiagram-v2
データモデル／スキーマ	ER 図	erDiagram
型の階層／インターフェース	クラス図	classDiagram
時系列の知識／変遷	タイムライン	timeline
ドメインの分類体系／概念マップ	マインドマップ	mindmap
優先度マトリックス（2 軸）	象限図	quadrantChart
コンポーネントのレイアウト／ブロック	ブロック図	block-beta
インフラストラクチャ／クラウドのトポロジー	アーキテクチャ図	architecture-beta
複数レベルのシステムビュー（C4）	C4	C4Context / C4Container / C4Component
プロジェクトのフェーズ／展開計画	ガントチャート	gantt
Git ブランチ／リリース戦略	Git グラフ	gitGraph
ユーザー体験のフロー	ジャーニー	journey
数量のフロー／予算	サンキー図	sankey-beta
指標／ベンチマーク	XY チャート	xychart-beta
比例関係の内訳	円グラフ	pie
階層的なサイズ比較	ツリーマップ	treemap
複数軸での機能比較	レーダーチャート	radar
タスク／状態の追跡	カンバン	kanban
要件のトレーサビリティ	要件図	requirementDiagram
ネットワークプロトコル／バイナリ形式	パケット図	packet-beta
シーケンス図（コード構文）	ZenUML	zenuml（プラグイン）

Mermaid の YAML フロントマター（任意）

Mermaid は、レンダリングのカスタマイズ（テーマ、色、間隔）に使用できる任意の --- フロントマターブロックに対応しています。**必須ではありません。**エージェントはこれを無視します。レンダラーはフロントマターがなくても適切な既定値を適用します。公開ドキュメントに特定のビジュアルスタイルが必要な場合にのみ追加してください。

# Optional — only for render customization
---
title: My Diagram
config:
  theme: neutral
  flowchart:
    curve: basis
---

テーマ：default、dark、forest、neutral、base。設定の完全なリファレンス：https://mermaid.ai/open-source/config/configuration.html

16 種類以上のすべての図を例付きで紹介する完全なカタログ：references/visual-artifacts.md を参照してください。

---

知識を見分ける要点

初心者とエキスパートを分ける専門知識です。古い学習データや、内容を理解せずに模倣したパターンが原因で、LLM が間違えやすい事柄を指します。

要点のテンプレート

### Anti-Pattern: [Name]
**Novice**: "[Wrong assumption]"
**Expert**: [Why it's wrong, with evidence]
**Timeline**: [Date]: [Old way] → [Date]: [New way]
**LLM mistake**: [Why LLMs suggest the old pattern]
**Detection**: [How to spot this in code/config]

盛り込む内容

• フレームワークの変遷（React のクラス → Hooks → サーバーコンポーネント）
• モデルの制約（CLIP は数を数えられません。埋め込みモデルはタスクごとに特化しています）
• ツールのアーキテクチャ（スクリプト → MCP への移行経路）
• API のバージョン管理（ada-002 → text-embedding-3-large）
• 時代にまつわる落とし穴（2023 年には正しかったものの、2025 年には有害なアドバイス）

事例を含む完全なカタログ：references/antipatterns.md を参照してください。

---

自己完結型ツールと拡張機能の分類

スキルは、Claude の7種類の拡張機能の1つです。Skills（ドメイン知識）、Plugins（配布用のパッケージ化されたバンドル）、MCP Servers（外部 API と認証）、Scripts（ローカル操作）、Slash Commands（ユーザーが起動するスキル）、Hooks（17以上のイベントポイントで実行されるライフサイクルの自動化）、Agent SDK（プログラムから Claude Code にアクセスするための SDK）があります。ほとんどのスキルにはスクリプトを含めるべきです。MCP は認証や状態の境界がある場合にのみ使用します。Plugins は、チームやコミュニティ間でスキルを共有するために使用します。

必要なもの	拡張機能の種類	主な要件
ドメインの専門知識／プロセス	Skill (SKILL.md)	意思決定ツリー、アンチパターン、出力要件
パッケージ化と配布	Plugin (plugin.json)	スキル、フック、MCP、エージェントをバンドル
外部 API と認証	MCP Server	動作するサーバーとセットアップ用 README
繰り返し実行するローカル操作	Script	実際に動作すること（テンプレートではない）、依存関係を最小限にする
複数ステップのオーケストレーション	Subagent	4セクションのプロンプト、スキル、ワークフロー
ユーザーが起動するアクション	Slash Command	user-invocable: true を指定したスキル
ライフサイクルの自動化	Hook	17以上のイベント：PreToolUse、PostToolUse、Stop など
プログラムからのアクセス	Agent SDK	npm/pip パッケージ、CI/CD パイプライン

進化の道筋：Skill → Skill + Scripts → Skill + MCP Server → Skill + Subagent → Plugin（配布用）。複雑さに見合う場合にのみ、次の段階へ進めてください。

例やよくある間違いを含む拡張機能の全分類：references/claude-extension-taxonomy.md を参照してください。 ツールの詳しいパターン：references/self-contained-tools.md を参照してください。 Plugin の作成と配布：references/plugin-architecture.md を参照してください。

---

ツールの権限

原則：最小権限 — 必要なものだけを許可します。

アクセスレベル	allowed-tools
読み取り専用	Read,Grep,Glob
ファイルの変更	Read,Write,Edit
ビルドとの連携	Read,Write,Bash(npm:*,git:*)
⚠️ 信頼できない対象には絶対に許可しない	無制限の Bash

---

アンチパターンの概要

#	アンチパターン	対策
1	ドキュメントの詰め込み	SKILL.md に意思決定ツリーを記載し、詳しい説明は /references に置く
2	NOT 条項の欠落	説明には必ず「X、Y、Z には使用しない」と記載する
3	実体のないツール	実在し、動作するファイルのみを参照する
4	テンプレートの寄せ集め	動作するコードを提供するか、何も提供しない
5	過度に許可範囲の広いツール	最小権限：具体的なツールのリストと、範囲を限定した Bash
6	古くなった時点依存の知識	すべてのアドバイスに日付を付け、四半期ごとに更新する
7	何でも扱うスキル	ドメインではなく、専門分野ごとに分割する
8	曖昧な説明	[何をするか] [いつ使うか] [キーワード]。対象外：[除外事項] の形式を使う
9	先読み	「最初にすべてのファイルを読む」ことは避け、必要に応じて参照先を読み込む
10	文章だけのプロセス	Mermaid 図（23種類）を使う — フローチャート、シーケンス図、状態遷移図、ER 図、タイムラインなど
11	テキストだけのビジュアルスキル	demo/ の HTML、assets/ のスクリーンショット、prompts/、手順に沿ったビルドガイドを提供する

詳細な事例：references/antipatterns.md を参照してください。

---

検証チェックリスト

□ SKILL.md exists and is <500 lines
□ Frontmatter has name + description (minimum required)
□ Description follows [What][When][Keywords] NOT [Exclusions] formula
□ Description uses keywords users would actually type
□ Name and description are aligned (not contradictory)
□ At least 1 anti-pattern with shibboleth template
□ All referenced files actually exist (no phantoms)
□ Scripts work (not templates), have clear CLI, handle errors
□ Reference files each have a 1-line purpose in SKILL.md
□ Processes/decisions/lifecycles use Mermaid diagrams (23 types), not prose
□ CHANGELOG.md tracks version history
□ If subagent-consumed: output contracts are defined
□ If visual/design skill: demo/, assets/, prompts/, templates/ per visual-design-skills.md

自動チェックを実行します：python scripts/validate_skill.py <path> と python scripts/validate_mermaid.py <path>

---

よくある拒否の原因

Claude Code がスキルの読み込み時に拒否したり、正しく処理できなかったりする原因です。

原因	症状	対処法
name または description がない	スキルが読み込まれない	frontmatter に両方を追加します
allowed-tools: ではなく tools: を指定している	ツールが無視される	allowed-tools:（ハイフン付き）を使用します
allowed-tools に YAML リストを使用している	解析エラー	カンマ区切りで指定します：Read,Write,Edit
allowed-tools に角括弧を使用している	解析エラー	[ ] は使わず、Read,Write,Edit のように指定します
無効なキー（triggers、outputs）を指定している	無視されるか、エラーになる	SKILL.md の本文に移します
名前にスペースや大文字が含まれている	マッチングに失敗する場合がある	小文字とハイフンを使用します：my-skill-name
名前がディレクトリ名と一致しない	アクティベーションの不一致	名前をディレクトリ名と同じにします
context: が fork ではない	無視される	有効な値は fork のみです
disable-model-invocation: がブール値ではない	無視される	true または false を使用します
存在しないファイルを参照している	エージェントがツール呼び出しを無駄にする	参照を削除するか、ファイルを作成します

完全な検証：python scripts/validate_skill.py <path> を実行すると、これらすべてを検出できます。

---

成功指標

指標	目標	測定方法
正しいアクティベーション	>90%	アクティベーションされるべきテストクエリを実行します
誤検知率	<5%	アクティベーションされないはずのテストクエリを実行します
トークン使用量	<5k	SKILL.md のサイズと通常の参照読み込み量
作業開始までの時間	<5 min	ユーザーがすぐに作業を開始できます
アンチパターンの防止	>80%	ユーザーが文書化された間違いを避けます

---

参照ファイル

詳しく調べる場合は、以下を参照してください。これらはデフォルトでは読み込まれません。

ファイル	参照するタイミング
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	Skills、Plugins、MCPs、Hooks、Agent SDK の比較 — 7 種類の分類
references/plugin-architecture.md	マーケットプレイスを通じてプラグインを作成、パッケージ化、配布するとき
references/visual-artifacts.md	Mermaid 図の追加：全 23 種類、YAML 設定、ベストプラクティス
references/visual-design-skills.md	Design & Creative スキルの要件：デモ、アセット、スクリーンショット、プロンプト、手続き的なビルド、帰属表示
references/mcp-template.md	スキル用の MCP サーバーを構築するとき
references/subagent-template.md	サブエージェントのプロンプトやマルチエージェントのパイプラインを定義するとき
scripts/validate_mermaid.py	任意のファイル内の Mermaid 構文を検証します。図の種類、ブロックの対応、構造上の正しさを確認します