yao-meta-skill/docs/README.ja-JP.md

Yao Meta Skill 日本語紹介

YAO = Yielding AI Outcomes は、「AI の結果を実際の成果として届ける」という意味です。単に prompt テキストを増やすのではなく、再利用可能な AI 資産と実運用の成果を作ることを重視します。

yao-meta-skill は、再利用可能な agent skill を作成・評価・パッケージ化・運用するための、軽量で厳密なシステムです。

粗い workflow、transcript、prompt、notes、runbook を、再利用可能な skill パッケージに変換し、次の性質を持たせます。

• 明確なトリガー面
• 軽量な SKILL.md
• 必要に応じた references、scripts、evals
• 深い authoring の前に、人間味のある短い intent dialogue を行い、intent confidence gate で理解が十分かを判定する。不十分なら 1〜2 個の高レバレッジ質問を追加する
• 深い authoring の前に、GitHub benchmark scan と reference synthesis を静かに実行し、高品質な公開リポジトリと world-class pattern tracks を参照する。実際に衝突や不確実性があるときだけユーザーに明示する
• ユーザー自身の参考例があれば、それも取り込み、文章ではなくパターン・構造・品質基準だけを学ぶ
• 新しい skill ごとに、白背景の簡潔な HTML overview を自動生成
• prompt quality profile により、need model、RTF mapping、complexity、prompt-facing quality checks を reviewer-visible な証拠として残し、SKILL.md を肥大化させない
• 初回作成後に自動で提示される 3 つの高価値な次の iteration direction
• 初回の人間レビューを助ける、コンパクトな HTML review viewer
• 毎回フル promotion flow を通さずに使える軽量 feedback log
• 増分価値をすばやく確認できる with-skill vs baseline 比較レポート
• 会話型 discovery flow として scaffold / production / library / governed を案内する archetype-aware quickstart
• 中立的なソースメタデータとクライアント別アダプタ
• ガバナンス、昇格判定、portability チェックを標準フローに内蔵

アーキテクチャ

Hero 版では、全体の流れは 1 本です。ばらばらの入力を、統制された再利用可能な skill package に変えます。

flowchart LR
    A["入力<br/>workflow / prompt / transcript / docs / notes"] --> B["ルート定義<br/>SKILL.md"]
    B --> C["設計<br/>method + gates"]
    C --> D["実行<br/>create / validate / eval / promote"]
    D --> E["出力<br/>skill package + reports + adapters"]

10 秒で読むならこうです。

• 入力: workflow、prompt、文書、メモなどの粗い素材から始めます。
• ルート定義: まず軽量な SKILL.md で境界と trigger を決めます。
• 設計: 適切な archetype、gate、資源の分割を選びます。
• 実行: 統一 CLI で作成、検証、最適化、昇格を進めます。
• 出力: 最終的に skill package と、評価・ガバナンス・移植性の証拠が残ります。

加重品質ベンチマーク

これはプロジェクトのエンジニアリング品質レビューです。各項目を 0-10 で評価し、重みづけして 100 点満点に換算します。GitHub stars は、エコシステム上の注目度を示すもので、meta-skill の工学的品質を直接示すものではないため、総合点には含めません。

加重スコアの式: sum(score / 10 * weight)。

Meta Skill	方法論 15	文脈規律 10	ツールチェーン 15	Eval/テスト 20	ガバナンス 15	移植性 10	導入/レビュー 5	ローカル信頼性 10	加重スコア
Yao Meta Skill	9.5	8.0	9.5	9.5	9.5	9.0	6.5	9.5	91.5
Anthropic Skill Creator	9.0	6.5	8.5	7.5	4.0	5.0	7.5	5.0	67.5
OpenAI Skill Creator	8.5	9.5	5.0	2.0	3.0	4.0	8.5	4.0	50.5

順位	Meta Skill	スコア	中核ポジション
1	Yao Meta Skill	91.5	工学化、評価化、ガバナンス化、移植性まで含む完全な meta-skill システム。
2	Anthropic Skill Creator	67.5	方法論と反復ループは強いが、ローカル実行信頼性とガバナンス範囲は弱めです。
3	OpenAI Skill Creator	50.5	完全な工学システムというより、簡潔な skill 作成ガイドとして有用です。

適したシナリオ

• チーム再利用、明確な境界、評価ゲート、ガバナンス、移植性、長期保守を重視するなら Yao Meta Skill が向いています。
• 会話優先の作成ループと人間主導の反復を重視するなら Anthropic Skill Creator が向いています。
• 簡潔な skill 作成ガイドと文脈規律の見本が必要なら OpenAI Skill Creator が向いています。
• 実務的な組み合わせとしては、会話的な creator で初稿を作り、その後 yao-meta-skill で harden して team-ready な asset にする、という流れが有効です。

クイックスタート

1. skill 化したい workflow、prompt 集合、または反復タスクを説明します。
2. まず短いが人間味のある intent dialogue で、実際の job、outputs、boundary、constraints、重視する品質基準を明確にします。
3. まず quickstart で意図を澄ませ、その後 benchmark scan と reference synthesis を静かに実行します。意図がまだ曖昧なとき、または設計ルートに本当の衝突があるときだけ、追加確認を明示します。
4. archetype-aware な quickstart か完全な authoring flow を使い、scaffold、production、library、governed のいずれかでパッケージを生成または改善します。
5. 新しく作成した skill には reports/intent-dialogue.md、reports/intent-confidence.md、reports/reference-synthesis.md、reports/artifact-design-profile.md、reports/prompt-quality-profile.md、reports/skill-overview.html、reports/review-viewer.html、reports/iteration-directions.md が付きます。さらに feedback log と baseline compare を使えば、毎回フル promotion flow を回さずに短い改善ループを回せます。

現在の結果

• 現在 make test は通過
• 現在の回帰セットでは trigger eval が 0 false positives / 0 false negatives
• train / dev / holdout の 3 層評価が通過
• 中国語の実利用表現も trigger 評価に追加済みです。例: 做一个 skill、沉淀成可复用能力、优化已有 skill、补 trigger 评测
• openai、claude、generic の packaging contract が通過

現在の強み

最新の加重レビューでは、Yao は 91.5/100 です。強みは、長く使うチーム資産としての skill に必要な領域に集中しています。

• 方法論の深さ 9.5: skill engineering doctrine、archetype、gate selection、non-skill decision、governance、resource boundary が体系化されています。
• ツールチェーン完成度 9.5: 初期化、検証、benchmark scan、description optimization、レポート、昇格判定、パッケージ化、CI、portability checks が一つの運用フローに接続されています。
• Eval / テスト厳密性 9.5: train/dev/holdout、blind holdout、adversarial holdout、judge-backed blind eval、route confusion、drift history、promotion gate を備えています。
• ガバナンス / ライフサイクル 9.5: 重要な skill に owner、lifecycle、review cadence、maturity score、trust boundary、promotion decision、regression history を持たせられます。
• ローカル実行信頼性 9.5: make test、make ci-test、統一 CLI でローカル再現できます。
• 移植性 / 配布 9.0: ソースは中立に保ち、adapter、degradation rule、packaging contract、portability score で環境間の再利用性を担保します。
• 文脈規律 / 精簡性 8.0: エントリポイントは budget 内に保たれていますが、レポート、例、benchmark、証拠資産が増えたため、継続的な制約として追跡しています。
• 導入 / レビュー体験 6.5: quickstart、HTML overview、side-by-side review viewer、feedback log により初回体験は改善しましたが、ここは次に最も伸ばすべき UX 領域です。

全体の方向性は明確です。入口は軽く、評価は厳しく、ガバナンスは見える形にし、初回作成と人間レビューの摩擦をさらに下げていきます。

なぜ Yao なのか

• 軽量: エントリポイントは小さく保たれ、context budget は明示され、追加構造は本当に価値がある場合にだけ導入されます。
• 厳密: trigger 品質は family regression、blind holdout、adversarial holdout、route confusion、judge-backed blind eval、promotion gate で検証されます。
• ガバナンス可能: 重要な skill は lifecycle、maturity expectation、owner、review cadence を持つ保守対象の資産として扱われます。
• 移植可能: ソースメタデータは中立のまま保たれ、adapter、degradation rule、packaging contract が環境間の再利用意味論を保持します。

何をするものか

このプロジェクトは、skill を単発の prompt ではなく、作成・改善・評価・配布できる持続的な能力パッケージとして扱えるようにします。

設計ロジックは次の通りです。

1. ユーザーの依頼の背後にある反復的な仕事を特定する
2. skill の境界を整理し、1 つのパッケージを 1 つの一貫した役割に保つ
3. 本文を長くする前に trigger description を最適化する
4. メインの skill ファイルを小さく保ち、詳細は references や scripts に移す
5. 品質ゲートは必要なときだけ追加する
6. 本当に必要なクライアント向けにだけ互換出力を生成する

なぜ必要か

多くのチームでは、重要な運用知識が chat、個人 prompt、口頭の習慣、未整理の workflow に散在しています。このプロジェクトは、それらの暗黙知を次の形に変換します。

• 発見可能な skill パッケージ
• 再現可能な実行フロー
• 低コンテキストな指示
• 再利用可能なチーム資産
• 配布しやすい互換パッケージ

リポジトリ構成

yao-meta-skill/
├── SKILL.md
├── README.md
├── LICENSE
├── .gitignore
├── agents/
│   └── interface.yaml
├── references/
├── scripts/
└── templates/

主要コンポーネント

SKILL.md

メインの skill エントリです。トリガー面、動作モード、圧縮された workflow、出力契約を定義します。

agents/interface.yaml

中立的なメタデータの単一ソースです。表示情報と互換性情報を保持し、ソースツリーを特定ベンダーのパスに固定しません。

references/

メイン skill ファイルを肥大化させないための長文資料です。設計ルール、評価方法、互換戦略、品質 rubric を含みます。

scripts/

この meta-skill を実用的にする補助スクリプトです。

• trigger_eval.py: trigger description が広すぎるか弱すぎるかを確認する
• context_sizer.py: コンテキスト量を見積もり、初期ロードが大きすぎる場合に警告する
• cross_packager.py: 中立的なソースパッケージからクライアント別出力を生成する

templates/

単純な skill と複雑な skill を始めるためのテンプレートです。

使い方

1. この skill を直接使う

次のようなときに yao-meta-skill を使います。

• 新しい skill を作る
• 既存の skill を改善する
• skill に eval を追加する
• workflow を再利用可能なパッケージにする
• チーム向けに skill を整備する

2. 新しい skill パッケージを生成する

一般的な流れは次の通りです。

1. workflow または能力を説明する
2. trigger フレーズと出力を特定する
3. scaffold、production、library のいずれかを選ぶ
4. パッケージを生成する
5. 必要に応じてサイズチェックと trigger チェックを行う
6. 対象クライアント向けの互換出力を生成する

3. 互換出力を生成する

例:

python3 scripts/cross_packager.py ./yao-meta-skill --platform openai --platform claude --zip
python3 scripts/context_sizer.py ./yao-meta-skill
python3 scripts/trigger_eval.py --description "Create and improve agent skills..." --cases ./cases.json

利点

• prompt ではなく方法論が中心: skill creation を正式な engineering workflow として扱います
• トリガー最適化を前提に設計: description は route confusion、blind holdout、adversarial family、promotion policy で検証されます
• 入口が軽い: SKILL.md は最小限に保ち、references、scripts、evals は必要なときだけ追加します
• ツールチェーンが一貫: 初期化、検証、最適化、レポート、パッケージ化、テストを統一 CLI と CI で回せます
• 資産として運用できる: owner、lifecycle、maturity expectation、review cadence を持つ skill として管理できます
• 移植前提: ソースは中立、互換性は adapter と degradation rule で処理します
• 証拠が豊富: route scorecard、regression history、context budget、portability score、promotion decision が公開アーティファクトとして残ります

最適な対象

このプロジェクトは次のような人や組織に向いています。

• agent builder
• 内部ツールチーム
• prompt engineering から skill engineering に移行したい人
• 再利用可能な skill ライブラリを構築したい組織

ライセンス

MIT。詳細は LICENSE を参照してください。