skill-coach

Skill Coach：エキスパートレベルのエージェントスキルを作成する

表面的な指示だけでなく、実際のドメイン専門知識を組み込みます。初心者とエキスパートを分ける深い知識、つまり シボレス に重点を置きます。

このスキルを使う場面

次の場合に使います：

• 新しいエージェントスキルをゼロから作成する
• 既存のスキルをレビュー／監査する
• スキルの起動率を改善する
• スキルにドメイン専門知識を追加する
• スキルが起動しない理由をデバッグする

次の場合には使いません：

• 一般的な Claude Code の機能（スラッシュコマンド、MCP）
• スキル以外のコーディングに関するアドバイス
• 実行時エラーのデバッグ（ドメインスキルを使ってください）

すぐにできる改善

既存のスキルをすぐに改善する方法：

1. 説明に NOT 条項 を追加する → 誤起動を防ぎます
2. アンチパターンを1～2個 追加する → よくある間違いを防ぎます
3. 行数を確認する（バリデーターを実行）→ 500行未満にしてください
4. 使われていないファイルを削除する → 参照されていないスクリプト／リファレンスを削除します
5. 起動をテストする → 起動すべき質問と、起動すべきでない質問を確認します

優れたスキルとは

優れたスキルは、次のことを実現する 段階的開示の仕組み です。

1. 正確に起動する - 具体的なキーワードと NOT 条項を使います
2. シボレスを組み込む - 初心者とエキスパートを分ける専門知識を備えます
3. アンチパターンを明示する - 「X が見えたら、それは Y の理由で誤りです。代わりに Z を使ってください」
4. 時間に関する知識を取り込む - 「2024年以前：X。2024年以降：Y」
5. 適用範囲を把握する - 「A、B、C には使います。D、E、F には使いません」
6. 判断ツリーを提示する - テンプレートではなく、「X なら A、Y なら B」
7. 500行未満に保つ - 中核は SKILL.md に置き、詳細は /references に分けます

基本原則

段階的開示

• フェーズ 1（約100トークン）：メタデータ - 「起動すべきか？」
• フェーズ 2（<5k トークン）：SKILL.md - 「どうすればよいか？」
• フェーズ 3（必要に応じて）：リファレンス - 「詳細を確認する」

重要：SKILL.md は500行未満に保ってください。詳細は /references に分けます。

説明の形式

[内容] [用途] [キーワード] NOT for [除外事項]

❌ Bad: "Helps with images"
⚠️ Better: "Image processing with CLIP"
✅ Good: "CLIP semantic search. Use for image-text matching.
   Activate on 'CLIP', 'embeddings'. NOT for counting, spatial reasoning."

SKILL.md のテンプレート

---
name: your-skill-name
description: [What] [When] [Triggers]. NOT for [Exclusions].
allowed-tools: Read,Write  # Minimal only
---

# Skill Name
[One sentence purpose]

## When to Use
✅ Use for: [A, B, C]
❌ NOT for: [D, E, F]

## Core Instructions
[Step-by-step, decision trees, not templates]

## Common Anti-Patterns
### [Pattern]
**Symptom**: [Recognition]
**Problem**: [Why wrong]
**Solution**: [Better approach]

Frontmatter のルール（重要）

Claude のスキルマーケットプレイスで使用できる frontmatter のキーは、次のものだけです：

キー	必須	用途
name	✅	小文字とハイフンで構成された識別子
description	✅	起動キーワードと NOT 条項
allowed-tools	⚠️	カンマ区切りのツール名
license	❌	例：「MIT」
metadata	❌	カスタムのキーと値の組

アップロード時にエラーになる無効なキー：

# ❌ WRONG - These will break skill upload
integrates_with:
  - orchestrator
triggers:
  - "activate on this"
tools: Read,Write
outputs: formatted text
coordinates_with: other-skill
python_dependencies:
  - numpy

カスタム情報は本文に移動します：

## Integrations
Works with: orchestrator, team-builder

## Activation Triggers
Responds to: "create skill", "review skill", "skill quality"

検証コマンド：

# Find invalid frontmatter keys
for skill in .claude/skills/*/SKILL.md; do
  sed -n '/^---$/,/^---$/p' "$skill" | grep -E "^[a-zA-Z_-]+:" | cut -d: -f1 | \
    grep -vE "^(name|description|license|allowed-tools|metadata)$" && \
    echo "  ^ in $(basename $(dirname $skill))"
done

スキルの構成

必須：

your-skill/
└── SKILL.md           # Core instructions (max 500 lines)

強く推奨（自己完結型のスキル）：

├── scripts/           # Working code - NOT templates
├── mcp-server/        # Custom MCP if external APIs needed
├── agents/            # Subagent definitions if orchestration needed
├── references/        # Deep dives on domain knowledge
└── CHANGELOG.md       # Version history

自己完結型のスキル（推奨）

動作するツールを備えたスキルは、すぐに役立ちます。 パターンの詳細は references/self-contained-tools.md を参照してください。

簡単な判断基準：外部 API ですか？→ MCP。複数ステップのワークフローですか？→ サブエージェント。繰り返し可能な操作ですか？→ スクリプト。

判断ツリー

新しいスキルを作るべき場合は？

• ✅ 既存のスキルにないドメイン専門知識がある
• ✅ 3つ以上のプロジェクトでパターンが繰り返される
• ✅ 防止したいアンチパターンがある
• ❌ 一度限りのタスク → そのまま実行します
• ❌ 既存のスキルを拡張できる → そのスキルを改善します

スキル、サブエージェント、MCP の使い分けは？

• スキル：ドメイン専門知識、判断ツリー（実行時の状態なし）
• サブエージェント：ツールのオーケストレーションが必要な複数ステップのワークフロー
• MCP：外部 API、認証、ステートフルな接続

スキル作成プロセス（6ステップ）

新しいスキルを作成する際は、次の手順を順番に実行してください。

ステップ 1：具体例を使って理解する

使用パターンがすでに明確な場合に限り、省略します。次の質問をします。

• 「このスキルで、どのような機能をサポートすべきですか？」
• 「どのように使うか、例を挙げてもらえますか？」
• 「どのような依頼があれば、このスキルを起動すべきですか？」

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

各例について、次の点を分析します。

1. ゼロから実行する方法
2. 繰り返し実行する際に役立つスクリプト、参考資料、アセット

分析例：

• pdf-editor で「この PDF を回転して」→ scripts/rotate_pdf.py が必要です
• frontend-webapp-builder → assets/hello-world/ テンプレートが必要です
• big-query スキル → テーブルスキーマ用の references/schema.md が必要です

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

スキルのディレクトリ構造を作成します。

your-skill/
├── SKILL.md           # Core instructions (max 500 lines)
├── scripts/           # Working code - NOT templates
├── references/        # Deep dives on domain knowledge
└── assets/            # Files used in output (templates, icons)

ステップ 4：SKILL.md を作成する

• 命令形／不定詞形（「X を達成するには、Y を行う」）で記述します
• 次の点に答えます：目的は何か？いつ使うか？同梱リソースをどう使うか？
• すべてのスクリプト／参考資料に触れ、Claude がそれらの存在を把握できるようにします

ステップ 5：検証してパッケージ化する

# Validate skill structure and content
python scripts/validate_skill.py <path>

# Check for self-contained tool completeness
python scripts/check_self_contained.py <path>

ステップ 6：反復する

実際に使用した後：

1. うまくいかない点や非効率な点を確認します
2. SKILL.md または同梱リソースの更新が必要な箇所を特定します
3. 変更を実施して、再度テストします

---

一般的なワークフロー

専門知識からスキルを作成する：

1. 範囲を定義します：どのような専門知識か？どのようなキーワードか？対応しないことは何か？
2. キーワードと非対応事項を記載した説明を作成します
3. これまでに確認したアンチパターンを追加します
4. 有効化を徹底的にテストします

有効化の問題をデバッグする（フローチャート）：

Skill not activating when expected?
├── Check description has specific keywords
│   ├── NO → Add "Activate on: keyword1, keyword2"
│   └── YES → Check if query contains those keywords
│       ├── NO → Add missing keyword variations
│       └── YES → Check for conflicting NOT clause
│           ├── YES → Narrow exclusion scope
│           └── NO → Check file structure
│               ├── SKILL.md missing → Create it
│               └── Wrong location → Move to .claude/skills/

Skill activating when it shouldn't?
├── Missing NOT clause?
│   ├── YES → Add "NOT for: exclusion1, exclusion2"
│   └── NO → NOT clause too narrow
│       └── Expand exclusions based on false positive queries

python scripts/test_activation.py <path> を実行して検証します

再帰的な自己改善（このスキルを使ってスキルを改善する）：

1. python scripts/validate_skill.py <path> を実行します → 検証レポートを取得します
2. python scripts/check_self_contained.py <path> を実行します → ツールが揃っているか確認します
3. まず ERRORS に対処し、次に WARNINGS、最後に SUGGESTIONS に対処します
4. 問題がなくなるまで検証を再実行します
5. 改善内容を CHANGELOG.md に記録します

ツールの権限

ガイドライン：

• 読み取り専用のスキル：Read,Grep,Glob
• ファイル変更用：Read,Write,Edit
• ビルド統合：Read,Write,Bash(npm:*,git:*)
• ⚠️ 禁止：信頼できないスキルに、制限のない Bash を許可しないでください

成功指標

指標	目標
正しい有効化率	>90%
誤検知率	<5%
トークン使用量	通常 <5k

参考ファイル

ファイル	内容
references/antipatterns.md	ドメイン固有の専門知識を示す言葉と、事例を含むアンチパターンカタログ
references/shibboleths.md	専門家と初心者の知識パターン
references/validation-checklist.md	完全なレビューおよびテストガイド
references/self-contained-tools.md	スクリプト、MCP サーバー、サブエージェントの実装パターン
references/scoring-rubric.md	スキルの定量評価（0～10 点）
references/skill-composition.md	スキル間の依存関係と構成パターン
references/skill-lifecycle.md	保守、バージョン管理、非推奨化に関するガイダンス
references/mcp_vs_scripts.md	アーキテクチャの判断ガイド：スキル、エージェント、MCP、スクリプトの比較

---

このスキルがガイドする内容：スキルの作成 | スキルの監査 | アンチパターンの検出 | 段階的な情報開示 | ドメイン専門知識の体系化