skill-developer

Name: skill-developer
Author: sickn33

github.com/sickn33エージェントワークフロー48.7k638 回インストール今日更新

リポジトリ

skill-developer について

skill-developerは、Claude Codeのスキル作成、設定、デバッグのためのガイドです。例示的なフック構成や段階的な情報開示、テスト方法を扱い、カスタム構成はClaude Codeの標準機能ではないと明記しています。

主な機能

01スキルファイルとYAML frontmatterの作成
02スキルトリガーとルールの設定
03キーワード、意図、パス、内容によるトリガー
04フックの仕組みと適用レベルの説明
05トリガーのテストと動作確認

活用シーン

01Claude Codeで新しいスキルを作成
02スキルの自動起動条件を変更
03起動しない、または誤起動するスキルの調査
04カスタムフックとルール設定のテスト

インストール

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

$npx skills add https://github.com/sickn33/agentic-awesome-skills --skill skill-developer

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

同梱ファイル

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

PATTERNS_LIBRARY.md

ADVANCED.md

HOOK_MECHANISMS.md

TRIGGER_TYPES.md

TROUBLESHOOTING.md

SKILL_RULES_REFERENCE.md

詳細

スキル開発者向けガイド

目的

自動アクティベーションシステムを使って Claude Code でスキルを作成・管理するための包括的なガイドです。説明用のカスタムフックアーキテクチャと、簡潔な段階的開示パターンを使用します。

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

次の内容に言及すると、自動的にアクティベートされます。

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

対象範囲と利用可能性

ここで説明するフック、ラッパー、skill-rules.json はカスタムのサンプルシステムであり、Claude Code の組み込み機能ではなく、このツリーにも含まれていません。例を実行する前に、これらが存在することを確認し、実装を監査してください。バージョンを固定したローカル依存関係を使用し、既存の設定を維持したうえで、任意のコードを実行するフックを登録する前に許可を得てください。フックに関する提案やセッションごとに一度表示されるリマインダーは、セキュリティの強制やスキルが呼び出された証明にはなりません。

システム概要

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. ガードレールスキル

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

特徴：

種類："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. セッションの追跡

目的： 同じセッション内で何度も注意を促さないようにします

動作：

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

frontmatterを含む.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を参照してください。

制限事項

タスクが上記の説明された範囲に明確に当てはまる場合にのみ、このスキルを使用してください。
出力を、環境固有の検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を中断して確認を求めてください。

Markdown 対応

ログインしてコメント

基本情報

作者: sickn33
リポジトリ: sickn33/agentic-awesome-skills
カテゴリ: エージェントワークフロー
インストール数: 638
GitHub スター: 48,675

問題を報告