docs: add architecture diagram to readmes
This commit is contained in:
yaojingang
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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 集合、または反復タスクを説明します。
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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 集合或重复任务。
|
||||
|
||||
Reference in New Issue
Block a user