スキル開発者ガイド

目的

Claude Code でスキルを作成・管理するための包括的ガイド。自動アクティベーションシステムを備え、Anthropic の公式ベストプラクティス（500行ルールとプログレッシブ・ディスクロージャーパターン）に従っています。

このスキルを使用する場合

以下の内容を提示したときに自動アクティベートされます：

• スキルの作成または追加
• スキルトリガーやルールの変更
• スキルアクティベーションの仕組みの理解
• スキルアクティベーション問題のデバッグ
• skill-rules.json の操作
• フック システムのメカニクス
• Claude Code のベストプラクティス
• プログレッシブ・ディスクロージャー
• YAML frontmatter
• 500行ルール

---

システム概要

2つのフック アーキテクチャ

1. UserPromptSubmit フック（プロアクティブな提案）

• ファイル: .claude/hooks/skill-activation-prompt.ts
• トリガー: Claude がユーザーのプロンプトを見る前
• 目的: キーワード＋意図パターンに基づいて関連スキルを提案
• 方法: フォーマットされたリマインダーを入力として注入（stdout → Claude の入力）
• ユースケース: トピックベースのスキル、暗黙的な作業検出

2. Stop フック - エラー処理リマインダー（穏やかなリマインダー）

• ファイル: .claude/hooks/error-handling-reminder.ts
• トリガー: Claude が応答を完了した後
• 目的: 記述されたコードのエラー処理に関する自己評価を促す穏やかなリマインダー
• 方法: 編集されたファイルをリスキーなパターンについて分析し、必要に応じてリマインダーを表示
• ユースケース: ワークフローをブロックせずにエラー処理への認識を維持

哲学的変更（2025-10-27）: Sentry/エラー処理の PreToolUse ブロッキングから移行しました。代わりに、ワークフローをブロックせず、コード品質への認識を保つ穏やかなポストレスポンスリマインダーを使用します。

設定ファイル

場所: .claude/skills/skill-rules.json

以下を定義します：

• すべてのスキルとそのトリガー条件
• 実行レベル（ブロック、提案、警告）
• ファイルパスパターン（glob）
• コンテンツ検出パターン（正規表現）
• スキップ条件（セッション追跡、ファイルマーカー、環境変数）

---

スキルタイプ

1. ガードレール スキル

目的: エラーを防止する重要なベストプラクティスを実装

特徴:

• タイプ: "guardrail"
• 実行: "block"
• 優先度: "critical" または "high"
• スキルが使用されるまでファイル編集をブロック
• 一般的なミスを防止（カラム名、重大なエラー）
• セッション対応（同じセッション内で繰り返し警告しない）

例:

• database-verification - Prisma クエリ実行前にテーブル/カラム名を検証
• frontend-dev-guidelines - React/TypeScript パターンを実装

使用する場合:

• ランタイムエラーを引き起こすミス
• データ整合性の懸念
• 重大な互換性の問題

2. ドメイン スキル

目的: 特定の領域に関する包括的なガイダンスを提供

特徴:

• タイプ: "domain"
• 実行: "suggest"
• 優先度: "high" または "medium"
• 助言的で、必須ではない
• トピックまたはドメイン固有
• 包括的なドキュメント

例:

• backend-dev-guidelines - Node.js/Express/TypeScript パターン
• frontend-dev-guidelines - React/TypeScript ベストプラクティス
• error-tracking - Sentry 統合ガイダンス

使用する場合:

• 深い知識が必要な複雑なシステム
• ベストプラクティスドキュメント
• アーキテクチャパターン
• ハウツーガイド

---

クイックスタート: 新しいスキルの作成

ステップ 1: スキルファイルの作成

場所: .claude/skills/{skill-name}/SKILL.md

テンプレート:

---
name: my-new-skill
description: このスキルをトリガーするキーワードを含む簡潔な説明。トピック、ファイルタイプ、ユースケースを記述します。トリガー用語を明確に記述してください。
---

# 私の新しいスキル

## 目的
このスキルが支援する内容

## 使用する場合
具体的なシナリオと条件

## 主な情報
実際のガイダンス、ドキュメント、パターン、例

ベストプラクティス:

• ✅ 名前: 小文字、ハイフン、ジェルント形（動詞 + -ing）が推奨
• ✅ 説明: すべてのトリガーキーワード/フレーズを含める（最大1024文字）
• ✅ コンテンツ: 500行未満 - 詳細は参照ファイルを使用
• ✅ 例: 実際のコード例
• ✅ 構造: 明確な見出し、リスト、コードブロック

ステップ 2: skill-rules.json に追加

完全なスキーマについては SKILL_RULES_REFERENCE.md を参照してください。

基本テンプレート:

{
  "my-new-skill": {
    "type": "domain",
    "enforcement": "suggest",
    "priority": "medium",
    "promptTriggers": {
      "keywords": ["keyword1", "keyword2"],
      "intentPatterns": ["(create|add).*?something"]
    }
  }
}

ステップ 3: トリガーのテスト

UserPromptSubmit をテスト:

echo '{"session_id":"test","prompt":"your test prompt"}' | \
  npx tsx .claude/hooks/skill-activation-prompt.ts

PreToolUse をテスト:

cat <<'EOF' | npx tsx .claude/hooks/skill-verification-guard.ts
{"session_id":"test","tool_name":"Edit","tool_input":{"file_path":"test.ts"}}
EOF

ステップ 4: パターンの改善

テストに基づいて：

• 不足しているキーワードを追加
• 誤検知を減らすために意図パターンを改善
• ファイルパスパターンを調整
• 実際のファイルに対してコンテンツパターンをテスト

ステップ 5: Anthropic ベストプラクティスに従う

✅ SKILL.md を 500行未満に保つ ✅ 参照ファイルでプログレッシブディスクロージャーを使用 ✅ 100行以上の参照ファイルに目次を追加 ✅ トリガーキーワード付きの詳細な説明を記述 ✅ ドキュメント化する前に 3つ以上の実シナリオでテスト ✅ 実際の使用状況に基づいて反復

---

実行レベル

BLOCK（重大なガードレール）

• Edit/Write ツールの実行を物理的に防止
• フックから終了コード 2、stderr → Claude
• Claude がメッセージを表示し、スキルを使用してから進める必要がある
• 使用対象: 重大なミス、データ整合性、セキュリティ問題

例: データベースカラム名検証

SUGGEST（推奨）

• Claude がプロンプトを見る前に注入されるリマインダー
• Claude が関連スキルを認識
• 実装されていない、単なる助言
• 使用対象: ドメインガイダンス、ベストプラクティス、ハウツーガイド

例: フロントエンド開発ガイドライン

WARN（オプション）

• 低優先度の提案
• 単なる助言で、最小限の実装
• 使用対象: 優先度の低い提案、情報提供リマインダー

めったに使用されません - ほとんどのスキルは BLOCK または SUGGEST のいずれかです。

---

スキップ条件とユーザーコントロール

1. セッション追跡

目的: 同じセッション内で繰り返し警告しない

動作方法:

• 最初の編集 → フックがブロック、セッション状態を更新
• 2番目の編集（同じセッション）→ フックが許可
• 別のセッション → 再度ブロック

状態ファイル: .claude/hooks/state/skills-used-{session_id}.json

2. ファイルマーカー

目的: 検証済みファイルの永続スキップ

マーカー: // @skip-validation

使用方法:

// @skip-validation
import { PrismaService } from './prisma';
// このファイルは手動で検証されています

注意: 過度に使用するとスキルの目的が失われるため、控えめに使用してください

3. 環境変数

目的: 緊急時の無効化、一時的なオーバーライド

グローバル無効化:

export SKIP_SKILL_GUARDRAILS=true  # すべての PreToolUse ブロックを無効化

スキル固有:

export SKIP_DB_VERIFICATION=true
export SKIP_ERROR_REMINDER=true

---

テストチェックリスト

新しいスキルを作成する場合、以下を確認してください：

• スキルファイルが .claude/skills/{name}/SKILL.md に作成されている
• 適切な frontmatter（名前と説明）が含まれている
• skill-rules.json にエントリが追加されている
• 実際のプロンプトでキーワードがテストされている
• バリエーションで意図パターンがテストされている
• 実際のファイルでファイルパスパターンがテストされている
• ファイルコンテンツに対してコンテンツパターンがテストされている
• ブロックメッセージが明確で実行可能（ガードレールの場合）
• スキップ条件が適切に設定されている
• 優先度レベルが重要性と一致している
• テストで誤検知がない
• テストで検出漏れがない
• パフォーマンスが許容範囲（< 100ms または < 200ms）
• JSON 構文が検証されている: jq . skill-rules.json
• SKILL.md が 500行以下 ⭐
• 必要に応じて参照ファイルが作成されている
• 100行以上のファイルに目次が追加されている

---

参照ファイル

特定のトピックの詳細については、以下を参照してください：

TRIGGER_TYPES.md

すべてのトリガータイプの完全ガイド：

• キーワードトリガー（明示的なトピック マッチング）
• 意図パターン（暗黙的なアクション検出）
• ファイルパストリガー（glob パターン）
• コンテンツパターン（ファイル内の正規表現）
• 各トリガーのベストプラクティスと例
• 一般的な落とし穴とテスト戦略

SKILL_RULES_REFERENCE.md

完全な skill-rules.json スキーマ：

• 完全な TypeScript インターフェース定義
• フィールド別の説明
• 完全なガードレール スキル例
• 完全なドメイン スキル例
• 検証ガイドと一般的なエラー

HOOK_MECHANISMS.md

フック内部への深い掘り下げ：

• UserPromptSubmit フロー（詳細）
• PreToolUse フロー（詳細）
• 終了コード動作テーブル（重要）
• セッション状態管理
• パフォーマンス考慮事項

TROUBLESHOOTING.md

包括的なデバッグガイド：

• スキルがトリガーされない（UserPromptSubmit）
• PreToolUse がブロックされない
• 誤検知（トリガーが多すぎる）
• フックがまったく実行されない
• パフォーマンス問題

PATTERNS_LIBRARY.md

すぐに使用できるパターン集：

• 意図パターン ライブラリ（正規表現）
• ファイルパス パターン ライブラリ（glob）
• コンテンツパターン ライブラリ（正規表現）
• ユースケース別に整理
• コピー＆ペースト可能

ADVANCED.md

今後の拡張とアイデア：

• 動的ルール更新
• スキル依存関係
• 条件付き実装
• スキル分析
• スキル バージョン管理

---

クイックリファレンス概要

新しいスキルの作成（5つのステップ）

1. frontmatter 付きで .claude/skills/{name}/SKILL.md を作成
2. .claude/skills/skill-rules.json にエントリを追加
3. npx tsx コマンドでテスト
4. テスト結果に基づいてパターンを改善
5. SKILL.md を 500行以下に保つ

トリガータイプ

• キーワード: 明示的なトピック提及
• 意図: 暗黙的なアクション検出
• ファイルパス: 場所ベースのアクティベーション
• コンテンツ: 技術固有の検出

詳細については TRIGGER_TYPES.md を参照してください。

実行

• BLOCK: 終了コード 2、重大なもののみ
• SUGGEST: コンテキストを注入、最も一般的
• WARN: 助言的、めったに使用されない

スキップ条件

• セッション追跡: 自動（繰り返し警告を防止）
• ファイルマーカー: // @skip-validation（永続スキップ）
• 環境変数: SKIP_SKILL_GUARDRAILS（緊急時無効化）

Anthropic ベストプラクティス

✅ 500行ルール: SKILL.md を 500行以下に保つ ✅ プログレッシブディスクロージャー: 詳細は参照ファイルで使用 ✅ 目次: 100行以上の参照ファイルに追加 ✅ 1レベル深: 参照を深くネストしない ✅ リッチな説明: すべてのトリガーキーワードを含める（最大1024文字） ✅ 最初にテスト: 広範なドキュメント化前に 3つ以上の評価を構築 ✅ ジェルント命名: 動詞 + -ing（例："processing-pdfs"）を優先

トラブルシューティング

フックを手動でテスト：

# UserPromptSubmit
echo '{"prompt":"test"}' | npx tsx .claude/hooks/skill-activation-prompt.ts

# PreToolUse
cat <<'EOF' | npx tsx .claude/hooks/skill-verification-guard.ts
{"tool_name":"Edit","tool_input":{"file_path":"test.ts"}}
EOF

完全なデバッグガイドについては TROUBLESHOOTING.md を参照してください。

---

関連ファイル

設定:

• .claude/skills/skill-rules.json - マスター設定
• .claude/hooks/state/ - セッション追跡
• .claude/settings.json - フック登録

フック:

• .claude/hooks/skill-activation-prompt.ts - UserPromptSubmit
• .claude/hooks/error-handling-reminder.ts - Stop イベント（穏やかなリマインダー）

すべてのスキル:

• .claude/skills/*/SKILL.md - スキルコンテンツファイル

---

スキルステータス: 完了 - Anthropic ベストプラクティスに従って再構成 ✅ 行数: < 500（500行ルールに従う） ✅ プログレッシブディスクロージャー: 詳細情報用の参照ファイル ✅

次: さらにスキルを作成し、使用状況に基づいてパターンを改善

制限事項

• このスキルは、タスクが上記の説明された範囲と明確に一致する場合にのみ使用してください。
• 出力を環境固有の検証、テスト、または専門家レビューの代わりにしないでください。
• 必須入力、許可、安全境界、または成功基準が不足している場合は、立ち止まって確認を求めてください。