@einja/dev-cli 0.1.37 → 0.1.39

package/presets/default/.claude/skills/einja-skill-creator/SKILL.md

@@ -0,0 +1,421 @@
+---
+name: einja-skill-creator
+description: 効果的なSkillを作成するためのガイド。ユーザーが新しいSkillを作成したい（または既存のSkillを更新したい）場合に使用。Skillの構造、段階的開示、適切な自由度設定、バンドルリソース（scripts/references/assets）の使い方、einja固有の規約（einja-プレフィックス、references/ディレクトリ、マネージドセクション）を含む。スクリプトツール（init_skill.py、package_skill.py、quick_validate.py）を提供。
+---
+
+# Skill作成ガイド
+
+## 概要
+
+このSkillは、効果的なSkillを作成するためのガイドを提供します。ユーザーが新しいSkillを作成したい（または既存のSkillを更新したい）場合に使用してください。
+
+## Skillとは
+
+Skillは、Claudeの能力を専門知識、ワークフロー、ツール統合によって拡張する、モジュール化された自己完結型パッケージです。Skillを「特定のドメインやタスクのためのオンボーディングガイド」として考えてください。汎用エージェントであるClaudeを、どのモデルも完全には持ち得ない手続き的知識を備えた専門エージェントに変換します。
+
+### Skillが提供するもの
+
+1. **専門化されたワークフロー** - 特定ドメインのための複数ステップの手順
+2. **ツール統合** - 特定のファイル形式やAPIを扱うための指示
+3. **ドメイン専門知識** - 会社固有の知識、スキーマ、ビジネスロジック
+4. **バンドルリソース** - 複雑で反復的なタスクのためのスクリプト、参照資料、アセット
+
+## 基本原則
+
+### 簡潔さが鍵
+
+コンテキストウィンドウは公共財です。Skillは、Claudeが必要とする他のすべてのもの（システムプロンプト、会話履歴、他のSkillのメタデータ、実際のユーザーリクエスト）とコンテキストウィンドウを共有します。
+
+**デフォルトの前提: Claudeはすでに非常に賢い。** Claudeがまだ持っていないコンテキストのみを追加してください。各情報について「Claudeは本当にこの説明が必要か？」「この段落はトークンコストに見合うか？」と問いかけてください。
+
+冗長な説明よりも簡潔な例を優先してください。
+
+### 適切な自由度の設定
+
+タスクの脆弱性と可変性に応じて、具体性のレベルを合わせます：
+
+**高自由度（テキストベースの指示）**: 複数のアプローチが有効な場合、決定がコンテキストに依存する場合、またはヒューリスティックがアプローチを導く場合に使用します。
+
+**中自由度（疑似コードまたはパラメータ付きスクリプト）**: 推奨パターンが存在する場合、ある程度のバリエーションが許容される場合、または設定が動作に影響する場合に使用します。
+
+**低自由度（特定のスクリプト、少数のパラメータ）**: 操作が脆弱でエラーが起きやすい場合、一貫性が重要な場合、または特定のシーケンスに従う必要がある場合に使用します。
+
+Claudeがパスを探索していると考えてください：崖のある狭い橋には特定のガードレールが必要（低自由度）ですが、開けた野原では多くのルートが許されます（高自由度）。
+
+### Skillの構造
+
+すべてのSkillは、必須のSKILL.mdファイルとオプションのバンドルリソースで構成されます：
+
+```
+skill-name/
+├── SKILL.md (必須)
+│   ├── YAMLフロントマターメタデータ (必須)
+│   │   ├── name: (必須)
+│   │   ├── description: (必須)
+│   │   └── compatibility: (オプション、めったに不要)
+│   └── Markdown指示 (必須)
+└── バンドルリソース (オプション)
+    ├── scripts/          - 実行可能コード（Python/Bash等）
+    ├── references/       - 必要に応じてコンテキストに読み込むドキュメント
+    └── assets/           - 出力で使用されるファイル（テンプレート、アイコン、フォント等）
+```
+
+#### SKILL.md（必須）
+
+すべてのSKILL.mdは以下で構成されます：
+
+- **フロントマター**（YAML）: `name`と`description`フィールド（必須）を含み、`license`、`metadata`、`compatibility`などのオプションフィールドもあります。Claudeがいつスキルをトリガーするかを判断するため、何のスキルか、いつ使用すべきかについて明確かつ包括的に記述してください。`compatibility`フィールドは環境要件（対象プロダクト、システムパッケージ等）を記載しますが、ほとんどのスキルには不要です。
+- **本文**（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またはreferencesファイルのどちらか一方に存在すべきで、両方には存在すべきではありません。詳細情報にはreferencesファイルを優先してください。SKILL.mdには必須の手続き的指示とワークフローガイダンスのみを保持し、詳細な参照資料、スキーマ、例はreferencesファイルに移動してください。
+
+##### assets/
+
+コンテキストに読み込まれることを意図せず、Claudeが生成する出力で使用されるファイル。
+
+- **含めるべき場合**: 最終出力で使用されるファイルが必要な場合
+- **例**: ブランドアセットのための `assets/logo.png`、PowerPointテンプレートのための `assets/slides.pptx`、HTML/Reactボイラープレートのための `assets/frontend-template/`、タイポグラフィのための `assets/font.ttf`
+- **使用例**: テンプレート、画像、アイコン、ボイラープレートコード、フォント、コピーまたは修正されるサンプルドキュメント
+- **利点**: 出力リソースとドキュメントを分離し、Claudeがコンテキストに読み込まずにファイルを使用可能
+
+#### Skillに含めるべきでないもの
+
+Skillには、その機能を直接サポートする必須ファイルのみを含めるべきです。以下のような余分なドキュメントや補助ファイルは作成しないでください：
+
+- README.md
+- INSTALLATION_GUIDE.md
+- QUICK_REFERENCE.md
+- CHANGELOG.md
+- その他
+
+Skillには、AIエージェントが手元のジョブを実行するために必要な情報のみを含めるべきです。作成プロセス、セットアップおよびテスト手順、ユーザー向けドキュメントなどの補助的なコンテキストを含めるべきではありません。追加のドキュメントファイルを作成すると、混乱を招きます。
+
+### 段階的開示設計原則
+
+Skillは、コンテキストを効率的に管理するために3レベルの読み込みシステムを使用します：
+
+1. **メタデータ（name + description）** - 常にコンテキスト内（~100語）
+2. **SKILL.md本文** - スキルトリガー時（<5k語）
+3. **バンドルリソース** - Claudeが必要に応じて（無制限。スクリプトはコンテキストウィンドウに読み込まずに実行可能）
+
+#### 段階的開示パターン
+
+SKILL.md本文は要点に絞り、500行以内に抑えてコンテキストの肥大化を最小限に抑えます。この制限に近づいたらコンテンツを別ファイルに分割します。コンテンツを他のファイルに分割する際は、SKILL.mdから参照し、いつ読むべきかを明確に記述することが非常に重要です。これにより、スキルの読者がそれらが存在し、いつ使用すべきかを知ることができます。
+
+**重要な原則**: Skillが複数のバリエーション、フレームワーク、オプションをサポートする場合、SKILL.mdにはコアワークフローと選択ガイダンスのみを保持します。バリエーション固有の詳細（パターン、例、設定）は別のreferenceファイルに移動します。
+
+**パターン1: リファレンス付きの高レベルガイド**
+
+```markdown
+# PDF Processing
+
+## クイックスタート
+
+pdfplumberでテキスト抽出:
+[コード例]
+
+## 高度な機能
+
+- **フォーム入力**: 完全ガイドは [FORMS.md](FORMS.md) を参照
+- **APIリファレンス**: すべてのメソッドは [REFERENCE.md](REFERENCE.md) を参照
+- **例**: 一般的なパターンは [EXAMPLES.md](EXAMPLES.md) を参照
+```
+
+ClaudeはFORMS.md、REFERENCE.md、またはEXAMPLES.mdを必要な場合のみ読み込みます。
+
+**パターン2: ドメイン固有の構成**
+
+複数のドメインを持つSkillの場合、無関係なコンテキストの読み込みを避けるためにドメインごとにコンテンツを整理します：
+
+```
+bigquery-skill/
+├── SKILL.md (概要とナビゲーション)
+└── references/
+    ├── finance.md (収益、請求メトリクス)
+    ├── sales.md (商談、パイプライン)
+    ├── product.md (API使用、機能)
+    └── marketing.md (キャンペーン、アトリビューション)
+```
+
+ユーザーが販売メトリクスについて質問すると、Claudeはsales.mdのみを読みます。
+
+同様に、複数のフレームワークやバリエーションをサポートするスキルの場合、バリエーションごとに整理します：
+
+```
+cloud-deploy/
+├── SKILL.md (ワークフロー + プロバイダー選択)
+└── references/
+    ├── aws.md (AWSデプロイパターン)
+    ├── gcp.md (GCPデプロイパターン)
+    └── azure.md (Azureデプロイパターン)
+```
+
+ユーザーがAWSを選択すると、Claudeはaws.mdのみを読みます。
+
+**パターン3: 条件付き詳細**
+
+基本コンテンツを表示し、高度なコンテンツにリンク：
+
+```markdown
+# DOCX Processing
+
+## ドキュメント作成
+
+新しいドキュメントにはdocx-jsを使用。[DOCX-JS.md](DOCX-JS.md) を参照。
+
+## ドキュメント編集
+
+簡単な編集には、XMLを直接修正。
+
+**変更履歴の場合**: [REDLINING.md](REDLINING.md) を参照
+**OOXMLの詳細**: [OOXML.md](OOXML.md) を参照
+```
+
+Claudeは、ユーザーがそれらの機能を必要とする場合のみREDLINING.mdまたはOOXML.mdを読みます。
+
+**重要なガイドライン**:
+
+- **深くネストされた参照を避ける** - 参照はSKILL.mdから1レベル深く保つ。すべてのreferencesファイルはSKILL.mdから直接リンクする。
+- **長いreferencesファイルの構造化** - 100行を超えるファイルの場合、プレビュー時にClaudeが全体のスコープを見ることができるよう、冒頭に目次を含める。
+
+## Skill作成プロセス
+
+Skill作成には以下のステップが含まれます：
+
+1. 具体例でスキルを理解する
+2. 再利用可能なスキルコンテンツを計画する（scripts、reference、assets）
+3. スキルを初期化する（init_skill.py実行）
+4. スキルを編集する（リソースを実装し、SKILL.mdを記述）
+5. スキルをパッケージ化する（package_skill.py実行）
+6. 実際の使用に基づいて反復改善する
+
+これらのステップに順番に従ってください。適用されない明確な理由がある場合のみスキップしてください。
+
+### ステップ1: 具体例でスキルを理解する
+
+スキルの使用パターンがすでに明確に理解されている場合のみ、このステップをスキップしてください。既存のスキルで作業している場合でも有益です。
+
+効果的なスキルを作成するには、スキルがどのように使用されるかの具体例を明確に理解します。この理解は、直接のユーザー例またはユーザーフィードバックで検証された生成例のいずれかから得られます。
+
+例えば、image-editorスキルを構築する場合、関連する質問には以下が含まれます：
+
+- 「image-editorスキルはどのような機能をサポートすべきですか？編集、回転、その他？」
+- 「このスキルがどのように使用されるかの例を教えてください」
+- 「『この画像から赤目を除去』や『この画像を回転』のようなユーザーのリクエストを想像できます。このスキルが使用される他の方法はありますか？」
+- 「このスキルをトリガーするためにユーザーは何と言うでしょうか？」
+
+ユーザーを圧倒しないように、1つのメッセージで多くの質問をすることを避けてください。最も重要な質問から始め、効果を高めるために必要に応じてフォローアップします。
+
+スキルがサポートすべき機能について明確な感覚が得られたら、このステップを終了します。
+
+### ステップ2: 再利用可能なスキルコンテンツの計画
+
+具体例を効果的なスキルに変えるために、各例を以下のように分析します：
+
+1. ゼロから例を実行する方法を検討
+2. これらのワークフローを繰り返し実行する際に役立つscripts、reference、assetsを特定
+
+例：「このPDFを回転してください」のようなクエリを処理するために`pdf-editor`スキルを構築する場合、分析は以下を示します：
+
+1. PDFを回転するには毎回同じコードを書き直す必要がある
+2. スキルに保存する `scripts/rotate_pdf.py` スクリプトが役立つ
+
+例：「Todoアプリを作って」や「歩数を追跡するダッシュボードを作って」のようなクエリのために`frontend-webapp-builder`スキルを設計する場合、分析は以下を示します：
+
+1. フロントエンドWebアプリを書くには毎回同じボイラープレートHTML/Reactが必要
+2. ボイラープレートHTML/Reactプロジェクトファイルを含む `assets/hello-world/` テンプレートがスキルに保存すると役立つ
+
+例：「今日何人のユーザーがログインしましたか？」のようなクエリを処理するために`big-query`スキルを構築する場合、分析は以下を示します：
+
+1. BigQueryをクエリするには毎回テーブルスキーマとリレーションシップを再発見する必要がある
+2. テーブルスキーマをドキュメント化する `references/schema.md` ファイルがスキルに保存すると役立つ
+
+スキルのコンテンツを確立するために、各具体例を分析して、含めるべき再利用可能なリソースのリストを作成します：scripts、reference、assets。
+
+### ステップ3: スキルの初期化
+
+この時点で、実際にスキルを作成します。
+
+開発中のスキルがすでに存在し、反復またはパッケージ化が必要な場合のみ、このステップをスキップしてください。その場合は次のステップに進んでください。
+
+新しいスキルをゼロから作成する場合は、常に `init_skill.py` スクリプトを実行してください。このスクリプトは、スキルが必要とするすべてを自動的に含む新しいテンプレートスキルディレクトリを便利に生成し、スキル作成プロセスをはるかに効率的かつ信頼性の高いものにします。
+
+使用法：
+
+```bash
+scripts/init_skill.py <skill-name> --path <output-directory>
+```
+
+スクリプトは：
+
+- 指定されたパスにスキルディレクトリを作成
+- 適切なフロントマターとTODOプレースホルダーを持つSKILL.mdテンプレートを生成
+- 例のリソースディレクトリを作成：`scripts/`、`references/`、`assets/`
+- カスタマイズまたは削除可能な各ディレクトリに例のファイルを追加
+
+初期化後、生成されたSKILL.mdと例のファイルを必要に応じてカスタマイズまたは削除します。
+
+### ステップ4: スキルの編集
+
+（新しく生成された、または既存の）スキルを編集する際、スキルは別のClaudeインスタンスが使用するために作成されていることを忘れないでください。Claudeにとって有益で自明でない情報を含めてください。別のClaudeインスタンスがこれらのタスクをより効果的に実行するのに役立つ手続き的知識、ドメイン固有の詳細、または再利用可能なアセットを検討してください。
+
+#### 実証済みデザインパターンを学ぶ
+
+スキルのニーズに基づいて、これらの有用なガイドを参照してください：
+
+- **複数ステップのプロセス**: シーケンシャルワークフローと条件付きロジックについては references/workflows.md を参照
+- **特定の出力形式または品質基準**: テンプレートと例のパターンについては references/output-patterns.md を参照
+
+これらのファイルには、効果的なスキル設計のための確立されたベストプラクティスが含まれています。
+
+#### 再利用可能なスキルコンテンツから始める
+
+実装を開始するには、上記で特定した再利用可能なリソースから始めます：`scripts/`、`references/`、`assets/` ファイル。このステップにはユーザー入力が必要な場合があります。例えば、`brand-guidelines`スキルを実装する場合、ユーザーは`assets/`に保存するブランドアセットやテンプレート、または`references/`に保存するドキュメントを提供する必要があります。
+
+追加されたスクリプトは、バグがないこと、出力が期待どおりであることを確認するために実際に実行してテストする必要があります。多くの類似したスクリプトがある場合、すべてが機能することを確信しながら完了までの時間とのバランスを取るために、代表的なサンプルのみをテストする必要があります。
+
+スキルに必要のない例のファイルとディレクトリは削除する必要があります。初期化スクリプトは構造を示すために`scripts/`、`references/`、`assets/`に例のファイルを作成しますが、ほとんどのスキルはそれらすべてを必要としません。
+
+#### SKILL.mdの更新
+
+**記述ガイドライン**: 常に命令形/不定詞形を使用してください。
+
+##### フロントマター
+
+`name`と`description`を持つYAMLフロントマターを記述します：
+
+- `name`: スキル名
+- `description`: これはスキルの主要なトリガーメカニズムであり、Claudeがいつスキルを使用するかを理解するのに役立ちます。
+  - Skillが何をするか、使用するための特定のトリガー/コンテキストの両方を含めます。
+  - すべての「使用すべき場合」情報をここに含めてください - 本文ではありません。本文はトリガー後にのみ読み込まれるため、本文の「このスキルを使用すべき場合」セクションはClaudeにとって役立ちません。
+  - `docx`スキルの例の説明: "変更履歴、コメント、書式保持、テキスト抽出をサポートする包括的なドキュメント作成、編集、分析。Claudeが専門的なドキュメント（.docxファイル）で作業する必要がある場合に使用：(1) 新しいドキュメントの作成、(2) コンテンツの変更または編集、(3) 変更履歴の操作、(4) コメントの追加、またはその他のドキュメントタスク"
+
+YAMLフロントマターに他のフィールドを含めないでください。
+
+##### 本文
+
+スキルとそのバンドルリソースを使用するための指示を記述します。
+
+##### 言語の考慮事項
+
+スキルの言語をプロジェクトの主要言語に合わせます：
+
+1. プロジェクト設定で言語設定を確認：`CLAUDE.md`、`.kiro/steering/`、または `spec.json` ファイル
+2. SKILL.md本文はプロジェクトの主要言語で記述
+3. フロントマター`description`：主要な説明はプロジェクトの主要言語を使用しますが、チームが使用する他の言語で重要なトリガーフレーズを含めます（バイリンガル説明はトリガーの失敗を防ぎます）
+4. referenceファイルと出力テンプレートもプロジェクトの言語に従うべき
+5. 技術用語（API名、ツール名、ファイル形式）はプロジェクト言語に関係なく英語のままで構いません
+
+### ステップ5: スキルのパッケージ化
+
+スキルの開発が完了したら、ユーザーと共有される配布可能な.skillファイルにパッケージ化する必要があります。パッケージ化プロセスは、すべての要件を満たしていることを確認するために、まずスキルを自動的に検証します：
+
+```bash
+scripts/package_skill.py <path/to/skill-folder>
+```
+
+オプションの出力ディレクトリ指定：
+
+```bash
+scripts/package_skill.py <path/to/skill-folder> ./dist
+```
+
+パッケージ化スクリプトは：
+
+1. **検証**：スキルを自動的に検証し、以下を確認：
+
+   - YAMLフロントマター形式と必須フィールド
+   - スキル命名規則とディレクトリ構造
+   - 説明の完全性と品質
+   - ファイル構成とリソース参照
+
+2. **パッケージ化**：検証が通過した場合、スキル名にちなんだ.skillファイル（例：`my-skill.skill`）を作成し、すべてのファイルを含み、配布のための適切なディレクトリ構造を維持します。.skillファイルは.skill拡張子を持つzipファイルです。
+
+検証が失敗した場合、スクリプトはエラーを報告し、パッケージを作成せずに終了します。検証エラーを修正し、パッケージ化コマンドを再度実行します。
+
+### ステップ6: 反復
+
+スキルをテストした後、ユーザーは改善を要求する場合があります。多くの場合、これはスキルを使用した直後、スキルがどのように機能したかの新鮮なコンテキストで発生します。
+
+**反復ワークフロー**:
+
+1. 実際のタスクでスキルを使用
+2. 苦労や非効率性に気づく
+3. SKILL.mdまたはバンドルリソースをどのように更新すべきかを特定
+4. 変更を実装し、再度テスト
+
+## einja固有の注意事項
+
+### 命名規約
+
+einjaプロジェクトでは、Skillには`einja-`プレフィックスを付けることを推奨します。
+
+例：`einja-coding-standards`、`einja-component-design`、`einja-api-development`
+
+### ディレクトリ構造
+
+einjaでは`references/`（複数形）を使用します。公式仕様に準拠しています。
+
+```
+einja-skill-name/
+├── SKILL.md
+├── scripts/          # オプション
+├── references/       # 複数形（公式仕様準拠）
+└── assets/           # オプション
+```
+
+### マネージドセクション
+
+einjaの一部のドキュメントは、CLIツールによって自動更新される「マネージドセクション」を使用します。Skillでこれらのパターンを使用する場合：
+
+**マネージドセクション**（CLIツールによる上書き）:
+```markdown
+<!-- @einja:managed:start -->
+この内容は`einja sync`で上書きされる
+<!-- @einja:managed:end -->
+```
+
+**シードセクション**（プロジェクト固有の追記）:
+```markdown
+<!-- @einja:seed:start id="unique-id" -->
+プロジェクト固有の内容をここに追記
+<!-- @einja:seed:end -->
+```
+
+### ビルドシステム連携
+
+einja management templateでは、`.claude/skills/einja-*/` 内のファイルはビルド時に `presets/default/.claude/skills/einja-*/` に自動的にコピーされます。
+
+**重要**: `presets/default/` 内のファイルは直接編集しないでください。ビルド時に上書きされます。
+
+### サブエージェント出力形式との連携
+
+einjaでは、サブエージェントの出力形式が `einja-output-format` Skillで定義されています。サブエージェント用のSkillを作成する場合、この形式テンプレートを参照してください。
+
+詳細は `.claude/skills/einja-output-format/SKILL.md` を参照。
+
+## 関連ドキュメント
+
+- [einja-output-format](../einja-output-format/SKILL.md) - サブエージェント出力形式
+- [einja-coding-standards](../einja-coding-standards/SKILL.md) - コーディング規約の例
+- [einja-component-design](../einja-component-design/SKILL.md) - コンポーネント設計の例