09 · Skills / Recipes / Ecosystem & Flow Engine

Ninth installment of the architecture deep-dive: the Skill system, Recipes, the Broker / Marketplace layer, multi-agent pipelines, and the Flow Engine. Corresponds to ARCHITECTURE.md §11–§11.5.

§11.1 Skill System (Skills)

11.1.1 SKILL.md Format

Skills are defined by SKILL.md files, stored in workspace/skills/ or workspace/tool_skills/:

markdown

# Skill Name

## Step 1: Input Parsing
**Manager Review**  ← This marker auto-generates the approval flow
...

## Step 2: Execution
...

## Step 3: Verification
...

11.1.2 Skill Tools

python

# src/tools/skill_tools.py
class SkillTools:
    """Entry point for agents to invoke skills."""

# src/utils/skill_watcher_tools.py
class SkillWatcherTools:
    """Skill watchdog — monitors skill changes."""

11.1.3 execute_skill Pseudo-Tool

python

# src/tools/tool_dispatcher.py
def execute_skill_schema() -> dict:
    """OpenAI function schema for execute_skill pseudo-tool.
    
    A framework-level affordance registered on every ToolDispatcher.
    Recipe / flow units expose this schema via tools.whitelist.
    """
    return {
        "type": "function",
        "function": {
            "name": "execute_skill",
            "parameters": {
                "type": "object",
                "properties": {
                    "skill_id": {"type": "string"},
                    "args": {"type": "object"},
                },
                "required": ["skill_id"],
            },
        },
    }

11.1.4 Manager Review Marker

Skill authors mark **Manager Review** in SKILL.md → skill_manager automatically builds the approval flow.

Applies to both tool_client and python_script bindings.

§11.2 Recipe System (Recipes)

11.2.1 Concept

Recipe = single-agent multi-stage graph:

Input Parsing → Planning → Execution → Verification → Synthesis

11.2.2 Node Types

Node Type	Description
`compute`	Pure computation (Python expression)
`llm_call` (native)	Native LLM call (inline system_prompt + tool_whitelist)
`tool_call`	Tool call node
`emit_event`	Blocking event dispatch
`for_each`	Loop (inline body_nodes/body_edges)

11.2.3 Branch Expressions

python

# Edge condition= goes through AST whitelist
# .get() silently evaluates to False → use x['key'] subscript syntax (whitelist allows it)

11.2.4 output_var

python

# config.output_var wraps the schema dict under a single name
# Without it, schema fields spread to the top level → downstream .field access breaks

11.2.5 Capability Approval

Per (recipe, agent) pair:

capabilities.extra_modules → request sandbox permissions
Approval hash → unique per (recipe_id, agent_id)

python

# Auto-approved when installing built-in templates
# bind/SetDefault responses carry caps_declared + needs_approval
# CapabilityApprovalPanel + CapabilityConsentModal live in the workshop UI

11.2.6 Recipe Layout

workspace/manager/recipes/<recipe_id>/
├── manifest.json        # Recipe manifest
├── state_graph.json     # State graph
├── knowledge/           # Knowledge base (AGENTS.md must be here)
├── external_kb/         # External knowledge base
└── output_renderers/    # Custom .vue renderers

Full tutorial: Ecosystem · Recipe.

§11.3 Broker / Marketplace Layer

11.3.1 Architecture Overview

src/broker/
├── hub.py               # BrokerHub: identity + transport + matching + rate limiting + ledger
├── identity.py          # Identity management
├── transport.py         # Transport layer
├── matching.py          # Matching engine
├── rate_limit.py        # Rate limiter
├── ledger.py            # Ledger
├── store.py             # Persistence
├── reputation.py        # Reputation system
├── packaging_cli.py     # Packaging CLI
├── workshop/            # Installable apps
│   └── __init__.py      # rooms + threads + reputation + triggers
├── relay/               # Marketplace distribution
├── relay_client.py      # Relay client
├── sdk/                 # SDK
├── user_profile/        # User profiles
├── guild/               # Guild subsystem
└── ...

11.3.2 Installable App Packages

.broker.zip structure:
├── manifest.json        # Manifest (name, version, author, permissions)
├── cover.png            # Cover image
├── ui/                  # UI assets (HTML/JS/CSS)
├── plugin.py            # Plugin code (runs in the bridge process)
└── triggers.json        # Trigger configuration

11.3.3 Signing & Installation

bash

# Author signing
python main.py broker keygen --name <author>
python main.py broker pack --source <dir> --output app.broker.zip
python main.py broker sign --package app.broker.zip

# User installation
python main.py broker install --package app.broker.zip
# Verification: sha256 + Ed25519 signature + author pubkey match

11.3.4 Marketplace

bash

# View marketplace index
python main.py broker marketplace-index

# Publish
python main.py broker publish --package app.broker.zip

The marketplace index is a stable contract (docs/marketplace-index-schema.md).

11.3.5 Three-Layer Cohesion

Layer	Responsibility	Corresponding Module
Hub	Messages + transaction chain + ledger	`hub.py`, `transport.py`, `ledger.py`
Workshop	Installable artifact management	`workshop/`, `broker_workshop.py`
Relay	Marketplace distribution	`relay/`, `relay_client.py`

11.3.6 Database Migrations

Broker-related migrations: v18–v39, v41+

Version	Description
v18	Broker core tables
v19	broker_workshop
v20	broker_local_package_dir
v21	broker_identity_assets
v22	broker_messages
v23	broker_member_caps
v24	broker_approvals
v28	broker_author_crl
v29	broker_trusted_authors
v30–v32	Broker federation (room/thread/message)
v36	broker_user_consents

11.3.7 REST Endpoints

Route	Prefix	Description
`broker.py`	`/api/broker`	Broker layer (Hub/matching/ledger)
`broker_workshop.py`	`/api/broker_workshop`	Install/manage
`broker_app.py`	`/api/broker_app`	iframe UI (static assets exempt from token)
`broker_assets.py`	`/api/broker_assets`	Static assets
`broker_dev.py`	`/api/broker_dev`	Developer tools

Full tutorial: Ecosystem · Broker.

§11.4 Multi-Agent Pipeline

python

# src/bridge/routes/pipelines.py
# POST /api/pipelines/...

# Custom multi-agent pipelines:
# Orchestrate multi-agent collaboration
# Executed by the custom_pipeline skill (backend-driven)

Operational guide: Pipelines & Broker.

§11.5 Flow Engine

11.5.1 Concept

Flow = multi-agent workflow with the main agent track as the backbone:

Starter → [agent_1 role_A] → [agent_2 role_B] → ... → Summary

11.5.2 FlowEngine

python

# src/flow/engine.py
class FlowEngine:
    """owner-thread + per-role worker-thread concurrent execution.
    
    owner-thread: manages flow lifecycle
    worker-thread: one per role, executes in parallel
    """

11.5.3 Resume from Breakpoints

python

# src/flow/resume.py
def resume_flow(flow_id: str) -> FlowEngine:
    """Rehydrate the engine from DB.
    
    Replays the mutation log + hash verification.
    """

11.5.4 Flow Templates

workspace/manager/flows/<template_id>/
├── template.json        # Template definition
├── layout.json          # Editor layout
├── renderers/           # Custom field renderers .vue
│   └── *.vue
└── docs/                # Design / development docs
    ├── DESIGN.md
    └── DEVELOPMENT.md

11.5.5 Built-in Templates

python

# src/flow/_builtin/<id>/
# install_built_ins() installs at bridge startup
# Built-in templates are read-only (backend forbids save/delete)
# UI splits into "System" / "My" lists

11.5.6 REST Endpoints

Route	Prefix	Description
`flow_templates.py`	`/api/flow-templates`	Template CRUD + custom field renderers
`flows.py`	`/api/flows`	Flow instances (list/get/trace/cancel)
`flow_dev.py`	`/api/flow_dev`	Flow developer tools

11.5.7 Database Migrations

Version	Description
v25	flow_core (Python migration)
v26	flow_trace_index

Full tutorial: Ecosystem · Flow.

§11.6 Guild System

11.6.1 Database Migrations

Version	Description
v20	Guild core
v21	guild_task_type
v27	guild_medal_images
v33	guild_task_federation
v34	guild_medal_federation
v35	guild_ledger_federation
v37	guild_scope_approvals
v38	guild_task_lifecycle
v39	guild_merge_requests
v40	task_edit_history
v42	guild_experience_reports + guild_modification_votes
v43	guild_task_recall_votes
v44	guild_scope_members
v46	guild_task_tags

11.6.2 REST Endpoints

python

# src/bridge/routes/guild.py → /api/guild

Next: 10-Engineering & Appendix →

09 · Skills / Recipes / Ecosystem & Flow Engine ​

§11.1 Skill System (Skills) ​

11.1.1 SKILL.md Format ​

11.1.2 Skill Tools ​

11.1.3 execute_skill Pseudo-Tool ​

11.1.4 Manager Review Marker ​

§11.2 Recipe System (Recipes) ​

11.2.1 Concept ​

11.2.2 Node Types ​

11.2.3 Branch Expressions ​

11.2.4 output_var ​

11.2.5 Capability Approval ​

11.2.6 Recipe Layout ​

§11.3 Broker / Marketplace Layer ​

11.3.1 Architecture Overview ​

11.3.2 Installable App Packages ​

11.3.3 Signing & Installation ​

11.3.4 Marketplace ​

11.3.5 Three-Layer Cohesion ​

11.3.6 Database Migrations ​

11.3.7 REST Endpoints ​

§11.4 Multi-Agent Pipeline ​

§11.5 Flow Engine ​

11.5.1 Concept ​

11.5.2 FlowEngine ​

11.5.3 Resume from Breakpoints ​

11.5.4 Flow Templates ​

11.5.5 Built-in Templates ​

11.5.6 REST Endpoints ​

11.5.7 Database Migrations ​

§11.6 Guild System ​

11.6.1 Database Migrations ​

11.6.2 REST Endpoints ​

09 · Skills / Recipes / Ecosystem & Flow Engine

§11.1 Skill System (Skills)

11.1.1 SKILL.md Format

11.1.2 Skill Tools

11.1.3 execute_skill Pseudo-Tool

11.1.4 Manager Review Marker

§11.2 Recipe System (Recipes)

11.2.1 Concept

11.2.2 Node Types

11.2.3 Branch Expressions

11.2.4 output_var

11.2.5 Capability Approval

11.2.6 Recipe Layout

§11.3 Broker / Marketplace Layer

11.3.1 Architecture Overview

11.3.2 Installable App Packages

11.3.3 Signing & Installation

11.3.4 Marketplace

11.3.5 Three-Layer Cohesion

11.3.6 Database Migrations

11.3.7 REST Endpoints

§11.4 Multi-Agent Pipeline

§11.5 Flow Engine

11.5.1 Concept

11.5.2 FlowEngine

11.5.3 Resume from Breakpoints

11.5.4 Flow Templates

11.5.5 Built-in Templates

11.5.6 REST Endpoints

11.5.7 Database Migrations

§11.6 Guild System

11.6.1 Database Migrations

11.6.2 REST Endpoints