skill-developer

Name: skill-developer
Author: davila7

github.com/davila7エージェントワークフロー33.0k312 回インストール今日更新

リポジトリ

skill-developer について

Claude Code のスキル作成と管理を案内し、自動アクティベーション、トリガールール、フックの仕組みを扱います。スキルのワークフローを構築・デバッグする開発者向けです。

主な機能

01スキルファイルの構成と作成指針
02トリガーとルールの設定
03フックの動作説明
04スキル起動のトラブルシューティング
05500行制限と段階的開示の実践

活用シーン

01新しいスキルの作成と登録
02スキルのトリガー語やルールの調整
03起動しないスキルの原因調査

インストール

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

$npx skills add https://github.com/davila7/claude-code-templates --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 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）
コンテンツ検出パターン（regex）
スキップ条件（セッション追跡、ファイルマーカー、環境変数）

スキルの種類

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: 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 はメッセージを確認し、続行するにはスキルを使用する必要があります
用途: 重大なミス、データ整合性、セキュリティの問題

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

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

NOTE: 控えめに使用してください - 使いすぎると本来の目的が損なわれます

3. 環境変数

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

グローバル無効化:

export SKIP_SKILL_GUARDRAILS=true  # Disables ALL PreToolUse blocks

スキル固有:

export SKIP_DB_VERIFICATION=true
export SKIP_ERROR_REMINDER=true

テストチェックリスト

新しいスキルを作成する際は、次を確認してください:

参照ファイル

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

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ステップ）

.claude/skills/{name}/SKILL.md をフロントマター付きで作成します
.claude/skills/skill-rules.json にエントリーを追加します
npx tsx コマンドでテストします
テスト結果に基づいてパターンを調整します
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 をご覧ください。

基本情報

作者: davila7
リポジトリ: davila7/claude-code-templates
カテゴリ: エージェントワークフロー
インストール数: 312
GitHub スター: 33,002

問題を報告