From 88fc339d5fe5ccffdb1b81e6a54eefe5571c1ef5 Mon Sep 17 00:00:00 2001
From: yaojingang <kingboke@gmail.com>
Date: Mon, 6 Apr 2026 10:51:35 +0800
Subject: [PATCH] docs: add architecture diagram to readmes

---
 README.md            | 46 ++++++++++++++++++++++++++++++++++++++++++++
 docs/README.fr-FR.md | 46 ++++++++++++++++++++++++++++++++++++++++++++
 docs/README.ja-JP.md | 46 ++++++++++++++++++++++++++++++++++++++++++++
 docs/README.ru-RU.md | 46 ++++++++++++++++++++++++++++++++++++++++++++
 docs/README.zh-CN.md | 46 ++++++++++++++++++++++++++++++++++++++++++++
 5 files changed, 230 insertions(+)

diff --git a/README.md b/README.md
index 946a955e..473b7d20 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,52 @@ It turns rough workflows, transcripts, prompts, notes, and runbooks into reusabl
 - neutral source metadata plus client-specific adapters
 - governance, promotion, and portability checks built into the default flow
 
+## Architecture
+
+The system is intentionally layered so users can understand it from top to bottom: route first, choose method second, validate third, then package and govern the result.
+
+```mermaid
+flowchart TD
+    A["Inputs<br/>workflows / prompts / transcripts / docs / notes"] --> B["Router<br/>SKILL.md"]
+    B --> C["Method Layer<br/>references/"]
+    B --> D["Authoring Flow<br/>scripts/yao.py"]
+
+    C --> C1["Archetypes"]
+    C --> C2["Gate Selection"]
+    C --> C3["Non-Skill Decision"]
+    C --> C4["Operating Modes"]
+    C --> C5["Governance"]
+    C --> C6["Resource Boundaries"]
+
+    D --> E["Create<br/>init / template"]
+    D --> F["Validate<br/>lint / boundary / governance"]
+    D --> G["Evaluate<br/>trigger / suites / judge / confusion"]
+    D --> H["Promote<br/>promotion policy / candidate registry"]
+    D --> I["Package<br/>neutral source -> target adapters"]
+    D --> J["Report<br/>history / scorecards / context / portability"]
+
+    E --> K["Skill Package"]
+    F --> K
+    G --> L["evals/"]
+    H --> M["reports/"]
+    I --> N["dist/ or target outputs"]
+
+    K --> K1["SKILL.md"]
+    K --> K2["agents/interface.yaml"]
+    K --> K3["manifest.json"]
+    K --> K4["optional references / scripts / evals / reports"]
+
+    L --> M
+```
+
+Read the diagram in five layers:
+
+- **Inputs**: rough operational material becomes the source for a reusable skill package.
+- **Router**: `SKILL.md` stays small and decides boundary, mode, and output contract first.
+- **Method layer**: doctrine files explain whether the request should become a skill and which quality gates it deserves.
+- **Authoring flow**: the unified CLI turns creation, validation, optimization, promotion, reporting, and packaging into one path.
+- **Evidence and outputs**: the result is not only a skill package, but also eval artifacts, governance signals, portability outputs, and iteration history.
+
 ## Quick Start
 
 1. Describe the workflow, prompt set, or repeated task you want to turn into a skill.
diff --git a/docs/README.fr-FR.md b/docs/README.fr-FR.md
index 84fab81a..5f99eeb4 100644
--- a/docs/README.fr-FR.md
+++ b/docs/README.fr-FR.md
@@ -12,6 +12,52 @@ Il transforme des workflows bruts, des transcripts, des prompts, des notes et de
 - des métadonnées sources neutres et des adaptateurs spécifiques au client
 - des contrôles de gouvernance, de promotion et de portabilité intégrés au flux standard
 
+## Architecture
+
+Le système est volontairement organisé par couches afin qu'un nouveau venu puisse le lire de haut en bas : d'abord le routage, ensuite la méthode, puis la validation, et enfin le packaging et la gouvernance.
+
+```mermaid
+flowchart TD
+    A["Entrées<br/>workflows / prompts / transcripts / docs / notes"] --> B["Routeur<br/>SKILL.md"]
+    B --> C["Couche méthode<br/>references/"]
+    B --> D["Flux auteur<br/>scripts/yao.py"]
+
+    C --> C1["Skill Archetype"]
+    C --> C2["Gate Selection"]
+    C --> C3["Non-Skill Decision"]
+    C --> C4["Operating Modes"]
+    C --> C5["Governance"]
+    C --> C6["Resource Boundaries"]
+
+    D --> E["Création<br/>init / template"]
+    D --> F["Validation<br/>lint / boundary / governance"]
+    D --> G["Évaluation<br/>trigger / suites / judge / confusion"]
+    D --> H["Promotion<br/>promotion policy / candidate registry"]
+    D --> I["Packaging<br/>neutral source -> target adapters"]
+    D --> J["Rapports<br/>history / scorecards / context / portability"]
+
+    E --> K["Skill Package"]
+    F --> K
+    G --> L["evals/"]
+    H --> M["reports/"]
+    I --> N["dist/ ou sorties cibles"]
+
+    K --> K1["SKILL.md"]
+    K --> K2["agents/interface.yaml"]
+    K --> K3["manifest.json"]
+    K --> K4["references / scripts / evals / reports optionnels"]
+
+    L --> M
+```
+
+On peut lire ce schéma en cinq couches :
+
+- **Couche d'entrée** : les matériaux opérationnels bruts servent de source au futur skill package.
+- **Couche de routage** : `SKILL.md` reste léger et définit d'abord les frontières, le mode et le contrat de sortie.
+- **Couche méthode** : les documents de doctrine déterminent si la demande mérite d'être skillifiée et quels garde-fous elle doit recevoir.
+- **Couche de flux auteur** : le CLI unifié relie création, validation, optimisation, promotion, reporting et packaging.
+- **Couche preuves et sorties** : le résultat n'est pas seulement un skill package, mais aussi des evals, des signaux de gouvernance, des sorties de portabilité et un historique d'itération.
+
 ## Quick Start
 
 1. Décrivez le workflow, l'ensemble de prompts ou la tâche répétée que vous voulez transformer en skill.
diff --git a/docs/README.ja-JP.md b/docs/README.ja-JP.md
index 45623827..b6f187bb 100644
--- a/docs/README.ja-JP.md
+++ b/docs/README.ja-JP.md
@@ -12,6 +12,52 @@
 - 中立的なソースメタデータとクライアント別アダプタ
 - ガバナンス、昇格判定、portability チェックを標準フローに内蔵
 
+## アーキテクチャ
+
+このシステムは層構造になっており、新しい利用者でも上から順に理解できます。最初に route を決め、次に method を選び、その後に検証し、最後に package と governance を扱います。
+
+```mermaid
+flowchart TD
+    A["入力<br/>workflow / prompt / transcript / docs / notes"] --> B["ルーター<br/>SKILL.md"]
+    B --> C["メソッド層<br/>references/"]
+    B --> D["作者フロー<br/>scripts/yao.py"]
+
+    C --> C1["Skill Archetype"]
+    C --> C2["Gate Selection"]
+    C --> C3["Non-Skill Decision"]
+    C --> C4["Operating Modes"]
+    C --> C5["Governance"]
+    C --> C6["Resource Boundaries"]
+
+    D --> E["作成<br/>init / template"]
+    D --> F["検証<br/>lint / boundary / governance"]
+    D --> G["評価<br/>trigger / suites / judge / confusion"]
+    D --> H["昇格<br/>promotion policy / candidate registry"]
+    D --> I["パッケージ化<br/>neutral source -> target adapters"]
+    D --> J["レポート<br/>history / scorecards / context / portability"]
+
+    E --> K["Skill Package"]
+    F --> K
+    G --> L["evals/"]
+    H --> M["reports/"]
+    I --> N["dist/ または target outputs"]
+
+    K --> K1["SKILL.md"]
+    K --> K2["agents/interface.yaml"]
+    K --> K3["manifest.json"]
+    K --> K4["optional references / scripts / evals / reports"]
+
+    L --> M
+```
+
+この図は 5 つの層として読むとわかりやすいです。
+
+- **入力層**: 断片的な運用資料を skill 化の原材料にします。
+- **ルーター層**: `SKILL.md` は軽量のまま、境界、モード、出力契約を先に決めます。
+- **メソッド層**: method 文書が、skill 化すべきか、どの quality gate が必要かを決めます。
+- **作者フロー層**: 統一 CLI が作成、検証、最適化、昇格、レポート、パッケージ化を一つの流れにします。
+- **証拠と出力層**: 最終成果は skill package だけでなく、eval 結果、governance signal、portability 出力、iteration history も含みます。
+
 ## Quick Start
 
 1. skill 化したい workflow、prompt 集合、または反復タスクを説明します。
diff --git a/docs/README.ru-RU.md b/docs/README.ru-RU.md
index e1636e18..b2ba67fd 100644
--- a/docs/README.ru-RU.md
+++ b/docs/README.ru-RU.md
@@ -12,6 +12,52 @@
 - нейтральными исходными метаданными и клиентскими адаптерами
 - встроенными проверками governance, promotion и portability в стандартном потоке
 
+## Архитектура
+
+Система специально построена слоями, чтобы новый пользователь мог понять ее сверху вниз: сначала routing, затем method, потом validation, а уже после этого packaging и governance.
+
+```mermaid
+flowchart TD
+    A["Входы<br/>workflows / prompts / transcripts / docs / notes"] --> B["Router<br/>SKILL.md"]
+    B --> C["Method layer<br/>references/"]
+    B --> D["Authoring flow<br/>scripts/yao.py"]
+
+    C --> C1["Skill Archetype"]
+    C --> C2["Gate Selection"]
+    C --> C3["Non-Skill Decision"]
+    C --> C4["Operating Modes"]
+    C --> C5["Governance"]
+    C --> C6["Resource Boundaries"]
+
+    D --> E["Создание<br/>init / template"]
+    D --> F["Проверка<br/>lint / boundary / governance"]
+    D --> G["Оценка<br/>trigger / suites / judge / confusion"]
+    D --> H["Промоушен<br/>promotion policy / candidate registry"]
+    D --> I["Упаковка<br/>neutral source -> target adapters"]
+    D --> J["Отчеты<br/>history / scorecards / context / portability"]
+
+    E --> K["Skill Package"]
+    F --> K
+    G --> L["evals/"]
+    H --> M["reports/"]
+    I --> N["dist/ или target outputs"]
+
+    K --> K1["SKILL.md"]
+    K --> K2["agents/interface.yaml"]
+    K --> K3["manifest.json"]
+    K --> K4["optional references / scripts / evals / reports"]
+
+    L --> M
+```
+
+Эту схему удобнее читать как 5 слоев:
+
+- **Слой входов**: разрозненные операционные материалы становятся сырьем для будущего skill package.
+- **Слой routing**: `SKILL.md` остается легким и сначала определяет границы, режим и output contract.
+- **Слой method**: doctrinal docs определяют, стоит ли вообще skill-изировать запрос и какие quality gates ему нужны.
+- **Слой authoring flow**: единый CLI связывает создание, проверку, оптимизацию, promotion, reporting и packaging.
+- **Слой доказательств и выходов**: итогом становится не только skill package, но и eval-артефакты, governance signals, portability outputs и история итераций.
+
 ## Quick Start
 
 1. Опишите workflow, набор prompts или повторяющуюся задачу, которую хотите превратить в skill.
diff --git a/docs/README.zh-CN.md b/docs/README.zh-CN.md
index 929dbd1e..65111bdb 100644
--- a/docs/README.zh-CN.md
+++ b/docs/README.zh-CN.md
@@ -12,6 +12,52 @@
 - 中性的源元数据以及面向不同客户端的适配层
 - 内建的治理、晋升和 portability 检查
 
+## 架构图
+
+这套系统是分层设计的，方便新用户从上到下理解：先路由，再选方法，再做验证，最后再打包和治理。
+
+```mermaid
+flowchart TD
+    A["输入<br/>workflow / prompt / transcript / docs / notes"] --> B["路由入口<br/>SKILL.md"]
+    B --> C["方法层<br/>references/"]
+    B --> D["作者流<br/>scripts/yao.py"]
+
+    C --> C1["Skill Archetype"]
+    C --> C2["Gate Selection"]
+    C --> C3["Non-Skill Decision"]
+    C --> C4["Operating Modes"]
+    C --> C5["Governance"]
+    C --> C6["Resource Boundaries"]
+
+    D --> E["创建<br/>init / template"]
+    D --> F["校验<br/>lint / boundary / governance"]
+    D --> G["评测<br/>trigger / suites / judge / confusion"]
+    D --> H["晋升<br/>promotion policy / candidate registry"]
+    D --> I["打包<br/>neutral source -> target adapters"]
+    D --> J["报告<br/>history / scorecards / context / portability"]
+
+    E --> K["Skill Package"]
+    F --> K
+    G --> L["evals/"]
+    H --> M["reports/"]
+    I --> N["dist/ 或目标导出物"]
+
+    K --> K1["SKILL.md"]
+    K --> K2["agents/interface.yaml"]
+    K --> K3["manifest.json"]
+    K --> K4["可选 references / scripts / evals / reports"]
+
+    L --> M
+```
+
+可以把这张图理解成 5 层：
+
+- **输入层**：把零散的操作材料作为 skill 的原始输入。
+- **路由层**：`SKILL.md` 保持轻量，优先定义边界、模式和输出契约。
+- **方法层**：方法文档决定这件事该不该 skill 化、该上哪些质量门。
+- **作者流层**：统一 CLI 把创建、校验、优化、晋升、报告和打包串成一条路径。
+- **证据与产出层**：最终产出不只是 skill 包，还包括 eval 结果、治理信号、portability 产物和迭代历史。
+
 ## Quick Start
 
 1. 先描述你想沉淀成 skill 的 workflow、prompt 集合或重复任务。