skill-writer

Skill Writer

スキルの作成と改善には、これを唯一の標準ワークフローとして使用してください。 主な成功条件：作成に着手する前に価値の高い入力をできるだけ多く網羅し、実行時に無駄なトークンをできるだけ減らすことです。

ワークフローの手順を順番に進めてください。現在の手順に必要な参照ファイルだけを読み込みます。 SKILL.md は主要なルーターです。同梱するすべての参照ファイルは references/ の直下に配置し、直接的な「〜するときに開く」理由を添えてここに記載してください。

コアワークフローの参照資料

次の作業が必要なときに開く...	読むファイル
作成、更新、反復、またはリサーチ先行の作業に適した最小限のワークフローを選ぶ	references/mode-selection.md
ファイルを決める前に、適切な最もシンプルな実行形式を選ぶ	references/execution-shapes.md
深さ、簡潔さ、移植性に関する執筆上の制約を適用する	references/design-principles.md
SKILL.md、references/、SPEC.md、補助ファイルのどれに含めるべきかを判断する	references/reference-architecture.md
スキルの保守契約を作成または更新する	references/spec-template.md
履歴やリグレッションなど、シグナルの強い情報源を見つける	references/source-discovery.md
上流のプロンプト、ワークフロー、評価基準、ベンチマーク、ドキュメントをスキルに適応させる	references/source-adaptation.md
網羅性チェックとソースの記録を含む、完全な統合作業を実施する	references/synthesis-path.md
SKILL.md、SPEC.md、補助ファイルを作成または更新する	references/authoring-path.md
トリガー表現と、誤検知・見逃しの動作を改善する	references/description-optimization.md
肯定例、否定例、または修正例をもとに反復する	references/iteration-path.md
将来の改訂に備えて、作業用の例と保留用の例を永続的に保存する	references/iteration-evidence.md
応答テンプレート、スキーマ、または出力契約を選ぶ	references/output-contracts.md
スキルの生成結果または実行時動作に対する評価を追加または更新する	references/skill-evals.md
過密なレイアウト、隠れた参照、その他の構造上の問題を解決する	references/structure-troubleshooting.md
スキルを登録し、最終検証を実行する	references/registration-validation.md

成果物レイアウトの参照資料

次の作業が必要なときに開く...	読むファイル
スキル全体を一貫した単一の SKILL.md に収める	references/layout-inline-skill.md
任意の詳細知識を、用途別に振り分ける参照ファイルに分割する	references/layout-reference-backed-skill.md
決定的な自動化または検証のためのスクリプトを追加する	references/layout-script-backed-workflow.md
明示的な引数を指定して呼び出すことが多いスキルを定義する	references/layout-argument-driven-skill.md
再利用可能なテンプレート、スキーマ、その他の静的アセットを提供する	references/layout-asset-template-skill.md

ワークフローの仕組みに関する参照資料

次の作業が必要なときに開く...	読むファイル
タスクを順序の決まった固定ステップに分割する	references/workflow-prompt-chaining.md
リクエストを分類し、異なる後続パスに振り分ける	references/workflow-routing.md
独立した作業を並列単位や投票に分割する	references/workflow-parallel.md
作業単位を動的に見つけ、ワーカーの出力を調整する	references/workflow-orchestrator-workers.md
作成または実行中に、検証・修正・再検証のチェックを行う	references/workflow-validation-loops.md
リスクの高い操作を実行する前に、計画を検証する	references/workflow-plan-validate-execute.md

Claude Code のリファレンス

次の場合に開く…	読む
Claude 固有のフロントマターや呼び出し制御を使用する	references/claude-frontmatter-invocation.md
Claude の引数フィールドや置換変数を使用する	references/claude-argument-substitutions.md
分離された context: fork で実行されるスキルを構築する	references/claude-subagent-fork.md
Claude のフックを使って決定論的な適用を行うスキルを構築する	references/claude-hook-backed.md
動的なコンテキスト注入に Claude のシェル前処理を使用する	references/claude-dynamic-context.md

プロファイルの例

次の場合に開く…	読む
ドキュメント中心のスキルに求められる深さを確認する	references/example-documentation-skill.md
ワークフロープロセススキルに求められる深さを確認する	references/example-workflow-process-skill.md
優れたルーティングスキルの例を確認する	references/example-router-skill.md
優れたサブエージェントフォークスキルの例を確認する	references/example-subagent-fork-skill.md
優れたフック対応スキルの例を確認する	references/example-hook-backed-skill.md

ステップ 1：対象、パス、形式を決定する

1. 対象の操作（create、update、synthesize、iterate）を決定し、ファイルの配置先を選ぶ前に、ワークスペース内の既存の実例を確認します。
2. 確認した慣例に基づいて、対象となるスキルのルートを選択します。確認後も標準の配置場所が不明な場合は、ファイルを編集する前に、直接的な質問を 1 つします。
3. references/mode-selection.md を読み、必要最小限のワークフローパスを選びます。
4. references/execution-shapes.md を読み、主要な実行形式を選びます。
5. 適切であれば最もシンプルな形式を選びます。より複雑な形式を選ぶ場合は、よりシンプルな形式を選ばなかった理由を記録します。
6. その形式に必要な、アーティファクトのレイアウト、ワークフローの仕組み、プロバイダー固有のリーフファイルだけを読み込みます。
7. ガイダンスを追加する前に、既存のルール、セクション、ファイルのうち、範囲を狭める、置き換える、または削除すべきものを特定します。
8. プロバイダー固有の仕組みを使用する前に、移植性への影響を記録します。

ステップ 2：必要に応じて統合を実行する

references/synthesis-path.md を読みます。

1. 新しいスキル、重要な変更、調査を優先する計画には、このパスを使用します。
2. 関連する情報源を収集し、出所情報とともに評価します。
3. 情報源が乏しい、古い、または曖昧な場合は、references/source-discovery.md を読みます。
4. 上流のプロンプト、ワークフロー、ルーブリック、ベンチマーク、またはドキュメントを適用する場合は、references/source-adaptation.md を読みます。
5. クラスと実行形式の選択を含め、情報源に基づく判断と、カバレッジ／ギャップの状況を明確にします。
6. 選択したクラスや形式に具体的な深みを加える場合に限り、プロファイルの例を読み込みます。
7. スキルがプロバイダー固有の仕組みを使用する場合は、最新のプロバイダー公式ドキュメントを含め、使用上の制約を記録します。
8. 必要なカバレッジを把握するか、ギャップを明示するまでは、作成に進まないでください。

ステップ 3：結果や例をもとに改善する場合は、まず反復を行う

選択したパスに iteration が含まれる場合（たとえば、操作が iterate の場合）は、まず references/iteration-path.md を読みます。

1. 出所情報とともに例を収集し、匿名化します。
2. 例を現在のターン以降も保持する必要がある場合は、references/iteration-evidence.md を読みます。
3. 動作中のスライスとホールドアウトスライスを使って、スキルの動作を確認します。
4. 肯定的な証拠、否定的な証拠、修正の証拠に基づいて改善案を提示します。
5. 具体的な動作の差分を作成に反映します。

選択したパスに iteration が含まれない場合は、このステップをスキップします。

Step 4: スキルの成果物を作成または更新する

references/authoring-path.mdを読みます。

1. トリガーとなる語句を十分に含めた説明を用い、命令形でSKILL.mdを作成または更新します。
2. SKILL.mdは実行時のルーターとして保ち、百科事典にしないでください。
3. セクションやファイルを新規作成する前に、references/authoring-path.mdに記載されている編集前の精密チェックを実行します。
4. 大量の手順を追加したり、新しい参照ファイルを作成したりする前に、references/reference-architecture.mdを読みます。
5. 新しいスキルを作成する場合、またはその契約を大幅に変更する場合は、references/spec-template.mdを使用してSPEC.mdを作成または更新します。
6. 焦点を絞った参照ファイル、スクリプト、アセットは、それぞれに明確な「この場合に開く」という理由があり、既存のファイルを改善するだけでは対応できない場合に限り作成します。
7. バンドルする参照ファイルを追加する場合は、このSKILL.mdにそのファイルへの直接のルーティングエントリを追加します。
8. 説明文よりも、チェックリスト、表、テンプレート、入出力例を優先します。
9. このスキル用に選択された、成果物のレイアウト、ワークフローの仕組み、Claude 固有の要件、出力契約に関する参照のみを適用します。
10. 高度な実行形式では、スキルを完成と判断する前に、必要なルーティング、委任、安全性に関する契約を追加します。
11. 作成または更新するスキルが作成・生成系の場合は、参照ファイルに変換済みの例を含めます。

• 成功するケース
• セキュアで堅牢なケース
• アンチパターンと修正版

12. 作成中のスキルについて、eval、回帰ケース、ベンチマークケース、またはモデル採点による品質チェックが依頼された場合は、references/skill-evals.mdを読みます。
13. スキルの成果物を変更した後は、説明の最適化や検証の前に、references/authoring-path.mdに記載されている変更後の精密チェックを実行します。

Step 5: 説明の品質を最適化する

references/description-optimization.mdを読みます。

1. トリガーすべきクエリと、トリガーすべきでないクエリのセットを検証します。
2. 対象を絞った説明の編集により、誤検知と見逃しを減らします。
3. スキルが特定のプロバイダー専用である場合を除き、プロバイダーを問わない汎用的なトリガー表現を保ちます。

Step 6: 登録と検証

references/registration-validation.mdを読みます。

1. ワークスペースで確認した現在のレイアウトに応じて、リポジトリへの登録手順を適用します。
2. 構造チェックのため、簡易検証を実行します。
3. 完了前に、バリデーターの警告、精密チェックの結果、カバレッジの不足を考慮して確認します。

出力形式

以下を返します。

1. Summary
2. Changes Made
3. Validation Results
4. Open Gaps