SuperAPI AI Directory
Partner中文AI newsFavorites
Skillssoia-dev-open-design-ops

soia-dev-open-design-ops

Design & creation

View repository

Updated 10-16 08:49

About this skill

soia-dev-open-design-ops — Open Design atomic operation layer

Only execute verifiable Open Design atomic operations; do not make visual direction, narrative, or template trade-offs on behalf of the client. Upper-layer design workflows can use this skill as the foundation for daemon, directory, design system, and export capabilities.

Client-readable description

What this skill can do

Client wants Skill will do Client can see
Check or start Open Design Check Node, pnpm, checkout, control the local daemon and probe /api/skills JSON status, missing items, log locations and repair commands
Onboard design system Distinguish the formal three-piece set from the DESIGN.md-only compatibility path, then onboard via the upstream CLI/App Design system id, source, verification result
Query capability directory Query functional skills and rendering templates separately Name, description,od.mode/category list
Render and export Drive the App/CLI via upstream stable entry points to export HTML, PDF, PPTX or MP4 Artifact paths, format semantics, openability check
Continue an existing design session Reuse the native session handle saved by the daemon Follow-up results for the same session or a clear reason for degradation

How the client uses it

  1. State the goal: environment check, daemon, design system, directory query, render/export, or continue session.
  2. Provide the Open Design checkout path; for design system onboarding, also provide the project path or DESIGN.md。
  3. For export, provide the project id, in-project source files, target format and output path; for PPTX also state whether "pixel fidelity" or "editable" is required.
  4. The Agent first runs read-only checks, then executes the minimal atomic command; overwriting files, deleting systems, or writing to remote requires separate confirmation.
  5. After execution, check the real API response or artifact; do not substitute the command exit code for acceptance.

Dependencies and installation

Install this skill:

npx skills add soia-team/soia-open-skills -g -a '*' -s soia-dev-open-design-ops -y

The upstream prerequisites for an Open Design local development checkout are Node.js 24.x, pnpm 10.33.x and Corepack. Per upstream QUICKSTART.md：

git clone https://github.com/nexu-io/open-design.git <open-design-root>
cd <open-design-root>
corepack enable
corepack pnpm --version   # upstream 当前 pin 10.33.2
pnpm install

This skill does not install or embed Open Design, nor does it treat Open Design as another agent skill. If any of Node/pnpm/checkout is missing, stop workflows that require the daemon and return the commands to fill the gap.

Private configuration

Copy config.example.yml to:

~/.config/soia-skills/soia-open-skills/soia-dev/soia-dev-open-design-ops/config.yml
SOIA_DEV_OPEN_DESIGN_OPS_CONFIG_FILE=<custom-config-path>

Configure at least OPEN_DESIGN_HOME. The daemon binds to loopback by default, with default port 7456; can be overridden with OPEN_DESIGN_DAEMON_PORT、OPEN_DESIGN_WEB_PORT、OPEN_DESIGN_DAEMON_URL . The project's own DESIGN.md path can hold OPEN_DESIGN_PROJECT_DESIGN_MD. Local checkout and project paths go only into private config or process environment, not into public body text, repositories or logs.

Logs and completion receipt

Daemon background logs and PID status are written to the user state directory; can be changed with OPEN_DESIGN_STATE_DIR . Must not print config contents or env values. Minimum receipt:

完成：<本次原子操作及结果>。

日志摘要：
- environment/daemon: <ok、missing 或 unreachable>
- processed: <系统/技能/模板/产物数量>
- created/updated: <产物或状态类别>
- skipped/failed: <数量与原因>

文件变化：<产物路径或“未改动项目文件”>
验证：<API、文件存在、页数/时长/打开检查>
问题与下一步：<缺依赖、需客户确认或“无”>

Positioning and boundaries

  • Only perform atomic operations such as install guidance, daemon, directories, design system integration, rendering/export, and resume.
  • Does not decide design direction, layout, brand language, deck narrative, or visual review; these belong to the upper-layer flows of slides, visual,soia-dev-design-explorer etc.
  • A functional skill is a capability in the agent's work; a design template is a rendering form. The two types of directories must not be merged into a single list.
  • Do not invent a headless API. When there is no stable script entry point upstream, explicitly write "the agent drives the upstream App/CLI according to the documentation".
  • Credentials, provider login state, and local paths go only into provider-owned storage, private config, or the process environment.

Environment and daemon

1. Detect the environment

Run from this skill's directory:

python3 scripts/check_env.py

The script offline-checks node、pnpm、OPEN_DESIGN_HOME and key repository files, and outputs status、missing、checks and suggestions JSON. When Node is not 24.x or pnpm is not 10.33.x, return an incompatible status; do not auto-upgrade.

2. Start/stop and health check

python3 scripts/daemon_ctl.py start
python3 scripts/daemon_ctl.py status
python3 scripts/daemon_ctl.py health
python3 scripts/daemon_ctl.py stop

start uses the pnpm tools-dev run web control plane from the upstream Quickstart, explicitly passing --daemon-port, and records PID and logs as a detached/nohup-style background process. Do not use the removed pnpm dev、pnpm daemon or pnpm start aliases. The health check is based on GET /api/skills returning the skills array;/api/health only indicates process-level liveness and does not prove the skill directory is usable.

The default URL is http://127.0.0.1:7456. Only loopback URLs are allowed; when remote deployment, reverse proxy, or 0.0.0.0 is required, this skill stops and asks the customer to handle it according to the upstream security configuration, and does not expose the local daemon on the customer's behalf.

Design system management and project integration

The Design System Project trio

When creating or maintaining a formal Open Design Design System Project, use the upstream _schema as the source; the minimum contract is:

<design-system-slug>/
├── manifest.json
├── DESIGN.md
└── tokens.css
  • manifest.json use od-design-system-project/v1, folder slug consistent with manifest id.
  • DESIGN.md is the canonical design prose for the agent;tokens.css is the canonical compiled semantic tokens.
  • A new system must not treat DESIGN.md-only as an authoring target. For the rich package's optional files and token constraints, the upstream docs/design-systems.md、design-systems/_schema/AGENTS.md and TypeScript schema are authoritative.

The user project's DESIGN.md-only compatible integration

An existing project may first put design rules in <user-project>/DESIGN.md. For registered legacy/user-installed directories, the daemon retains DESIGN.md-only discovery, but this is a compatibility fallback. Project integration should preferentially go through the CLI/App's local import, letting the daemon scan and build an editable design system:

node <open-design-root>/apps/daemon/dist/cli.js design-systems import-local <user-project> --name "<project-name>" --json
node <open-design-root>/apps/daemon/dist/cli.js design-systems list --json

For a first instance, you may configure a real product project's <product-project>/DESIGN.md to a private OPEN_DESIGN_PROJECT_DESIGN_MD, then execute <product-project> with import-local; do not copy or hardcode the maintainer's path. If dist/cli.js does not exist, first run in the checkout pnpm --filter @open-design/daemon build。

For common management commands, the actual output of od design-systems help is authoritative; v0.13.0 already has list/show/rename/download/import-local/import-github/import-shadcn. rename, delete, overwrite import, or token rebuild affect persistent state, so first show the target and the current state before confirming.

Directory query

Functional skills

python3 scripts/list_skills.py
python3 scripts/list_skills.py --category slides

The script calls the daemon GET /api/skills, and outputs name、description、od.mode and category;--category performs local exact filtering on the API-returned results, because the route itself has no server-side category query.

Rendering templates

Render templates are provided by GET /api/design-templates and checkout's design-templates/ , and do not belong to /api/skills. When templates are needed, use the App's New Project “Start from” rail or query that API directly; do not use list_skills.py to pretend to override the template directory.

Deck first selects one of three entry categories, then hands off to the upper-layer flow for design decisions:

  • simple-deck: design-system driven, single-file, tightly constrained horizontal deck;
  • guizang-ppt: e-magazine/WebGL line, including five directions: Monocle, WIRED, Kinfolk, Domus, and Lab;
  • html-ppt: HTML PPT Studio line, providing full-deck, theme, layout, animation, and presenter runtime directories.

Rendering and Export

Submit a render task

  1. In the App, select the runtime, design template, and design system, and submit the prompt; filesystem-capable runtimes write canonical project files, while text-only/BYOK runtimes return the complete <artifact>。
  2. Open the project from the App and verify the preview; or have a daemon-spawned agent use the injected OD_BIN、OD_DAEMON_URL、OD_PROJECT_ID、OD_PROJECT_DIR。
  3. Do not directly POST undocumented chat/run payloads. For automation, prefer the already-built od CLI; App-only interactions are driven by the agent according to upstream documentation.

HTML

HTML is the canonical artifact in the project. Use App Download → HTML, or read/copy the source files within the project. v0.13.0's od export does not have --format html, and that format must not be faked; use the project file API/route only when a project id and path actually exist.

PDF and PPTX

After building the daemon CLI, the stable commands from upstream v0.13.0 are available:

node <open-design-root>/apps/daemon/dist/cli.js export <project-file.html> \
  --project <project-id> --format pdf --out <output.pdf>
node <open-design-root>/apps/daemon/dist/cli.js export <deck.html> \
  --project <project-id> --format pptx --out <output.pptx>

The built-in PPTX is one screenshot per page, suitable for pixel-faithful delivery, not an editable shape/text deck. The recommended chain for editable PPTX:

  1. Use the HTML deck as the visual source of truth;
  2. Call the functional skill pptx-generator to generate editable .pptx；
  3. Call pptx-html-fidelity-audit to compare HTML/PPTX, and fix footer overflow, clipping, font/italic issues, and pacing drift;
  4. Open the final PPTX and verify page count, canvas size, key text, and absence of overflow.

MP4

MP4 uses the HyperFrames HTML renderer and does not pretend to be a general-purpose video export:

node <open-design-root>/apps/daemon/dist/cli.js media generate \
  --surface video --model hyperframes-html \
  --project <project-id> --composition-dir <project-relative-composition-dir> \
  --output <output.mp4>

The composition directory must contain the hyperframes.json/meta.json/index.htmlrequired by upstream. The daemon actually drives npx hyperframes render; after the task is queued, use the task id returned by the CLI with od media wait, and finally verify that the file exists, its MIME type, duration, and playability.

Session resume (v0.13.0)

Native resume is performed automatically by the daemon, not manually by the user od resume：

  1. Reopen the original project and the original conversation, without creating a new session;
  2. Send a follow-up turn;
  3. The daemon reuses the captured native session id for supported runtimes, so that v0.13.0-supported items such as Codex, OpenCode, Pi, and Open Design Cloud continue across turns;
  4. Check the run result and touched files to confirm it is not a cold start.

If the session handle has expired, the runtime is unsupported, or the CLI refuses to resume, clearly report “resume unavailable/expired”, and let the customer decide whether to rebuild context from historical messages; rebuilding must not be passed off as native resume. After a daemon restart, actual conversation/run metadata still serves as the evidence.

Private configuration command wrapper

When an explicit config load is needed to execute controlled upstream commands:

python3 scripts/run_with_env.py -- pnpm tools-dev status
python3 scripts/run_with_env.py -- pnpm --filter @open-design/daemon build

The wrapper only allows known Open Design lifecycle and build/install/version forms of Corepack/pnpm; it rejects shell,env、printenv, any executable, and pnpm exec/dlx. Must not use set -x, must not print env values.

Safety Rules

  1. The daemon is a local privileged service and by default only binds to 127.0.0.1; do not expose public ports for convenience.
  2. Do not print config, env, provider credentials, or tokens injected by the daemon; logs only state presence/absence.
  3. stop only handles PIDs recorded by this skill; when the PID does not match or the status is unclear, stop and report; do not guess the process.
  4. Before import, rename, delete, download overwrite, or export overwrite, check the target's current state; deletion and overwrite must obtain explicit authorization from the current request.
  5. Do not modify OPEN_DESIGN_HOME the upstream source code to "connect" the project; this skill only performs read-only queries or operates according to the official CLI/App.

Acceptance

  • Environment:check_env.py returns status=ok, with no missing.
  • daemon：daemon_ctl.py health Verify that /api/skills returns an array.
  • Directories: skills and templates are fetched separately; all category filter results match.
  • Design system: all three components are present, or it is explicitly marked as DESIGN.md-only compatibility; after import, list/show works.
  • Export: the target file exists, is non-empty, and its format can be opened; for PDF/PPTX check the page count, for MP4 check the duration and playability.
  • resume: follow-ups for the same project/conversation have native resume evidence; do not claim success without evidence.