Engi Design

Engi Design is a stateful, interactive Agent Skill that turns visual-design intent into an accepted and validated project-root DESIGN.md.

It guides an Agent through style discovery, selectable visual directions, detailed preview review, point or rectangle annotations, rework, acceptance, and final design-system documentation.

Keyword: $engi-design.

中文说明见 zh/README.md.

Why Engi Design

Visual-design conversations are easy to interrupt, restart, or steer away from earlier decisions. Engi Design keeps the process grounded in durable state instead of relying on conversation history alone.

• derive style and project context before asking questions;
• present at least three selectable visual directions;
• deliver review rounds through a local HTTP page;
• collect element-level and free-rectangle annotations;
• resolve acceptance from both conversation choices and annotation meaning;
• resume unfinished design work safely;
• finish only when the project-root DESIGN.md exists and passes validation.

How It Works

Discover context
  → Review style gallery
  → Review selected design
  → Rework or accept
  → Finalize and validate DESIGN.md

The typical flow is adaptive. If the prompt and project already provide enough style and product context, the Agent proceeds directly to a style gallery. If an unfinished matching design is found in a conversation with no knowledge of that work, the Agent first asks whether to continue it or start a separate design.

Interactive rounds are served from a local address such as http://127.0.0.1:8080. Gallery pages support selection. Expanded design pages support point and rectangle annotations.

Quickstart

Install the Skill, open the project to design, and explicitly request visual-design work:

$engi-design Design a visual direction for this project

You can provide more context up front to skip unnecessary questions:

$engi-design Create a bright, restrained, technology-oriented visual design for this Web admin dashboard

The Agent creates local working state under:

.engifoundry/design/

That directory is added to the target project's .gitignore. It is private working state, does not require the EngiFoundry plugin, and does not create EngiFoundry Packages or task records. The accepted result is written to the project root and should be committed:

DESIGN.md

Installation

Node.js 18 or newer is required. Choose either installation method.

npm

Run outside an engi-design-skill source checkout:

npx --yes engi-design-skill install

GitHub

npm exec --yes --package=github:caoyuan-fire/engi-design-skill -- engi-design install

From a cloned source checkout, run:

npm run skill:install -- --host codex

Target hosts

Without target options, the installer presents the detected hosts for selection. Use explicit targets in non-interactive environments:

npx --yes engi-design-skill install --host codex
npx --yes engi-design-skill install --host codex,claude
npx --yes engi-design-skill install --all
npx --yes engi-design-skill install --target /custom/skills

Default paths:

Codex     ~/.codex/skills/engi-design
Claude    ~/.claude/skills/engi-design
Kimi Code ~/.kimi/skills/engi-design

Manage an installation

npx --yes engi-design-skill check --host codex
npx --yes engi-design-skill update --host codex
npx --yes engi-design-skill uninstall --host codex

Add --dry-run to preview changes. Replacing an unmanaged installation requires --force.

Optional design.md CLI

When designmd or design.md is available locally, Engi Design prefers its specification and linter for the final DESIGN.md structure. The CLI is optional: if it is absent or any attempted operation fails, the Skill automatically uses its bundled template and structural validation. Tool failure never removes the fallback path.

What's Inside

skills/engi-design/
  SKILL.md                         Core workflow and rules
  agents/openai.yaml               Skill interface metadata
  assets/DESIGN.template.md        Built-in DESIGN.md fallback
  assets/review-shell/             Interactive review page shell
  references/state-model.md        Durable states and transition rules
  scripts/design-state.mjs         State creation and legal transitions
  scripts/create-review-page.mjs   Gallery and review page generation
  scripts/serve-review-page.mjs    Local review server
tests/                              Repository-level dry-run tests
bin/engi-design.mjs                 Multi-host npm installer
package.json                        npm package and CLI declaration

Development

Check the scripts and run the state-machine dry-run tests:

for file in skills/engi-design/scripts/*.mjs tests/*.mjs; do node --check "$file"; done
node --test tests/*.mjs

License

This project is licensed under the Apache License, Version 2.0. See LICENSE for details.