mcpField
S
skill-developer

skill-developer

github.com/grasmashエージェントワークフロー82140 回インストール4 週間前に更新
リポジトリ

skill-developer について

Claude Code のスキル作成者向け開発ガイドです。Agent Skills Specification と Anthropic の実践に沿って、構成、起動、テスト、管理を説明し、任意の高度な Hook 起動方式も紹介します。

主な機能

  1. 01スキルのディレクトリと frontmatter の要件
  2. 02段階的開示と 500 行ルールの説明
  3. 03説明文ベースと Hook ベースの起動方式
  4. 04スキルのテストとトラブルシューティング項目
  5. 05ガードレール型やドメイン型などの説明

活用シーン

  1. 01仕様に沿ったスキルの作成
  2. 02スキルの起動条件の調整
  3. 03起動しない、または誤起動するスキルの調査
  4. 04チーム向け Hook ベース起動システムの設計

インストール

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

$npx skills add https://github.com/grasmash/drupal-claude-skills --skill skill-developer

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

同梱ファイル

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

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

詳細

スキル開発者ガイド

目的

Claude Code でスキルを作成・管理するための包括的なガイドです。Agent Skills Specification に準拠し、500 行ルールや段階的な情報開示パターンなど、Anthropic のベストプラクティスに沿っています。

Agent Skills Specification (agentskills.io)

このプロジェクトのスキルは、オープンな Agent Skills Specification に準拠しています。主な要件は以下のとおりです。

ディレクトリ構造
skills/{skill-name}/
├── SKILL.md           # Required - main skill file
├── references/        # Optional - detailed documentation
├── scripts/           # Optional - executable code (Python, Bash, JS)
└── assets/            # Optional - templates, images, data files
SKILL.md のフロントマターのスキーマ

必須フィールド：

フィールド要件
name1～64 文字。小文字の英数字とハイフンを使用し、ディレクトリ名と一致させる必要があります
description1～1024 文字。エージェントの起動に使われるキーワードを含めます

任意フィールド：

フィールド目的
licenseスキルを公開して共有する際のライセンス
compatibility環境要件（パッケージ、ネットワークアクセス）
metadataカスタムプロパティ用のキーと値のペア
allowed-tools事前承認済みツールの一覧（実験的）
段階的な情報開示モデル
  1. メタデータ（約 100 トークン）— 起動時に読み込まれます
  2. 全指示（5000 トークン未満を推奨）— 有効化時に読み込まれます
  3. 補助ファイル— 必要に応じて読み込まれます
検証

skills-ref ツールを使うか、手動で検証します。

  • ファイル名は SKILL.md（大文字）である必要があります
  • フロントマターの名前は親ディレクトリ名と一致させます
  • 説明には起動キーワードを含める必要があります

このスキルを使うタイミング

以下について言及すると、自動的に有効になります。

  • スキルの作成または追加
  • スキルのトリガーやルールの変更
  • スキルの有効化の仕組みの把握
  • スキルの有効化に関する問題のデバッグ
  • Claude Code のベストプラクティス
  • 段階的な情報開示
  • YAML フロントマター
  • 500 行ルール

システムの概要

スキルの有効化方法

スキルの有効化には、シンプルなものから高度なものまで、いくつかの方法があります。

1. 説明に基づく有効化（デフォルト）

  • Claude はセッション開始時にフロントマターからスキルの説明を読み取ります
  • ユーザーのプロンプトが説明内のキーワードと一致すると、スキルを有効にします
  • 追加の設定は不要です
  • agentskills.io の仕様に準拠しており、すぐに利用できます

2. 実装例：フックベースの有効化

より高度な有効化を行うには、フックシステムを構築できます。これは高度なパターンです。

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

  • トリガー：Claude がユーザーのプロンプトを見る前
  • 目的：キーワードと意図のパターンに基づいて、関連するスキルを提案します
  • 方法：コンテキストとして、形式を整えたリマインダーを挿入します（標準出力から Claude の入力へ）

Stop フック（控えめなリマインダー）

  • トリガー：Claude の応答完了後
  • 目的：作成したコード内のパターンを自己評価するよう、控えめに促します
  • 方法：編集されたファイルのパターンを分析し、必要に応じてリマインダーを表示します

フックシステムの設定：

ルールファイル（例：skill-rules.json）では、以下を定義できます。

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

スキルの種類

1. ガードレールスキル

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

特徴：

  • 種類："guardrail"
  • 適用レベル："block"
  • 優先度："critical" または "high"
  • スキルが使用されるまで、ファイルの編集をブロックします
  • よくあるミスを防ぎます
  • セッションを認識し、同じセッション中に同じ警告を繰り返しません

例：

  • database-verification — クエリを実行する前にテーブル名とカラム名を検証します
  • frontend-dev-guidelines — React/TypeScript のパターンを徹底します

使用するタイミング：

  • 実行時エラーにつながるミス
  • データ整合性に関する懸念
  • 重大な互換性の問題
2. ドメインスキル

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

特徴：

  • 種類："domain"
  • 適用方式："suggest"
  • 優先度："high" または "medium"
  • 推奨であり、必須ではありません
  • トピックまたはドメインに特化しています
  • 包括的なドキュメントを提供します

例：

  • backend-dev-guidelines - Node.js/Express/TypeScript のパターン
  • frontend-dev-guidelines - React/TypeScript のベストプラクティス
  • drupal-search-api - Search API の設定ガイダンス

使用する場面：

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

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

ステップ 1：スキルファイルを作成する

場所： 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

ベストプラクティス（agentskills.io の仕様に準拠）：

  • 名前：1〜64 文字。小文字の英数字とハイフンを使用し、ディレクトリ名と一致させます
  • 説明：1〜1024 文字。トリガーとなるキーワードやフレーズをすべて含めます
  • 内容：500 行未満にします。詳細には references/ ディレクトリを使用します
  • 例：実際のコード例を記載します
  • 構成：明確な見出し、リスト、コードブロックを使用します
ステップ 2：（任意）トリガールールを追加する

フックベースの有効化システムを使用する場合は、ルールを追加します。

基本テンプレート：

{
  "my-new-skill": {
    "type": "domain",
    "enforcement": "suggest",
    "priority": "medium",
    "promptTriggers": {
      "keywords": ["keyword1", "keyword2"],
      "intentPatterns": ["(create|add).*?something"]
    }
  }
}
ステップ 3：有効化をテストする

スキルが正しく有効化されることを確認します。

  • 有効化されるはずのプロンプトを試します
  • 有効化されないはずのプロンプトを試します
  • 結果に基づいて説明のキーワードを調整します
ステップ 4：Anthropic のベストプラクティスに従う
  • SKILL.md は 500 行未満にします
  • 参照ファイルを使って段階的に情報を開示します
  • 100 行を超える参照ファイルには目次を追加します
  • トリガーキーワードを含む詳細な説明を記述します
  • ドキュメント化する前に、実際のシナリオで 3 回以上テストします
  • 実際の使用状況に基づいて繰り返し改善します

適用レベル

BLOCK（重要なガードレール）
  • Edit/Write ツールの実行を物理的に阻止します
  • Claude にメッセージが表示され、続行するにはスキルを使用する必要があります
  • 用途： 致命的なミス、データの整合性、セキュリティ上の問題

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

SUGGEST（推奨）
  • Claude がプロンプトを見る前にリマインダーを挿入します
  • Claude は関連するスキルを認識します
  • 強制ではなく、推奨のみです
  • 用途： ドメインに関するガイダンス、ベストプラクティス、ハウツーガイド

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

WARN（任意）
  • 優先度の低い提案です
  • 推奨のみで、適用は最小限です
  • 用途： あれば便利な提案、情報提供のためのリマインダー

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

スキップ条件とユーザーによる制御

1. セッションの追跡

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

仕組み：

  • 最初の編集：フックがブロックし、セッションの状態を更新します
  • 2 回目の編集（同じセッション）：フックが許可します
  • 別のセッション：再びブロックします
2. ファイルマーカー

目的： 検証済みファイルを恒久的にスキップします

マーカー： // @skip-validation

使用方法：

// @skip-validation
import { PrismaService } from './prisma';
// This file has been manually verified

注： 使いすぎると目的に反するため、必要最小限にしてください

3. 環境変数

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

全体を無効化：

export SKIP_SKILL_GUARDRAILS=true  # Disables ALL blocks

特定のスキル：

export SKIP_DB_VERIFICATION=true

テストチェックリスト

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

  • skills/{name}/SKILL.md にスキルファイルを作成した
  • 名前と説明を含む適切なフロントマターを設定した
  • 実際のプロンプトでキーワードをテストした
  • テストで誤検知がない
  • テストで検知漏れがない
  • SKILL.md が 500 行未満である
  • 必要に応じて参照ファイルを作成した
  • 100 行を超えるファイルに目次を追加した

高度なトピック

高度なアクティベーションシステムを構築するチームは、次の点を検討してください。

  • トリガーの種類：キーワード、意図パターン、ファイルパスの glob、コンテンツの正規表現
  • フックの仕組み：UserPromptSubmit、PreToolUse、Stop イベントフック
  • セッション状態の管理：どのスキルが確認済みかを追跡
  • パフォーマンス：フックの実行を 200ms 未満に抑える
  • パターンライブラリ：再利用可能な正規表現と glob パターン

これらのトピックは、任意のリファレンスファイルに記載されています。

  • TRIGGER_TYPES.md - トリガーの種類に関する完全ガイド
  • SKILL_RULES_REFERENCE.md - ルールスキーマのドキュメント
  • HOOK_MECHANISMS.md - フックの内部動作を詳しく解説
  • TROUBLESHOOTING.md - アクティベーションに関する問題のデバッグ
  • PATTERNS_LIBRARY.md - すぐに使えるパターン集

クイックリファレンスのまとめ

新しいスキルを作成する（4 ステップ）
  1. frontmatter を含む skills/{name}/SKILL.md を作成します
  2. 実際のプロンプトでアクティベーションをテストします
  3. テスト結果に基づいて説明文のキーワードを調整します
  4. SKILL.md を 500 行未満に保ちます
トリガーの種類
  • キーワード：明示的なトピックへの言及（説明文内）
  • 意図：暗黙的なアクションの検出（高度な機能。フックを使用）
  • ファイルパス：場所に基づくアクティベーション（高度な機能。フックを使用）
  • コンテンツ：技術固有の検出（高度な機能。フックを使用）
強制方法
  • ブロック：重大な場合にのみ使用し、ツールの実行を防止します
  • 提案：最も一般的な方法で、助言的なコンテキストを挿入します
  • 警告：助言的な方法で、使用頻度は低いです
スキップ条件
  • セッションの追跡：自動（同じ警告の繰り返しを防ぎます）
  • ファイルマーカー：// @skip-validation（永続的にスキップ）
  • 環境変数：SKIP_SKILL_GUARDRAILS（緊急時に無効化）
Anthropic のベストプラクティスと agentskills.io の仕様
  • 500 行ルール：SKILL.md を 500 行未満に保ちます
  • 段階的な開示：詳細なドキュメントには references/ ディレクトリを使用します
  • 目次：100 行を超えるリファレンスファイルには目次を追加します
  • 階層は 1 段階まで：リファレンスを深くネストしないでください
  • 充実した説明文：すべてのトリガーキーワードを含めます（仕様上、最大 1024 文字）
  • 名前とディレクトリ名の一致：frontmatter のスキル名は親ディレクトリ名と一致させる必要があります
  • まずテスト：ドキュメントを詳しく作成する前に、3 つ以上の評価を用意します
  • 仕様の URL：https://agentskills.io/specification
トラブルシューティング

スキルがアクティベーションされるべきプロンプトと、されるべきでないプロンプトを試して、アクティベーションをテストします。説明文のキーワードを繰り返し調整します。

リファレンスファイル

前述のフックベースのアクティベーションパターン（高度な任意のアーキテクチャ。説明文ベースのアクティベーションでは不要です）に関する詳細なドキュメントです。

関連ファイル

設定：

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

仕様：

クレジット

フックベースのアクティベーションアーキテクチャと上記のリファレンスファイルは、 diet103/claude-code-infrastructure-showcase （MIT License）を参考にしています。

コメント

Markdown 対応