日本語 Skill 設計ワークフロー
Overview
このskillは、スピード優先のポン出しを避け、設計根拠付きで日本語skillを作成するための標準フローを提供する。
毎回同じ品質で作るため、手順を固定し、各フェーズで成果物を明示する。
運用原則
- •先に要件と品質基準を固定し、その後に実装する
- •不足情報がある場合は1回で1-3問まで確認する
- •各フェーズ完了時に成果物を短く要約する
- •迷った場合は抽象説明を減らし、具体例と判定基準を増やす
フェーズ1: 要件定義
references/requirements-template.md を読み、次を確定する。
- •何をするskillか
- •いつ使うskillか
- •何をしないskillか
- •想定ユーザ発話（トリガー候補）
- •必要リソース（scripts/references/assets）
成果物:
- •要件メモ（目的、対象、除外範囲、依存）
- •トリガー候補10件以上（肯定/否定を含む）
フェーズ2: トリガー設計
frontmatterの description を先に作る。
description は次を必ず含める。
- •Skillが行うこと
- •Skillを使う条件
- •典型的なユーザ要求語句（3件以上）
- •対象ファイル種別（必要時）
- •使わない条件（1件以上）
推奨:
- •日本語200-400字を目安にする
- •曖昧語を避ける（適宜、いい感じに、必要に応じて、適切に、など）
禁止事項:
- •抽象語だけで終える記述
- •何でも使えるように見える広すぎる記述
フェーズ3: 構造設計
SKILL本文の章立てを先に設計し、本文は後から埋める。
- •
Overview - •ワークフロー判定
- •実行手順（順序付き）
- •品質チェック
- •返答方針
詳細が長い場合は references/ に分割し、SKILL本文から参照する。
フェーズ4: 実装
新規skillは skill-creator/scripts/init_skill.py で初期化する。
SKILL.md と agents/openai.yaml を必ず作成する。
作成時の要点:
- •frontmatterは
nameとdescriptionを必須で設定する - •本文は命令形で具体手順を書く
- •ツール実行コマンドは実行順で記載する
フェーズ5: 品質ゲート
references/quality-gate.md を使ってレビューする。
最低限、以下を満たすまで公開しない。
- •トリガー適合: 想定要求で起動し、無関係要求で起動しにくい
- •実行可能性: 手順だけで再現できる
- •日本語品質: 用語がぶれず、曖昧語が少ない
- •保守性: 長文はreferencesへ分離されている
フェーズ6: 検証
最低限の検証:
bash
uv run --with pyyaml python .system/skill-creator/scripts/quick_validate.py <skill-path>
加えて、手動で以下を確認する。
- •肯定ケース5件以上で想定どおり使える
- •否定ケース5件以上で過剰適用しない
- •曖昧ケース3件以上で期待挙動を定義できる
- •隣接skillとの境界ケース3件以上で誤発火しない
期待挙動は次の3択で定義する。
- •発火して処理する
- •発火せず他skillへ委譲する
- •発火し、短い確認質問を返して判定する
検証結果は references/trigger-test-log.md に追記する。
不明点が残る場合は $agent-consultation-workflow を使い、背景情報とモデル指定付きで外部AI照会して結論を回収する。
フェーズ7: 反復改善
運用中に失敗例を収集し、次を更新する。
- •frontmatterの
description - •本文の判定条件
- •referencesの補助資料
改善時は次を必ず記録する。
- •失敗原因 -> 修正点 -> 再検証結果
- •
descriptionの変更前後差分 - •発火範囲の変化（何が新たに発火/非発火になったか）
返答方針
- •どのフェーズまで完了したかを明示する
- •決定事項と未確定事項を分けて示す
- •追加確認が必要なら短い質問で絞る
- •最終的に「このskillで何が再現可能か」を1段落で要約する