| name | moai-workflow-design-import |
| description | 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.
|
| license | Apache-2.0 |
| compatibility | Designed for Claude Code |
| allowed-tools | Read, Write, Edit, Grep, Glob, Bash |
| user-invocable | false |
| metadata | {"version":"1.0.0","category":"workflow","status":"active","updated":"2026-04-20","tags":"design import, handoff bundle, claude design, design tokens, components","related-skills":"moai-domain-brand-design, moai-workflow-gan-loop"} |
| progressive_disclosure | {"enabled":true,"level1_tokens":100,"level2_tokens":5000} |
| triggers | {"keywords":["design import","handoff bundle","claude design","bundle path","design zip","import bundle"],"agents":["expert-frontend"],"phases":["run"]} |
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, ), symbolic links, path traversal sequences (, ), or absolute paths
