How do I install the Moai Workflow Design Import skill?

Run npx skillmds@latest add modu-ai/moai-workflow-design-import in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Moai Workflow Design Import skill do?

Parses Claude Design handoff bundle (ZIP or HTML) and extracts design tokens, component manifests, and static assets for expert-frontend delegation. Validates bundle version against the supported_bundle_versions whitelist and returns structured error codes on failure with path B fallback guidance. It is listed under Web & Frontend on SkillMD.

Is Moai Workflow Design Import safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Moai Workflow Design Import?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Moai Workflow Design Import free to use?

Yes. Installing skills from SkillMD is free. This skill is licensed under Apache-2.

Who published Moai Workflow Design Import?

modu-ai (@modu-ai) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Moai Workflow Design Import by modu-ai

Name: Moai Workflow Design Import
Author: modu-ai

moai-workflow-design-import

Handles Claude Design handoff bundle ingestion for the /moai design path A workflow. Validates bundle format, extracts design artifacts, and prepares structured output for expert-frontend delegation.

This skill is invoked only when the user selects path A (Claude Design) in /moai design and provides a local bundle file path.

Quick Reference

Supported Bundle Formats (Phase 1)

Primary supported formats:

ZIP: Claude Design export containing manifest.json, tokens.json, components/, and assets/
HTML: Single-file HTML export from Claude Design

Unsupported formats (Phase 2 roadmap):

DOCX, PPTX, PDF, Canva link — return DESIGN_IMPORT_UNSUPPORTED_FORMAT and guide to path B.

Version Whitelist

Before parsing, check the bundle's declared format version against supported_bundle_versions in .moai/config/sections/design.yaml.

Current default whitelist: ["1.0"]

If the detected bundle version is not in the whitelist, return DESIGN_IMPORT_UNSUPPORTED_VERSION with the three required stderr fields (see Error Codes).

Implementation Guide

Bundle Parsing Flow

Step 1: Receive the bundle file path from the orchestrator.

Step 2: Validate file existence. If the path does not exist or is not readable, return DESIGN_IMPORT_NOT_FOUND immediately with manual path guidance.

Step 3: Validate file format. Inspect the file extension and magic bytes:

.zip: ZIP magic bytes PK\x03\x04
.html: HTML DOCTYPE or <html tag at start

If neither matches, return DESIGN_IMPORT_UNSUPPORTED_FORMAT.

Step 4: Security scan (before any extraction):

List all ZIP entries (for ZIP bundles) without extracting
Reject if any entry contains: executable extensions (.sh, .exe, .bat, .cmd, .ps1, .py, .rb, .pl), symbolic links, path traversal sequences (../, ..\), or absolute paths
If any security issue detected, return DESIGN_IMPORT_SECURITY_REJECT without extracting any content

Step 5: Read manifest.json from the bundle root:

Extract format_version field
Compare against supported_bundle_versions from design.yaml
If version not in whitelist, return DESIGN_IMPORT_UNSUPPORTED_VERSION

Step 6: Extract and parse:

tokens.json → .moai/design/tokens.json
components/*.html or components/*.json → .moai/design/components.json (component manifest)
assets/** → .moai/design/assets/ (images, fonts, icons)
copy.json (if present) → .moai/design/copy.json

Step 7: Validate extracted tokens structure:

Required keys: colors, typography, spacing
If any required key is missing, add a warning to the output but do not fail

Step 8: Report extraction results to the orchestrator.

ZIP Bundle Expected Structure

bundle.zip
  manifest.json          # Required: format_version, claude_design_version, created_at
  tokens.json            # Required: colors, typography, spacing, radii, shadows
  components/            # Optional: component HTML or JSON specs
    hero.html
    navigation.html
    card.html
  assets/                # Optional: images, fonts, icons
    images/
    fonts/
    icons/
  copy.json              # Optional: structured copy output

HTML Bundle Expected Structure

Single-file HTML export. Extract:

Inline <style> CSS custom properties as color and spacing tokens
Inline <script> JSON blocks tagged with data-design-tokens
<link> tags referencing external assets (list only, do not fetch)

Output Artifacts

All output is written to .moai/design/:

.moai/design/tokens.json — Normalized design tokens:

{
  "colors": { "primary": "...", "secondary": "...", ... },
  "typography": { "fontFamily": {...}, "fontSize": {...}, ... },
  "spacing": { "base": 4, "scale": {...} },
  "radii": { "sm": "4px", ... },
  "shadows": { "sm": "...", ... },
  "source": "claude-design-bundle",
  "bundle_version": "1.0"
}

.moai/design/components.json — Component manifest:

{
  "components": [
    { "name": "Hero", "file": "hero.html", "variants": [...] },
    ...
  ]
}

.moai/design/assets/ — Static assets directory (images, fonts, icons extracted verbatim).

Error Codes

All errors are returned as structured responses with an error code and human-readable message.

DESIGN_IMPORT_NOT_FOUND

Trigger: Bundle file path does not exist or is not readable.
Action: Return error immediately. Output manual guidance: "Provide the correct local file path, or switch to path B (moai-domain-brand-design)."

DESIGN_IMPORT_UNSUPPORTED_FORMAT

Trigger: File is not ZIP, HTML, or magic bytes do not match.
Action: Return error with supported format list. Guide to path B.

DESIGN_IMPORT_UNSUPPORTED_VERSION

Trigger: Bundle manifest.json format_version is not in supported_bundle_versions whitelist.
Required stderr output (all three fields mandatory):
1. Detected version: "Detected bundle version: v<N>"
2. Supported versions: "Supported versions: <list from design.yaml>"
3. Fallback guidance: "Switch to path B: run /moai design and select 'Code-based brand design'"
Do not create any partial output files.

DESIGN_IMPORT_SECURITY_REJECT

Trigger: Bundle contains executable files, symbolic links, path traversal sequences, or absolute paths.
Action: Reject without extracting any content. List the offending entries in the error message.
Do not create .moai/design/ directory.

DESIGN_IMPORT_MISSING_MANIFEST

Trigger: ZIP bundle does not contain manifest.json.
Action: Return error. Cannot determine bundle version without manifest. Guide to path B.

Fallback Guidance

When any error code is returned, always append this guidance:

To continue with code-based design (path B):
1. Run /moai design
2. Select "Code-based brand design (moai-domain-brand-design)"
3. Ensure .moai/project/brand/visual-identity.md is complete

Advanced Patterns

Partial Bundle Recovery

If the bundle is valid but missing optional components (e.g., no components/ directory):

Extract what is available
Add warnings to the output manifest
Do not fail — proceed with partial output
Note missing sections in .moai/design/import-warnings.json

Token Normalization

Input bundles may use different naming conventions. Normalize to the MoAI token schema:

Bundle field	Normalized token
`primary_color`	`colors.primary`
`brand_color`	`colors.primary`
`heading_font`	`typography.fontFamily.heading`
`base_spacing`	`spacing.base`

Normalization rules are applied silently. Log all renamed fields in the import warnings.

Asset Safety

When extracting assets:

Validate image MIME types (accept: png, jpg, gif, webp, svg, ico)
Validate font formats (accept: woff2, woff, ttf, otf)
Reject archives within archives (no nested ZIPs)
Strip metadata from SVG files that contains script tags

Works Well With

moai-domain-brand-design: Fallback path when bundle import fails
moai-workflow-gan-loop: Receives extracted tokens for quality evaluation
expert-frontend: Primary consumer of extracted design artifacts

REQ coverage: REQ-SKILL-007, REQ-SKILL-008, REQ-SKILL-009, REQ-SKILL-010, REQ-SKILL-015 Version: 1.0.0

Moai Workflow Design Import

File contents

moai-workflow-design-import

Quick Reference

Supported Bundle Formats (Phase 1)

Version Whitelist

Implementation Guide

Bundle Parsing Flow

ZIP Bundle Expected Structure

HTML Bundle Expected Structure

Output Artifacts

Error Codes

Fallback Guidance

Advanced Patterns

Partial Bundle Recovery

Token Normalization

Asset Safety

Works Well With

Frequently asked questions

Moai Workflow Design Import

File contents

moai-workflow-design-import

Quick Reference

Supported Bundle Formats (Phase 1)

Version Whitelist

Implementation Guide

Bundle Parsing Flow

ZIP Bundle Expected Structure

HTML Bundle Expected Structure

Output Artifacts

Error Codes

Fallback Guidance

Advanced Patterns

Partial Bundle Recovery

Token Normalization

Asset Safety

Works Well With

Related skills

Frequently asked questions

How do I install the Moai Workflow Design Import skill?

What does the Moai Workflow Design Import skill do?

Is Moai Workflow Design Import safe to use?

Which AI agents work with Moai Workflow Design Import?

Is Moai Workflow Design Import free to use?

Who published Moai Workflow Design Import?