Agent Skills

Agent Skills

v0.3: The skills are split into four sub-skills under codex-skills/. Each ships with a SKILL.md, an agents/openai.yaml for OpenAI-style agents/ directories, and a references/ directory of deep-dive docs. The router skill (yororen-ui-user) decides which sub-skill to load for a given task.

This page explains how to install the Yororen UI Agent Skills into your local Codex / OpenAI Codex setup.

These skills are intended for end users who build apps with gpui + yororen_ui. They are not intended for contributing to the yororen-ui library itself — if the agent finds itself editing the library repo, stop and ask for the user's app repo instead.

What you get

Four sub-skills, each with a single responsibility:

Sub-skill	When the agent loads it
yororen-ui-user	Router. Always loaded first; picks the right sub-skill for the user's ask.
yororen-ui-app-core	Scaffolding a new app: main.rs, window setup, the one-call renderer::install, theme JSON, i18n bootstrap, NotificationCenter global, project module layout, Entity<T> state pattern.
yororen-ui-state-inputs	State + inputs + forms + modals + popovers + dropdowns + select + tree + virtual list. Wiring on_change / on_submit / on_pick closures with cx.entity().clone(). Diagnosing typing lag and focus issues.
yororen-ui-recipes	End-to-end working examples copied and adapted from the six demos.

The four skills are modular by intent: the agent loads only what it needs. The router skill (yororen-ui-user) decides, based on the user's ask, which sub-skill to load next (or none, if the ask is unrelated).

Prerequisites

• You have Codex installed and a local Codex home directory (commonly ~/.codex).
• Your Rust app uses Yororen UI as a dependency:

[dependencies]
gpui      = { package = "gpui-ce", version = "0.3" }
yororen_ui = "0.3"

Or from GitHub for reproducibility:

[dependencies]
yororen_ui = { git = "https://github.com/MeowLynxSea/yororen-ui.git", tag = "v0.3.0" }

Install

Option A — copy into Codex home (recommended)

The skills live under codex-skills/ in this repo. Copy the four sub-skill folders into your Codex home:

mkdir -p ~/.codex/skills
cp -R codex-skills/yororen-ui-user           ~/.codex/skills/
cp -R codex-skills/yororen-ui-app-core       ~/.codex/skills/
cp -R codex-skills/yororen-ui-state-inputs   ~/.codex/skills/
cp -R codex-skills/yororen-ui-recipes        ~/.codex/skills/

Resulting layout:

~/.codex/skills/
  yororen-ui-user/
  yororen-ui-app-core/
  yororen-ui-state-inputs/
  yororen-ui-recipes/

Restart Codex (or refresh the skill list if your UI supports it).

Option B — install the OpenAI-style agents/openai.yaml

Each sub-skill also ships an agents/openai.yaml for OpenAI-style agent directories. Drop the four files into your agent config root:

cp codex-skills/yororen-ui-user/agents/openai.yaml           ~/.codex/agents/
cp codex-skills/yororen-ui-app-core/agents/openai.yaml       ~/.codex/agents/
cp codex-skills/yororen-ui-state-inputs/agents/openai.yaml   ~/.codex/agents/
cp codex-skills/yororen-ui-recipes/agents/openai.yaml        ~/.codex/agents/

Each openai.yaml is a four-line manifest declaring the skill's display name, short description, and default prompt. Example (yororen-ui-app-core):

interface:
  display_name: "Yororen UI App Core"
  short_description: "Bootstrap a Yororen UI app"
  default_prompt: "Use $yororen-ui-app-core to bootstrap a gpui app with Yororen UI — the one-call renderer install, theme JSON, i18n bootstrap, NotificationCenter global, project layout, and the Entity<T> state pattern."

The $yororen-ui-X form is the Codex shorthand for explicitly invoking a skill by name. Use it whenever the router does not auto-trigger.

What each sub-skill is for

yororen-ui-user (router)

• Decides which sub-skill to load for the user's ask.
• Enforces the 3-layer split mental model (headless / renderer / theme).
• Enforces the one-call bootstrap (renderer::install(cx, cx.window_appearance())).
• Refuses to edit the library repo; asks for the app repo if the user is contributing to yororen-ui itself.

yororen-ui-app-core

Use when generating or refactoring:

• main.rs + window setup.
• The one-call renderer install + theme JSON.
• The i18n bootstrap (locale_en::install, etc.).
• NotificationCenter global.
• Project module layout (state.rs, *_app.rs, components/).
• Entity<T> global state pattern.

yororen-ui-state-inputs

Use when implementing or fixing:

• Any of the seven text inputs (TextInput, PasswordInput, NumberInput, SearchInput, FilePathInput, KeybindingInput, TextArea).
• Building forms with form + form_field.
• Opening / closing modals, popovers, dropdowns, tooltips, selects, menus.
• Configuring the AnimatedVisibility lifecycle on composites.
• VirtualList with infinite loading.
• Diagnosing typing lag, cursor jumps, focus issues.

yororen-ui-recipes

Use when the user asks for a complete working example:

• A copy-from-the-demos recipe (counter / layers / inputs / gallery / theme switch / XML-DSL pair).
• A screen layout pattern (settings page, dashboard, detail pane).
• Composing a modal + form, virtualized list, or theme switcher from scratch.

How to use

The skills should auto-trigger when the user asks to build an app with Yororen UI / gpui. If they do not, explicitly invoke the router:

• $yororen-ui-user

Or invoke a sub-skill directly when you know which one you want:

• $yororen-ui-app-core
• $yororen-ui-state-inputs
• $yororen-ui-recipes

Example prompts:

• "Use yororen ui to build a counter app with i18n and theme support" → router → app-core for the bootstrap.
• "Build a settings page with a form and a modal editor using yororen ui" → router → state-inputs for the wiring, then recipes for the page layout.
• "My TextInput typing is laggy; fix the state pattern" → router → state-inputs for the sync-loop diagnosis.

Notes about docs

End users typically do not have the repo wiki checked out. The agent should read docs and examples from the yororen_ui dependency source checkout that Cargo already fetched.

Practical approach:

• Run cargo metadata --format-version 1 in the app repo.
• Find the yororen_ui package manifest_path.
• Read docs/examples in that checkout (README.md, the demos under crates/yororen-ui-demos/, and the headless sources under crates/yororen-ui-core/src/headless/).