Eidou Usage

Eidou Semantic Compose (Agent Entrypoint)

Agent entrypoint: this file (SKILL.md).

In-repo (dev): /.opencode/skill/eidou-usage-skill/SKILL.md Installed (Linux/macOS): ~/.config/opencode/skill/eidou-usage/SKILL.md Installed (Windows): %APPDATA%\opencode\skill\eidou-usage\SKILL.md

Use this skill at L1: provide semantic IntentSpec JSON and let compose.py generate valid EUIP.

Setup & Usage

Detect your script root first, then call compose/validate from there.

macOS / Linux (Bash/Zsh)

# Set path
export SKILL_DIR="packages/eidou-usage-skill/scripts"                       # In-repo
# export SKILL_DIR="$HOME/.config/opencode/skill/eidou-usage/scripts"       # Installed

# Run
python3 "$SKILL_DIR/compose.py" --input intent.json

Windows (PowerShell)

# Set path
$env:SKILL_DIR = "packages\eidou-usage-skill\scripts"                                # In-repo
# $env:SKILL_DIR = "$env:APPDATA\opencode\skill\eidou-usage\scripts"                 # Installed

# Run
python "$env:SKILL_DIR\compose.py" --input intent.json

Core Rules

• Primary tool: compose.py
• Validation gate: validate.py
• Output must satisfy projection -> field -> content and pass validate.py.

Reserved Close Action

• Use _eidou_sys_close for buttons that should close the projection.
• Compose normalizes explicit close intents in action rows:
  • action: "close" -> _eidou_sys_close
  • action: "eidou:close" -> _eidou_sys_close
  • label: "Close" with missing/empty action -> _eidou_sys_close
• Non-close custom actions are preserved as provided.

CLI Contract

# stdin -> stdout
echo '{"pattern":"message","title":"Hi","message":"Yo"}' | \
  python3 $SKILL_DIR/compose.py

# file input / file output
python3 $SKILL_DIR/compose.py --input intent.json --output ui.json

# validate-only dry run
python3 $SKILL_DIR/compose.py --input intent.json --validate-only

# stdin -> stdout
'{"pattern":"message","title":"Hi","message":"Yo"}' |
  python "$env:SKILL_DIR\compose.py"

# file input / file output
python "$env:SKILL_DIR\compose.py" --input intent.json --output ui.json

# validate-only dry run
python "$env:SKILL_DIR\compose.py" --input intent.json --validate-only

Exit Codes

• 0: success
• 1: IntentSpec validation error
• 2: pattern not found
• 3: build error
• 4: EUIP validation error

Error Format (stderr JSON)

{"error":"PATTERN_NOT_FOUND","message":"Pattern 'x' not found","stage":"pattern_selection"}

stage values: input_parse, spec_validation, pattern_selection, build, euip_validation.

IntentSpec Basics

Common fields:

• pattern (required)
• title (required)
• description (optional)
• size (optional; width-class presets: compact, standard, wide; ratio presets: dashboard, card, widescreen, portrait, square; protocol presets: auto, sm, md, lg, xl, full; object: {"width":1024,"height":"auto"}; ratio object: {"ratio":"16:9","width":960,"maxWidth":1200,"base":"lg"})
• theme (optional projection theme override)

Pattern-specific fields are below.

Pattern Catalog

Profile avatar behavior: profile always emits an avatar atom. avatar may be an object ({ "src": "...", ... }) or a string URL shorthand. Compose derives a 1-2 character fallback from name whenever avatar.fallback is missing and sets alt to <name> avatar when not provided.

Default sizing note: media_gallery defaults to a ratio size (16:9, width 1024, maxWidth 1200) to keep image-heavy content stable without oversized auto windows. Compose layouts default to fit-content style hybrid sizing ({"width":...,"height":"auto"}) to avoid wasted vertical whitespace.

Compose Pattern (Build Your Own)

Use "pattern": "compose" to assemble custom UIs from building blocks. Each block in body[] is a { "use": "<block_name>", ...params } directive.

{
  "pattern": "compose",
  "title": "Server Dashboard",
  "layout": "sidebar",
  "size": "dashboard",
  "body": [
    { "slot": "main", "use": "chart_panel", "variant": "line", "data": [{"month": "Jan", "revenue": 4200}] },
    { "slot": "side", "use": "metric_card", "label": "CPU", "value": "73%" },
    { "slot": "side", "use": "metric_card", "label": "Mem", "value": "2.1GB" }
  ]
}

Layout Presets

Pick a layout to control how blocks are arranged spatially. Assign blocks to named slots. Multiple blocks in the same slot stack vertically. If no slot is specified, blocks go to the first slot of the layout.

Use explicit size (for example "dashboard") when you want a semantic ratio preset instead of fit-content defaults.

Layout ASCII Diagrams

sidebar:

+------------------+--------+
|      main        |  side  |
+------------------+--------+

Note: If main contains a single chart_panel, it is vertically centered in the available height. Multi-block content (profiles, docs) stays top-aligned.

bento:

+------------------+--------+
|                  | slot-b |
|     slot-a       +--------+
|                  | slot-c |
+------------------+--------+

dashboard:

+---------------------------+
| metrics  metrics  metrics |
+---------------------------+
|          main             |
+---------------------------+
|         footer            |
+---------------------------+

Size Presets

Control window dimensions with semantic size names. Explicit size always overrides the layout's fit-content default.

Most patterns default to a width-class preset (fit-content height). Use ratio presets only for media/visual compositions where aspect stability matters. sm/md/lg/xl are fixed pixel protocol presets (both axes fixed) and often less ideal for content-heavy windows.

Width-class presets (fixed width, height fits content):

For 1024-wide content, use explicit {"width":1024,"height":"auto"} or compose layout defaults (sidebar/split/dashboard already provide this).

Ratio presets (fixed aspect ratio canvas):

You can also use raw sizes: auto, sm, md, lg, xl, full, hybrid objects ({"width":1024,"height":"auto"}), or ratio objects.

Molecules (Small Functional Units)

Organisms (Functional Sections)

Recipes (Suggested Combos)

• Dashboard: layout: "dashboard" with metrics_row in metrics + chart_panel in main
• Sidebar Analysis: layout: "sidebar" with chart_panel in main + metric_cards in side
• Comparison: layout: "split" with chart_panel in left + chart_panel in right
• Bento Overview: layout: "bento" with main chart in slot-a + metrics in slot-b/slot-c
• KPI Grid: layout: "grid-2x2" with metric_card in each slot
• Hero Feature: layout: "hero" with chart_panel in hero + text_block in content
• Simple Stack: no layout (default) with text_block + action_row
• Form + Preview: form_section + markdown_block (stack layout)

Compose One-Liners

{"pattern":"compose","title":"Quick","body":[{"use":"text_block","content":"Hello"},{"use":"action_row","actions":[{"label":"OK","action":"ok"}]}]}

{"pattern":"compose","title":"Dashboard","layout":"sidebar","size":"dashboard","body":[{"slot":"main","use":"chart_panel","variant":"pie","data":[{"cat":"A","val":60},{"cat":"B","val":40}]},{"slot":"side","use":"metric_card","label":"Total","value":"100"}]}

{"pattern":"compose","title":"KPIs","layout":"grid-2x2","size":"square","body":[{"slot":"slot-a","use":"metric_card","label":"CPU","value":"73%"},{"slot":"slot-b","use":"metric_card","label":"RAM","value":"2.1GB"},{"slot":"slot-c","use":"metric_card","label":"Disk","value":"45%"},{"slot":"slot-d","use":"metric_card","label":"Net","value":"120Mbps"}]}

Semantic Field Type Mapping

When building form/settings controls:

• text, email, password, number, textarea -> input
• select -> select
• toggle -> switch
• checkbox -> checkbox
• radio -> radiogroup
• readonly -> text
• hidden -> omitted
• unknown type -> fallback to text input

Minimal Examples

{
  "pattern": "form",
  "title": "Create Contact",
  "fields": [
    {"name": "name", "label": "Name", "type": "text"},
    {"name": "email", "label": "Email", "type": "email"}
  ],
  "actions": [{"label": "Save", "action": "submit", "variant": "primary"}]
}

One-line skeletons for quick authoring:

• message: {"pattern":"message","title":"Welcome","message":"..."}
• data_table: {"pattern":"data_table","title":"T","columns":[{"key":"x"}],"rows":[{"x":"1"}]}
• confirmation: {"pattern":"confirmation","title":"Delete","warning":"..."}
• status_dashboard: {"pattern":"status_dashboard","title":"Health","metrics":[{"label":"CPU","value":"73%"}]}
• detail_view: {"pattern":"detail_view","title":"Detail","fields":[{"label":"Name","value":"Alice"}]}
• list: {"pattern":"list","title":"Logs","items":[{"primary":"Started"}]}
• settings: {"pattern":"settings","title":"Prefs","groups":[{"title":"General","settings":[{"name":"x","label":"X","type":"toggle"}]}]}
• profile: {"pattern":"profile","title":"Agent","name":"Souta"}
• article: {"pattern":"article","title":"Notes","content":"## Hello"}
• chat: {"pattern":"chat","title":"Session","messages":[{"sender":"S","content":"hi"}]}
• terminal_output: {"pattern":"terminal_output","title":"Build","lines":["$ bun run build"]}
• progress_tracker: {"pattern":"progress_tracker","title":"Pipeline","steps":[{"label":"Build","status":"complete"}]}
• media_gallery: {"pattern":"media_gallery","title":"Shots","items":[{"src":"https://example.com/1.png"}]}
• chart: {"pattern":"chart","title":"Revenue","variant":"line","data":[{"month":"Jan","revenue":4200}]}

Recommended Workflow

# compose then validate
echo '<intent_spec_json>' | \
  python3 $SKILL_DIR/compose.py | \
  python3 $SKILL_DIR/validate.py -

# compose then validate
'<intent_spec_json>' |
  python "$env:SKILL_DIR\compose.py" |
  python "$env:SKILL_DIR\validate.py" -

Use this flow for every generated widget before calling show_widget.

If this skill doc conflicts with schema, schema wins:

• specification/v0_1/json/root.json
• specification/v0_1/json/components.json
• specification/v0_1/json/events.json
• specification/v0_1/json/theme.json

Converted and distributed by TomeVault — claim your Tome and manage your conversions.