スキルクリエイター：効果的なClaudeスキルを構築する

--- name: skill-creator description: 効果的なスキルを作成するためのガイド。ユーザーが専門知識、ワークフロー、ツール連携でClaudeの機能を拡張する新しいスキル（または既存スキルの更新）を作成したい場合に使用します。 license: LICENSE.txtの完全な規約 --- # スキルクリエイター このスキルは、効果的なスキルを作成するためのガイダンスを提供します。 ## スキルについて スキルは、専門知識、ワークフロー、ツールを提供することでClaudeの機能を拡張する、モジュール式の自己完結型パッケージです。特定のドメインやタスクの「オンボーディングガイド」と考えてください。汎用エージェントを、モデルが完全には保持できない手続き的知識を備えた専門エージェントに変えます。 ### スキルが提供するもの 1. 専門ワークフロー - 特定ドメイン向けの多段階手順 2. ツール連携 - 特定のファイル形式やAPIを扱うための指示 3. ドメイン専門知識 - 会社固有の知識、スキーマ、ビジネスロジック 4. バンドルリソース - 複雑で反復的なタスク用のスクリプト、リファレンス、アセット ## 基本原則 ### 簡潔さが鍵 コンテキストウィンドウは公共財です。スキルは、システムプロンプト、会話履歴、他のスキルのメタデータ、実際のユーザーリクエストなど、Claudeが必要とするすべてのものとコンテキストウィンドウを共有します。 **デフォルトの前提: Claudeはすでに非常に賢い。** Claudeがまだ持っていないコンテキストのみを追加してください。各情報に問いかけてください:「Claudeは本当にこの説明を必要とするか?」「この段落はトークンコストに見合うか?」 冗長な説明よりも簡潔な例を優先してください。 ### 適切な自由度の設定 タスクの脆弱性と変動性に合わせて特異性のレベルを調整します: **高自由度(テキストベースの指示)**: 複数のアプローチが有効な場合、決定が文脈に依存する場合、ヒューリスティックがアプローチを導く場合に使用します。 **中自由度(パラメータ付きの擬似コードまたはスクリプト)**: 推奨パターンが存在し、ある程度の変動が許容される場合、または設定が動作に影響する場合に使用します。 **低自由度(特定のスクリプト、少数のパラメータ)**: 操作が脆弱でエラーが発生しやすい場合、一貫性が重要な場合、または特定のシーケンスに従う必要がある場合に使用します。 Claudeが道を探索していると考えてください。崖のある狭い橋には特定のガードレール(低自由度)が必要ですが、開けた野原では多くのルート(高自由度)が可能です。 ### スキルの構造 すべてのスキルは、必須のSKILL.mdファイルとオプションのバンドルリソースで構成されます: ``` skill-name/ ├── SKILL.md (必須) │ ├── YAMLフロントマターのメタデータ (必須) │ │ ├── name: (必須) │ │ └── description: (必須) │ └── Markdownの指示 (必須) └── バンドルリソース (オプション) ├── scripts/ - 実行可能コード (Python/Bashなど) ├── references/ - 必要に応じてコンテキストに読み込むことを意図したドキュメント └── assets/ - 出力で使用されるファイル (テンプレート、アイコン、フォントなど) ``` #### SKILL.md (必須) すべてのSKILL.mdは以下で構成されます: - **フロントマター** (YAML): `name` と `description` フィールドを含みます。これらはClaudeがスキルを使用するタイミングを判断するために読み取る唯一のフィールドであり、スキルが何であるか、いつ使用すべきかを明確かつ包括的に説明することが非常に重要です。 - **ボディ** (Markdown): スキルを使用するための指示とガイダンス。スキルがトリガーされた後にのみ読み込まれます(読み込まれない場合もあります)。 #### バンドルリソース (オプション) ##### スクリプト (`scripts/`) 決定的な信頼性が必要なタスクや繰り返し書き直されるタスクのための実行可能コード (Python/Bashなど)。 - **含めるタイミング**: 同じコードが繰り返し書き直されている場合、または決定的な信頼性が必要な場合 - **例**: PDF回転タスク用の `scripts/rotate_pdf.py` - **利点**: トークン効率が良く、決定的で、コンテキストに読み込まずに実行可能 - **注記**: スクリプトは、パッチ適用や環境固有の調整のためにClaudeが読み取る必要がある場合があります ##### リファレンス (`references/`) Claudeのプロセスと思考に情報を提供するために、必要に応じてコンテキストに読み込むことを意図したドキュメントと参考資料。 - **含めるタイミング**: Claudeが作業中に参照すべきドキュメント用 - **例**: 財務スキーマ用の `references/finance.md`、会社のNDAテンプレート用の `references/mnda.md`、会社方針用の `references/policies.md`、API仕様用の `references/api_docs.md` - **ユースケース**: データベーススキーマ、APIドキュメント、ドメイン知識、会社方針、詳細なワークフローガイド - **利点**: SKILL.mdを簡潔に保ち、Claudeが必要と判断した場合にのみ読み込む - **ベストプラクティス**: ファイルが大きい場合 (>10k語)、SKILL.mdにgrep検索パターンを含めます - **重複を避ける**: 情報はSKILL.mdまたはリファレンスファイルのいずれかに配置し、両方には配置しないでください。 ##### アセット (`assets/`) コンテキストに読み込むことを意図していないが、Claudeが生成する出力内で使用されるファイル。 - **含めるタイミング**: スキルが最終出力で使用されるファイルを必要とする場合 - **例**: ブランドアセット用の `assets/logo.png`、PowerPointテンプレート用の `assets/slides.pptx` - **ユースケース**: テンプレート、画像、アイコン、ボイラープレートコード、フォント、サンプルドキュメント ### 段階的開示の設計原則 スキルは3レベルの読み込みシステムを使用してコンテキストを効率的に管理します: 1. **メタデータ (name + description)** - 常にコンテキスト内 (~100語) 2. **SKILL.mdボディ** - スキルがトリガーされたとき (<5k語) 3. **バンドルリソース** - Claudeが必要に応じて SKILL.mdボディを必須事項に保ち、コンテキストの肥大化を最小限に抑えるために500行未満にしてください。 ## スキル作成プロセス スキル作成には以下の手順が含まれます: 1. 具体的な例でスキルを理解する 2. 再利用可能なスキルコンテンツ (スクリプト、リファレンス、アセット) を計画する 3. スキルを初期化する (init_skill.pyを実行) 4. スキルを編集する (リソースを実装し、SKILL.mdを作成) 5. スキルをパッケージ化する (package_skill.pyを実行) 6. 実際の使用状況に基づいて反復する ### ステップ3: スキルの初期化 新しいスキルをゼロから作成する場合は、常に `init_skill.py` スクリプトを実行します: ```bash scripts/init_skill.py <skill-name> --path <output-directory> ``` ### ステップ4: スキルの編集 スキルのニーズに基づいて、以下の役立つガイドを参照してください: - **多段階プロセス**: 順次ワークフローと条件ロジックについては、references/workflows.mdを参照 - **特定の出力形式または品質基準**: テンプレートと例のパターンについては、references/output-patterns.mdを参照 ### ステップ5: スキルのパッケージ化 ```bash scripts/package_skill.py <path/to/skill-folder> ``` パッケージ化スクリプトは検証し、配布用の.skillファイルを作成します。 FILE:references/workflows.md # ワークフローパターン ## 順次ワークフロー 複雑なタスクの場合は、操作を明確な順次ステップに分割します。SKILL.mdの冒頭でプロセスの概要をClaudeに示すと役立つことがよくあります: ```markdown PDFフォームへの記入には以下の手順が含まれます: 1. フォームを分析する (analyze_form.pyを実行) 2. フィールドマッピングを作成する (fields.jsonを編集) 3. マッピングを検証する (validate_fields.pyを実行) 4. フォームに記入する (fill_form.pyを実行) 5. 出力を検証する (verify_output.pyを実行) ``` ## 条件ワークフロー 分岐ロジックを伴うタスクの場合は、決定ポイントを通じてClaudeをガイドします: ```markdown 1. 変更タイプを決定します: **新しいコンテンツを作成?** → 以下の「作成ワークフロー」に従う **既存コンテンツを編集?** → 以下の「編集ワークフロー」に従う 2. 作成ワークフロー: [手順] 3. 編集ワークフロー: [手順] ``` FILE:references/output-patterns.md # 出力パターン スキルが一貫した高品質の出力を生成する必要がある場合に、これらのパターンを使用します。 ## テンプレートパターン 出力形式のテンプレートを提供します。厳格さのレベルをニーズに合わせます。 **厳格な要件の場合 (APIレスポンスやデータ形式など):** ```markdown ## レポート構造 常にこの正確なテンプレート構造を使用します: # [分析タイトル] ## エグゼクティブサマリー [主要な調査結果の1段落の概要] ## 主要な調査結果 - データを伴う調査結果1 - データを伴う調査結果2 - データを伴う調査結果3 ## 推奨事項 1. 具体的で実行可能な推奨事項 2. 具体的で実行可能な推奨事項 ``` **柔軟なガイダンスの場合 (適応が役立つ場合):** ```markdown ## レポート構造 これは適切なデフォルト形式ですが、最良の判断を使用してください: # [分析タイトル] ## エグゼクティブサマリー [概要] ## 主要な調査結果 [発見に基づいてセクションを適応] ## 推奨事項 [特定のコンテキストに合わせて調整] 特定の分析タイプに応じてセクションを調整します。 ``` ## 例パターン 出力品質が例を見ることに依存するスキルの場合は、入力/出力ペアを提供します: ```markdown ## コミットメッセージ形式 以下の例に従ってコミットメッセージを生成します: **例1:** 入力: JWTトークンでユーザー認証を追加 出力: ``` feat(auth): JWTベースの認証を実装 ログインエンドポイントとトークン検証ミドルウェアを追加 ``` **例2:** 入力: レポートで日付が正しく表示されないバグを修正 出力: ``` fix(reports): タイムゾーン変換での日付形式を修正 レポート生成全体でUTCタイムスタンプを一貫して使用 ``` このスタイルに従います: type(scope): 簡潔な説明、その後詳細な説明。 ``` 例は、説明だけよりも、望ましいスタイルと詳細レベルをClaudeが理解するのに役立ちます。 FILE:scripts/quick_validate.py #!/usr/bin/env python3 """ スキル用のクイック検証スクリプト - 最小バージョン """ import sys import os import re import yaml from pathlib import Path def validate_skill(skill_path): """スキルの基本検証""" skill_path = Path(skill_path) # SKILL.mdが存在するか確認 skill_md = skill_path / 'SKILL.md' if not skill_md.exists(): return False, "SKILL.mdが見つかりません" # フロントマターを読み取り、検証 content = skill_md.read_text() if not content.startswith('---'): return False, "YAMLフロントマターが見つかりません" # フロントマターを抽出 match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL) if not match: return False, "フロントマター形式が無効です" frontmatter_text = match.group(1) # YAMLフロントマターを解析 try: frontmatter = yaml.safe_load(frontmatter_text) if not isinstance(frontmatter, dict): return False, "フロントマターはYAML辞書である必要があります" except yaml.YAMLError as e: return False, f"フロントマターのYAMLが無効です: {e}" # 許可されるプロパティを定義 ALLOWED_PROPERTIES = {'name', 'description', 'license', 'allowed-tools', 'metadata'} # 予期しないプロパティを確認 (metadataの下のネストされたキーを除く) unexpected_keys = set(frontmatter.keys()) - ALLOWED_PROPERTIES if unexpected_keys: return False, ( f"SKILL.mdフロントマターに予期しないキーがあります: {', '.join(sorted(unexpected_keys))}. " f"許可されるプロパティは: {', '.join(sorted(ALLOWED_PROPERTIES))}" ) # 必須フィールドを確認 if 'name' not in frontmatter: return False, "フロントマターに'name'がありません" if 'description' not in frontmatter: return False, "フロントマターに'description'がありません" # 検証用にnameを抽出 name = frontmatter.get('name', '') if not isinstance(name, str): return False, f"nameは文字列である必要があります。型: {type(name).__name__}" name = name.strip() if name: # 命名規則を確認 (ハイフンケース: 小文字とハイフンのみ) if not re.match(r'^[a-z0-9-]+$', name): return False, f"name '{name}' はハイフンケースである必要があります (小文字、数字、ハイフンのみ)" if name.startswith('-') or name.endswith('-') or '--' in name: return False, f"name '{name}' はハイフンで開始/終了できず、連続ハイフンを含めることはできません" # nameの長さを確認 (仕様に基づく最大64文字) if len(name) > 64: return False, f"nameが長すぎます ({len(name)}文字)。最大は64文字です。" # descriptionを抽出して検証 description = frontmatter.get('description', '') if not isinstance(description, str): return False, f"descriptionは文字列である必要があります。型: {type(description).__name__}" description = description.strip() if description: # 山括弧を確認 if '<' in description or '>' in description: return False, "descriptionに山括弧 (< または >) を含めることはできません" # descriptionの長さを確認 (仕様に基づく最大1024文字) if len(description) > 1024: return False, f"descriptionが長すぎます ({len(description)}文字)。最大は1024文字です。" return True, "スキルは有効です!" if __name__ == "__main__": if len(sys.argv) != 2: print("使用方法: python quick_validate.py <skill_directory>") sys.exit(1) valid, message = validate_skill(sys.argv[1]) print(message) sys.exit(0 if valid else 1) FILE:scripts/init_skill.py #!/usr/bin/env python3 """ スキルイニシャライザ - テンプレートから新しいスキルを作成 使用方法: init_skill.py <skill-name> --path <path> 例: init_skill.py my-new-skill --path skills/public init_skill.py my-api-helper --path skills/private init_skill.py custom-skill --path /custom/location """ import sys from pathlib import Path SKILL_TEMPLATE = """--- name: {skill_name} description: [TODO: スキルが何をするか、いつ使用するかの完全かつ情報豊富な説明。このスキルをトリガーする特定のシナリオ、ファイルタイプ、タスクを含むWHENを含めてください。] --- # {skill_title} ## 概要 [TODO: このスキルが何を可能にするかの1-2文の説明] ## リソース このスキルには、さまざまなタイプのバンドルリソースを整理する方法を示すサンプルリソースディレクトリが含まれています: ### scripts/ 特定の操作を実行するために直接実行できる実行可能コード (Python/Bashなど)。 ### references/ Claudeのプロセスと思考に情報を提供するためにコンテキストに読み込むことを意図したドキュメントと参考資料。 ### assets/ コンテキストに読み込むことを意図していないが、Claudeが生成する出力内で使用されるファイル。 --- **不要なディレクトリは削除できます。** すべてのスキルが3種類すべてのリソースを必要とするわけではありません。 """ EXAMPLE_SCRIPT = '''#!/usr/bin/env python3 """ {skill_name} 用のサンプルヘルパースクリプト これは直接実行できるプレースホルダースクリプトです。 実際の実装に置き換えるか、不要な場合は削除してください。 """ def main(): print("これは {skill_name} 用のサンプルスクリプトです") # TODO: 実際のスクリプトロジックをここに追加 if __name__ == "__main__": main() ''' EXAMPLE_REFERENCE = """# {skill_title} 用のリファレンスドキュメント これは詳細なリファレンスドキュメント用のプレースホルダーです。 実際のリファレンスコンテンツに置き換えるか、不要な場合は削除してください。 """ EXAMPLE_ASSET = """# サンプルアセットファイル このプレースホルダーは、アセットファイルが保存される場所を表します。 実際のアセットファイル (テンプレート、画像、フォントなど) に置き換えるか、不要な場合は削除してください。 """ def title_case_skill_name(skill_name): """ハイフン付きスキル名を表示用にタイトルケースに変換します。""" return ' '.join(word.capitalize() for word in skill_name.split('-')) def init_skill(skill_name, path): """テンプレートSKILL.mdで新しいスキルディレクトリを初期化します。""" skill_dir = Path(path).resolve() / skill_name if skill_dir.exists(): print(f"❌ エラー: スキルディレクトリがすでに存在します: {skill_dir}") return None try: skill_dir.mkdir(parents=True, exist_ok=False) print(f"✅ スキルディレクトリを作成しました: {skill_dir}") except Exception as e: print(f"❌ ディレクトリ作成エラー: {e}") return None skill_title = title_case_skill_name(skill_name) skill_content = SKILL_TEMPLATE.format(skill_name=skill_name, skill_title=skill_title) skill_md_path = skill_dir / 'SKILL.md' try: skill_md_path.write_text(skill_content) print("✅ SKILL.mdを作成しました") except Exception as e: print(f"❌ SKILL.md作成エラー: {e}") return None try: scripts_dir = skill_dir / 'scripts' scripts_dir.mkdir(exist_ok=True) example_script = scripts_dir / 'example.py' example_script.write_text(EXAMPLE_SCRIPT.format(skill_name=skill_name)) example_script.chmod(0o755) print("✅ scripts/example.pyを作成しました") references_dir = skill_dir / 'references' references_dir.mkdir(exist_ok=True) example_reference = references_dir / 'api_reference.md' example_reference.write_text(EXAMPLE_REFERENCE.format(skill_title=skill_title)) print("✅ references/api_reference.mdを作成しました") assets_dir = skill_dir / 'assets' assets_dir.mkdir(exist_ok=True) example_asset = assets_dir / 'example_asset.txt' example_asset.write_text(EXAMPLE_ASSET) print("✅ assets/example_asset.txtを作成しました") except Exception as e: print(f"❌ リソースディレクトリ作成エラー: {e}") return None print(f"\n✅ スキル '{skill_name}' が正常に初期化されました: {skill_dir}") return skill_dir def main(): if len(sys.argv) < 4 or sys.argv[2] != '--path': print("使用方法: init_skill.py <skill-name> --path <path>") sys.exit(1) skill_name = sys.argv[1] path = sys.argv[3] print(f"🚀 スキルを初期化中: {skill_name}") print(f" 場所: {path}") print() result = init_skill(skill_name, path) sys.exit(0 if result else 1) if __name__ == "__main__": main() FILE:scripts/package_skill.py #!/usr/bin/env python3 """ スキルパッケージャ - スキルフォルダーの配布可能な.skillファイルを作成 使用方法: python utils/package_skill.py <path/to/skill-folder> [output-directory] 例: python utils/package_skill.py skills/public/my-skill python utils/package_skill.py skills/public/my-skill ./dist """ import sys import zipfile from pathlib import Path from quick_validate import validate_skill def package_skill(skill_path, output_dir=None): """スキルフォルダーを.skillファイルにパッケージ化します。""" skill_path = Path(skill_path).resolve() if not skill_path.exists(): print(f"❌ エラー: スキルフォルダーが見つかりません: {skill_path}") return None if not skill_path.is_dir(): print(f"❌ エラー: パスはディレクトリではありません: {skill_path}") return None skill_md = skill_path / "SKILL.md" if not skill_md.exists(): print(f"❌ エラー: SKILL.mdが {skill_path} に見つかりません") return None print("🔍 スキルを検証中...") valid, message = validate_skill(skill_path) if not valid: print(f"❌ 検証に失敗しました: {message}") print(" パッケージ化する前に検証エラーを修正してください。") return None print(f"✅ {message}\n") skill_name = skill_path.name if output_dir: output_path = Path(output_dir).resolve() output_path.mkdir(parents=True, exist_ok=True) else: output_path = Path.cwd() skill_filename = output_path / f"{skill_name}.skill" try: with zipfile.ZipFile(skill_filename, 'w', zipfile.ZIP_DEFLATED) as zipf: for file_path in skill_path.rglob('*'): if file_path.is_file(): arcname = file_path.relative_to(skill_path.parent) zipf.write(file_path, arcname) print(f" 追加: {arcname}") print(f"\n✅ スキルを正常にパッケージ化しました: {skill_filename}") return skill_filename except Exception as e: print(f"❌ .skillファイル作成エラー: {e}") return None def main(): if len(sys.argv) < 2: print("使用方法: python utils/package_skill.py <path/to/skill-folder> [output-directory]") sys.exit(1) skill_path = sys.argv[1] output_dir = sys.argv[2] if len(sys.argv) > 2 else None print(f"📦 スキルをパッケージ化中: {skill_path}") if output_dir: print(f" 出力ディレクトリ: {output_dir}") print() result = package_skill(skill_path, output_dir) sys.exit(0 if result else 1) if __name__ == "__main__": main()