mcpField
S
skill-developer

skill-developer

github.com/diet103エージェントワークフロー10.0k51 回インストール17 週間前に更新
リポジトリ

skill-developer について

Claude Code のスキルを作成、設定、デバッグする開発者向けガイドです。自動アクティベーションやフックによる制御に加え、段階的な情報開示や500行ルールなどの実践方法を説明します。

主な機能

  1. 01キーワードと意図によるアクティベーション
  2. 02フックによるスキル制御
  3. 03スキルルールとトリガーの設定
  4. 04セッション単位のスキップ条件
  5. 05テストとトラブルシューティング

活用シーン

  1. 01Claude Code スキルの作成
  2. 02スキルトリガーとルールの調整
  3. 03アクティベーションやフックの問題調査

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/diet103/claude-code-infrastructure-showcase --skill skill-developer

インストール後、Claude Code で/skill-developerを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

ADVANCED.md
HOOK_MECHANISMS.md
PATTERNS_LIBRARY.md
SKILL_RULES_REFERENCE.md
TRIGGER_TYPES.md
TROUBLESHOOTING.md

詳細

スキル開発者ガイド

目的

自動有効化システムを使用して Claude Code のスキルを作成・管理するための包括的なガイドです。500 行ルールや段階的開示のパターンを含む、Anthropic の公式ベストプラクティスに従います。

このスキルを使用するタイミング

次の内容に言及すると、自動的に有効化されます：

  • スキルの作成または追加
  • スキルのトリガーやルールの変更
  • スキルの有効化の仕組みの理解
  • スキル有効化に関する問題のデバッグ
  • skill-rules.json の使用
  • フックシステムの仕組み
  • Claude Code のベストプラクティス
  • 段階的開示
  • YAML フロントマター
  • 500 行ルール

システム概要

フックのアーキテクチャ（接続済みの 5 つのフック）

1. UserPromptSubmit フック（先回りした提案）

  • ファイル：.claude/hooks/skill-activation-prompt.ts
  • トリガー：Claude がユーザーのプロンプトを見る前
  • 目的：キーワードと意図パターン（正規表現またはオプションの AI 分類）に基づいて関連スキルを提案します
  • 方法：書式設定されたリマインダーをコンテキストとして挿入します（標準出力 → Claude の入力）
  • 適用：enforcement: "block" のスキルのみを必須として表示します。suggest／warn のスキルは常に推奨として表示されます

2. PreToolUse フック - スキル検証ガード（適用）

  • ファイル：.claude/hooks/skill-verification-guard.ts
  • トリガー：Edit／MultiEdit／Write の実行前
  • 目的：必須スキルの有効化（2 回試行モデル）とガードレールのファイル／コンテンツパターンを適用します。オプションで AI による編集分析も行います
  • 方法：終了コード 2 と標準エラー出力によってツールをブロックします。ブロックできるのは enforcement: "block" のスキルのみです

3. PostToolUse フック - 編集トラッカー

  • ファイル：.claude/hooks/post-tool-use-tracker.sh
  • トリガー：Edit／MultiEdit／Write の完了後
  • 目的：編集されたファイルとリポジトリを追跡します（ビルドチェックとエラー処理リマインダーに情報を渡します）

4. PostToolUse フック - スキル有効化トラッカー

  • ファイル：.claude/hooks/skill-activation-tracker.ts
  • トリガー：Skill ツールの実行後
  • 目的：有効化されたスキルを保留リストから削除し、ガードによるブロックを停止します

5. Stop フック - セッションドキュメント更新ツール

  • ファイル：.claude/hooks/session-doc-updater.ts
  • トリガー：Claude の応答完了後
  • 目的：ベクトル検索（セッションインテリジェンス）用に開発ドキュメントをインデックス化します。古くなったセッション状態は削除されます

オプション（提供済みですが未接続）： error-handling-reminder.ts（Stop）—編集をブロックする代わりに、編集されたファイルのリスクのあるパターンを分析する、応答後の穏やかなセルフチェックです。

方針の変更（2025-10-27）： Sentry／エラー処理に対する PreToolUse によるブロックを取りやめました。代わりに、ワークフローを妨げず、コード品質への意識を保つための、応答後の穏やかなリマインダーを使用します。

設定ファイル

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

次の内容を定義します：

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

スキルの種類

1. ガードレールスキル

目的： エラーを防ぐための重要なベストプラクティスを適用します

特性：

  • 種類：「guardrail」
  • 適用：「block」
  • 優先度：「critical」または「high」
  • スキルが使用されるまでファイル編集をブロックします
  • よくある間違い（カラム名、重大なエラー）を防ぎます
  • セッションを認識し、同じセッション内で同じ注意を繰り返しません

例：

  • frontend-dev-guidelines - React／TypeScript のパターンを適用します（提供されている block ガードレール）
  • Prisma クエリの前にテーブル名／カラム名を検証する database-verification スキル（仮定の例）

使用するタイミング：

  • 実行時エラーを引き起こす間違い
  • データの整合性に関する懸念
  • 重大な互換性の問題
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: Brief description including keywords that trigger this skill. Mention topics, file types, and use cases. Be explicit about trigger terms.
---

# My New Skill

## Purpose
What this skill helps with

## When to Use
Specific scenarios and conditions

## Key Information
The actual guidance, documentation, patterns, examples

ベストプラクティス：

  • ✅ 名前：小文字とハイフンを使い、動名詞形（動詞 + -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 はメッセージを確認し、処理を続行するにはスキルを使う必要があります
  • 使用する場面： 重大なミス、データの整合性、セキュリティ上の問題
  • 強制的にブロックできるのは enforcement: "block" のスキルのみです。UserPromptSubmit の必須リストと PreToolUse のガードレールチェックの両方で同様です。suggest／warn による一致は常に参考情報として扱われます。

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

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';
// This file has been manually verified

注： 多用すると本来の目的が損なわれるため、控えめに使用してください

3. 環境変数

目的： 緊急時の無効化、一時的な上書き

全体を無効にする：

export SKIP_MANDATORY_SKILLS=true   # Disables mandatory-skill blocking
export SKIP_PRETOOLUSE_AI=true      # Disables AI edit analysis in the guard

スキル固有（skill-rules.json の skipConditions.envOverride を使用）：

export SKIP_FRONTEND_GUIDELINES=true
export SKIP_ERROR_REMINDER=true     # Optional Stop-hook reminder

テストチェックリスト

新しいスキルを作成するときは、以下を確認してください。

  • スキルファイルが .claude/skills/{name}/SKILL.md に作成されている
  • name と description を含む適切なフロントマターがある
  • 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. フロントマターを含む .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_MANDATORY_SKILLS、スキルごとの envOverride（緊急時に無効化）
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/skill-verification-guard.ts - PreToolUse (Edit|MultiEdit|Write)
  • .claude/hooks/post-tool-use-tracker.sh - PostToolUse (Edit|MultiEdit|Write)
  • .claude/hooks/skill-activation-tracker.ts - PostToolUse (Skill)
  • .claude/hooks/session-doc-updater.ts - Stop
  • .claude/hooks/error-handling-reminder.ts - Stop（オプション。デフォルトでは接続されません）

すべてのスキル：

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

スキルのステータス：完了 - Anthropic のベストプラクティスに沿って再構成済み ✅ 行数：< 500（500 行ルールに準拠）✅ 段階的な開示：詳細情報はリファレンスファイルに記載 ✅

次のステップ：スキルを追加し、使用状況に基づいてパターンを改善します

コメント

Markdown 対応