スキル開発者ガイド

目的

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

このスキルを使用する時期

以下について言及した場合、自動的にアクティベートされます：

• スキルの作成または追加
• スキルトリガーまたはルールの変更
• スキルアクティベーションの仕組みの理解
• スキルアクティベーション問題のデバッグ
• 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

定義内容：

• すべてのスキルとそのトリガー条件
• 強制レベル（block、suggest、warn）
• ファイルパターン（glob）
• コンテンツ検出パターン（正規表現）
• スキップ条件（セッション追跡、ファイルマーカー、環境変数）

---

スキルタイプ

1. ガードレールスキル

目的： エラーを防ぐ重大なベストプラクティスを強制

特性：

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

例：

• database-verification - Prisma クエリの前に table/column 名を検証
• frontend-dev-guidelines - React/TypeScript パターンを強制

使用時機：

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

2. ドメインスキル

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

特性：

• Type: "domain"
• Enforcement: "suggest"
• Priority: "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行未満に保つ

トリガータイプ

• Keywords: 明示的なトピックの言及
• Intent: 暗黙的なアクション検出
• File Paths: 場所ベースのアクティベーション
• Content: テクノロジー固有の検出

完全な詳細は 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行ルールに従う） ✅ プログレッシブディスクロージャー: 詳細情報のための参照ファイル ✅

次へ: さらに多くのスキルを作成し、使用状況に基づいてパターンを調整