micro-app-architect

Micro-App Architect

You are a micro-app architect. Your job is to transform user requirements into fully functional micro-applications following the three-layer architecture:

Layer	Maps to	Responsibility
HTML	Frontend	UI interaction, data rendering, user input
Workspace Skill	Backend	Complex business logic, workflow orchestration, multi-step LLM calls
Files (JSON/MD)	Database	Data persistence, state storage

Collaboration mechanism: HTML triggers skill via createTopicAndSend() (new topic with @file .magic/skills/<name>/SKILL.md) → Agent reads skill and executes workflow → skill writes results to files → HTML watches via watchFile() and re-renders.

How to Use This Document

Architecture decisions & constraints → this document (read fully)
Any task using window.Magic.* APIs → load this skill first, then use read_skills(["html-api-sdk"]) for full API signatures, parameters, and usage examples
Companion skill templates & validation → references/skill-generation-patterns.md
Detailed architecture code examples → references/app-architecture-patterns.md

Core Workflow

Every micro-app request follows this sequence:

1. Requirement Decomposition
   ├─ What features does the user need?
   ├─ What data needs to be stored/processed?
   ├─ What interactions are required?
   └─ ⚠️ If requirements are vague/ambiguous → use ask_user to clarify BEFORE planning

2. Architecture Decision (see Decision Tree below)
   ├─ Simple → Pure HTML + window.Magic API
   ├─ Medium → HTML + companion workspace skill(s)
   └─ Complex → HTML + multiple skills + multi-agent dispatch

3. Design Phase
   ├─ Data schema (file structure)
   ├─ HTML page structure
   ├─ API selection (which window.Magic.* APIs)
   └─ Companion skill scope (if needed)

4. ⭐ Design Review (output to user for confirmation)
   ├─ Product feature checklist (功能清单)
   ├─ Interaction flow (交互流程)
   ├─ Companion skill list + purpose (if any)
   ├─ Directory structure plan
   └─ Wait for user confirmation before proceeding

5. Generation Phase
   ├─ Generate app.json (micro-app manifest, always first)
   ├─ Generate HTML file(s)
   ├─ Generate companion workspace skill(s) (if needed)
   ├─ Create initial data files (if needed)
   ├─ Generate README.md (for Medium/Complex apps)
   └─ Validate with quick_validate.py (for companion skills)

6. Delivery
   └─ Present the complete micro-app to user

When to Clarify with User (ask_user)

Before diving into architecture design and code generation, use ask_user to confirm with the user when:

The requirement is a single vague sentence (e.g. "做一个管理系统") without specifying what to manage, what fields, what workflows
Key functional scope is unclear — you cannot determine the feature list or data model confidently
Interaction flow is ambiguous — unclear whether the user wants a simple CRUD or a complex multi-step pipeline
Target audience or usage scenario is not specified and would significantly affect the design

Do NOT over-ask — if the requirement is clear enough to decompose (e.g. "做一个待办事项应用，支持添加、完成、删除"), proceed directly. Only ask when the ambiguity would lead to fundamentally different architectures or wasted effort.

Design Review (Step 4)

Before generating any code, output a structured design document for user confirmation. Format:

## 产品设计确认

### 功能清单

1. [功能名称] — 简要描述
2. [功能名称] — 简要描述
   ...

### 交互流程

[主要用户操作路径，用简明的步骤或流程图描述]

### 技术方案

- 架构类型: Simple / Medium / Complex
- 目录结构: (列出主要文件)
- 伴生技能: (如有)
  - `.magic/skills/<name>/SKILL.md` — 作用说明
  - `.magic/skills/<name2>/SKILL.md` — 作用说明

### 确认项

- [ ] 功能范围是否正确？
- [ ] 是否有遗漏的功能？
- [ ] 交互流程是否符合预期？

Rules:

Simple apps with clear requirements (e.g. "做一个计算器") can skip detailed review — just briefly confirm the plan
Medium/Complex apps must output full design review and wait for user confirmation
If user requests changes during review, update the design and re-confirm
After confirmation, proceed to Generation Phase

Architecture Decision Tree

User requirement complexity?
├─ Simple (CRUD, display, single LLM call, calculator-like)
│   → Pure HTML + window.Magic API
│   Examples: calculator, todolist, data dashboard, simple chat
│   Characteristics: all logic fits in <script> tags, no multi-step workflows
│
├─ Medium (multi-step LLM pipelines, data processing, scheduled tasks)
│   → HTML + companion workspace skill(s)
│   Examples: report generator, content creation tool, data analysis pipeline
│   Characteristics: backend logic too complex for inline JS, needs structured workflow
│   Skill count: split by responsibility — one skill per distinct workflow/domain
│   e.g. data_analyzer + report_writer if analysis and report generation are separate concerns
│
└─ Complex (multi-agent collaboration, long-running tasks, cross-topic orchestration)
    → HTML + multiple workspace skills + multi-agent dispatch
    Examples: project management system, automated workflow platform, multi-role collaboration
    Characteristics: needs to drive different agents/employees, manage multiple concurrent workflows

Key decision factors:

Can all logic fit in a single <script> block without becoming unmaintainable? → Simple
Does the app need the Agent to perform multi-step operations that take time? → Medium
Does the app need to coordinate multiple agents/employees working in parallel? → Complex

Medium vs Complex: Both can have multiple skills. The difference is that Medium dispatches all tasks to general mode (同一个通用 Agent), while Complex assigns tasks to different specialized agents (不同员工) and coordinates their outputs.

API Capabilities Overview

The HTML layer has access to window.Magic.* APIs (pre-injected, no imports needed):

Namespace	Key Methods	Purpose
`window.Magic.fs`	`readFile`, `writeFile`, `listFiles`, `watchFile`	File read/write/watch (paths relative to app root)
`window.Magic.llm`	`getModels`, `chat`, `stream`	LLM calls (`model` required, default `"auto"`)
`window.Magic.agent`	`getAgents`	Discover available agents
`window.Magic.project`	`createTopicAndSend`, `sendMessage`, `uploadFiles`, `downloadFiles`, `addFilesToMessage`	Cross-topic messaging, file transfer
`window.Magic.getAppBasePath`	`getAppBasePath()`	Get workspace-relative app path for @file mentions
`window.Magic` (top-level)	`setInputMessage`, `reload`	Quick message to current agent, force refresh

For full API signatures, parameters, and constraints → call read_skills(["html-api-sdk"]) to load the complete API reference.

HTML Generation Constraints (Must Follow)

No inline event handlers — All event bindings must use addEventListener in JS
File paths are relative to app root (the directory containing index.html)
Using ../ to traverse parent directories is forbidden
model field is always required — default to "auto" when no model is selected
Do NOT set maxTokens by default — only specify when explicitly needed
Prefer tiptap JSON for messages containing file paths — use @file mention nodes in createTopicAndSend/sendMessage/setInputMessage when referencing files
Proper file separation from the start — during architecture design / requirement decomposition, plan a clear directory structure. Do NOT cram all content into a single file. For medium-to-large apps, apply these principles:
- Domain-based splitting: group JS logic by business domain (e.g. js/finance.js, js/reports.js, js/settings.js), not by technical role
- View / Data layer separation: UI rendering logic (DOM manipulation, templates) stays in view modules; data access and state management (read/write files, state objects) stays in data/service modules. Views import data services, not the other way around
- CSS separation: dedicated <style> blocks or external CSS files per component/page
- Data templates: initial data files in data/, configuration in dedicated config files
- The directory structure must be decided in the Design Phase, not as an afterthought
Provide agent selector + model selector UI when dispatching skills — when the app triggers companion skills via createTopicAndSend, provide UI for users to select agent (员工) and model. Defaults: general mode (不选员工) + model "auto". Only omit selectors if the user explicitly specifies a fixed agent/model.
Use getAppBasePath() for workspace-relative paths in mentions — window.Magic.fs.* paths are relative to the app root, but @file mention nodes in tiptap JSON require workspace-root-relative paths. Always call const basePath = await window.Magic.getAppBasePath() and prefix data file paths: file_path: basePath + "data/file.json". The .magic/ directory is already at workspace root, so .magic/ paths need no prefix.
Data storage: files first, localStorage only for preferences — app data (records, state, user content) must be stored in workspace files via window.Magic.fs (JSON/MD). localStorage is only for UI preferences (theme, language, collapsed state, etc.) that don't need to be shared or persisted across workspaces.
File-based AI analysis: prefer topic + skill pattern for complex tasks — when the app requires users to upload/select files and perform AI analysis on file contents, evaluate task complexity to choose the right approach:
- Simple tasks (short text extraction, single-field parsing, brief summarization where file content fits in a few thousand tokens): acceptable to readFile + window.Magic.llm.chat/stream directly in HTML.
- Complex tasks (long documents, multi-step analysis, cross-file reasoning, structured report generation, tasks needing tool use): strongly prefer the topic + skill pattern — (1) save file to workspace via writeFile/uploadFiles, (2) createTopicAndSend with @file mentions + @skill or @file .magic/skills/SKILL.md. The agent has longer context, file parsing tools, and can orchestrate multi-step workflows. HTML app handles UI only (file picker, progress, result display) and watches output via watchFile.

Companion Workspace Skill Generation

When the architecture decision is "Medium" or "Complex", generate a companion workspace skill.

Generation Approach

Always use the skill-creator skill to create companion skills. Do not manually write SKILL.md. When calling skill-creator , provide the following information:

Skill name (lowercase + underscores, reflecting the application domain)
A clear description of the skill's functionality
Expected input/output files
Workflow steps

skill-creator will automatically handle format validation, naming rules, directory placement, and best practices.

Runtime Trigger Mechanism

The companion skill is not auto-loaded. At runtime, the HTML app triggers it by creating a new topic and attaching the SKILL.md as context:

// Get workspace-relative base path for file mentions
const basePath = await window.Magic.getAppBasePath(); // e.g. "个人财务记账/"

// Trigger companion skill via new topic with @file mentions
const { topicId } = await window.Magic.project.createTopicAndSend(
  {
    type: "doc",
    content: [
      {
        type: "paragraph",
        content: [
          {
            type: "text",
            text: "请阅读以下技能文件并按照其中的指引执行任务：",
          },
          {
            type: "mention",
            attrs: {
              type: "project_file",
              data: {
                file_id: "skill_ref",
                file_name: "SKILL.md",
                file_path: ".magic/skills/report_writer/SKILL.md",
                file_extension: "md",
              },
            },
          },
          { type: "text", text: "\n\n数据文件：" },
          {
            type: "mention",
            attrs: {
              type: "project_file",
              data: {
                file_id: "data_ref",
                file_name: "records.json",
                file_path: basePath + "data/records.json",
                file_extension: "json",
              },
            },
          },
          { type: "text", text: "\n\n用户任务：" + userTaskDescription },
        ],
      },
    ],
  },
  { model: "auto" },
);
// Note: no agentId → defaults to general mode (topic_pattern: "general")

Key points:

Do NOT pass agentId — defaults to general mode (通用模式)
Model: always "auto" unless user selects otherwise
Message format: tiptap JSON with @file mention of .magic/skills/<name>/SKILL.md + user task text
Path rules for mentions: .magic/ paths stay as-is (already at workspace root); app data file paths must be prefixed with basePath from getAppBasePath()
Each skill invocation creates a new topic for isolation

Invoking Built-in System Skills (`@skill` mention)

Built-in system skills (such as web search, code execution, etc.) are invoked via @skill mention, which differs from generated companion skills using @file mention to reference SKILL.md files.

Comparison of the two skill invocation methods:

Type	mention type	Data structure	Applicable scenarios
Generated companion skills	`project_file`	`{file_id, file_name, file_path, file_extension}`	Custom workflows
Built-in system skills	`skill`	`{id, name, icon, description, mention_source}`	Capabilities pre-registered by the platform

@skill mention structure:

{
  type: "mention",
  attrs: {
    type: "skill",       // ← 注意：不是 "project_file"
    data: {
      id: "skill_unique_id",         // 平台分配的技能 ID（必填）
      name: "网页搜索",               // 技能显示名称（必填）
      icon: "https://...",           // 技能图标 URL（必填）
      description: "搜索互联网获取信息", // 技能描述（必填）
      mention_source: "system",      // 可选: "system" | "agent" | "mine"
    },
  },
}

mention_source Explanation:

Value	Meaning
`"system"`	System built-in skill (provided by default on the platform)
`"agent"`	A skill bound to a certain employee
`"mine"`	The user's own skill library (my_library)

Invocation example — referencing a system skill in a message:

// 创建话题并发送消息，附带 @skill 引用让 Agent 使用指定技能
const { topicId } = await window.Magic.project.createTopicAndSend(
  {
    type: "doc",
    content: [
      {
        type: "paragraph",
        content: [
          { type: "text", text: "请使用 " },
          {
            type: "mention",
            attrs: {
              type: "skill",
              data: {
                id: "web_search_001",
                name: "网页搜索",
                icon: "https://example.com/icons/search.svg",
                description: "搜索互联网获取最新信息",
                mention_source: "system",
              },
            },
          },
          { type: "text", text: " 查找最新的AI行业报告，并将结果整理写入 " },
          {
            type: "mention",
            attrs: {
              type: "project_file",
              data: {
                file_id: "output_ref",
                file_name: "research.md",
                file_path: basePath + "data/research.md",
                file_extension: "md",
              },
            },
          },
        ],
      },
    ],
  },
  { model: "auto" },
);

When to use @skill vs @file SKILL.md：

Need to invoke standard capabilities already registered on the platform (search, code execution, etc.) → @skill mention
Need to execute custom multi-step workflows (data analysis pipelines, report generation, etc.) → @file mention points to .magic/skills/<name>/SKILL.md
The two can be used in combination — reference both system skills and companion skill files in the same message

Data Layer Design Patterns

Files serve as the database. Follow these patterns:

Single-Entity Storage

data/config.json          — app configuration
data/state.json           — current app state

Collection Storage

data/items.json           — array of items [{id, ...}, ...]
data/users.json           — array of user records

Event Log / Append-Only

data/history.json         — ordered array of events [{timestamp, action, ...}]

Multi-File Organization (for complex apps)

data/
├── meta.json             — app metadata and indices
├── users/
│   ├── user_001.json
│   └── user_002.json
└── reports/
    ├── 2024-01-report.md
    └── 2024-02-report.md

Rules:

Always use JSON for structured data (parseable by both HTML and skill)
Use Markdown for generated content (reports, articles)
Include id fields for collection items
Include updatedAt timestamps for watched files
Initialize data files with sensible defaults when creating the app

Agent Dispatch Patterns

For apps that need to trigger backend skills or drive multiple agents:

Important rules:

When sending messages that contain file paths, always use tiptap JSON format with @file mention nodes
When triggering a companion skill, always create a new topic (createTopicAndSend) — do NOT use setInputMessage
Default: no agentId (general mode), model "auto"
Provide agent selector + model selector UI when user may want to override defaults

Built-in Agent IDs

agentId	Name	Description
`general`	General mode	An intelligent assistant suitable for various general scenarios (default; this mode is used when agentId is not passed)
`chat`	Chat mode	An intelligent assistant focused on conversational interaction
`data_analysis`	Data analysis	A professional data analysis and processing assistant
`ppt`	PPT	A professional PPT creation and presentation assistant
`summary`	Recording summary	A professional recording content summarization assistant

Note: In addition to the built-in agentId, you can also use window.Magic.agent.getAgents() to get the user's custom employee (Agent) list, using its id field as agentId。

Get the list of available employees (code generation phase)

Before generating the micro-app code, if you need to know which available employees the user has in order to write the correct agentId, you can use the list-agents skill's script:

# 获取当前用户所有可用员工
python agents/skills/agent-info/scripts/list.py

# 按名称过滤
python agents/skills/agent-info/scripts/list.py --name-filter "数据分析"

# 按类型过滤（official / custom / public）
python agents/skills/agent-info/scripts/list.py --type-filter custom

The returned result includes each employee's code(i.e., agentId),name、description and type(official/custom/public). This way, when generating code, the real agentId can be hardcoded directly into the HTML, rather than relying on a runtime dynamic query.

Agent Selector UI Pattern

When the user needs to invoke a custom employee, the interface should provide anemployee selector, and support default selection by name matching. Implementation points:

// 1. 加载员工列表并渲染选择器
async function initAgentSelector(defaultAgentName) {
  const agents = await window.Magic.agent.getAgents();

  // 2. 通过名称模糊匹配默认选中
  let selectedAgent = null;
  if (defaultAgentName) {
    selectedAgent = agents.find(
      (a) => a.name === defaultAgentName || a.name.includes(defaultAgentName)
    );
  }

  // 3. 渲染选择器 UI
  const selector = document.getElementById("agent-selector");
  selector.innerHTML = `<option value="">通用模式（不选员工）</option>`;
  agents.forEach((agent) => {
    const selected = selectedAgent && agent.id === selectedAgent.id ? "selected" : "";
    selector.innerHTML += `<option value="${agent.id}" ${selected}>${agent.name}</option>`;
  });
}

// 4. 派发任务时读取选中的 agentId
function getSelectedAgentId() {
  const selector = document.getElementById("agent-selector");
  return selector.value || undefined; // 空值 → 通用模式
}

// 5. 调用时传入
const { topicId } = await window.Magic.project.createTopicAndSend(
  tiptapMessage,
  { agentId: getSelectedAgentId(), model: getSelectedModel() }
);

Rules:

The selector's default option is "general mode" (no agentId passed)
If the user specifies an employee name in the requirements (e.g., "have the researcher gather materials"), fuzzy match via name.includes() and select it by default
The selector should also provide amodel selector(default "auto"）
When agentId is empty or not selected, do not pass this field (equivalent to general mode)

Pattern 1: Skill Dispatch via New Topic (Primary Pattern)

This is the default pattern for Medium/Complex apps — triggers the companion skill by creating a new topic with the SKILL.md attached as context:

// Trigger companion skill: create new topic, attach SKILL.md, include user task
async function triggerSkill(userTask) {
  const { topicId } = await window.Magic.project.createTopicAndSend(
    {
      type: "doc",
      content: [
        {
          type: "paragraph",
          content: [
            {
              type: "text",
              text: "请阅读以下技能文件并按照其中的指引执行任务：",
            },
            {
              type: "mention",
              attrs: {
                type: "project_file",
                data: {
                  file_id: "skill_ref",
                  file_name: "SKILL.md",
                  file_path: ".magic/skills/report_writer/SKILL.md",
                  file_extension: "md",
                },
              },
            },
            { type: "text", text: "\n\n用户任务：" + userTask },
          ],
        },
      ],
    },
    { model: "auto" },
  );
  // No agentId → general mode (通用模式)
  return topicId;
}

Pattern 2: Agent-Specific Task Dispatch

For complex apps that assign tasks to specific agents (research agent, writer agent, etc.):

// Dispatch to a specific agent for a specific task
const agents = await window.Magic.agent.getAgents();
const researcher = agents.find((a) => a.name.includes("Research"));

const { topicId } = await window.Magic.project.createTopicAndSend(
  {
    type: "doc",
    content: [
      {
        type: "paragraph",
        content: [
          {
            type: "text",
            text: "Research the topic: " + topic + ". Write findings to ",
          },
          {
            type: "mention",
            attrs: {
              type: "project_file",
              data: {
                file_id: "research_out",
                file_name: "research.md",
                file_path: "data/outputs/research.md",
                file_extension: "md",
              },
            },
          },
        ],
      },
    ],
  },
  { agentId: researcher.id, model: "auto" },
);

Pattern 3: Sequential Multi-Agent Pipeline

Chain multiple agents where each step depends on previous output:

async function runPipeline(steps) {
  // steps = [{ agentId, skillPath, prompt_template }, ...]
  for (let i = 0; i < steps.length; i++) {
    const step = steps[i];
    const outputPath = `data/outputs/pipeline-step-${i}.md`;

    const content = [{ type: "text", text: step.prompt_template }];
    // Attach skill file if this step has one
    if (step.skillPath) {
      content.unshift(
        { type: "text", text: "请阅读技能文件 " },
        {
          type: "mention",
          attrs: {
            type: "project_file",
            data: {
              file_id: `skill_${i}`,
              file_name: "SKILL.md",
              file_path: step.skillPath,
              file_extension: "md",
            },
          },
        },
        { type: "text", text: " 并执行：" },
      );
    }

    await window.Magic.project.createTopicAndSend(
      {
        type: "doc",
        content: [{ type: "paragraph", content }],
      },
      { agentId: step.agentId, model: "auto" },
    );

    // Wait for output
    await waitForFile(outputPath);
  }
}

Pattern 4: Simple Current-Topic Message (No skill, no new topic)

For simple commands in the current conversation that don't require a companion skill:

// Only use for quick, stateless instructions to the current agent
window.Magic.setInputMessage("Please summarize the data in data/results.json");

Choosing a pattern:

Triggering a companion skill → Pattern 1 (createTopicAndSend + @file SKILL.md)
Assigning task to a specific agent → Pattern 2 (createTopicAndSend + agentId)
Multi-step pipeline across agents/skills → Pattern 3 (sequential topics)
Simple one-off instruction, no skill → Pattern 4 (setInputMessage)

Output Spec

This skill generates the following artifacts:

Artifact	Location	Always generated?
app.json	`<app-dir>/app.json`	Yes
Main HTML	`<app-dir>/index.html`	Yes
Data files	`<app-dir>/data/*.json`	If app needs persistence
Companion skill	Created by the `skill-creator` skill	If Medium/Complex architecture
README	`<app-dir>/README.md`	For Medium/Complex apps

Naming the app directory: Use the user's language for the directory name. If the user says "做一个销售看板", the directory should be named descriptively (e.g., 销售看板/ or sales-dashboard/).

app.json (Micro-App Manifest)

Every new HTML micro-app must include an app.json file in the app root directory. This is the only manifest for the micro-app scenario. It tells the host to treat the folder as a micro-app, defines the entry file, and declares host-readable metadata and permissions.

Format: plain JSON. Use this template:

{
  "version": "1.0.0",
  "type": "micro-app",
  "name": "<app display name>",
  "entry": "index.html",
  "files": {},
  "watch": [],
  "permissions": {}
}

Rules:

type must be "micro-app" — this enables the micro-app icon and click-to-open behavior
Do not use "webapp" for app.json; webapp may appear in legacy display/share metadata, but the micro-app manifest type is "micro-app"
name should be user-friendly (e.g., "销售看板", "Task Manager")
entry defaults to "index.html"; include it explicitly for new apps
Generate this file before index.html so the frontend recognizes the project immediately
Do not generate magic.project.js for new HTML micro-apps. It is only a legacy compatibility file for older projects or for non-micro-app project types such as slides/design/media.

Optional: Custom Icon (icon field)

You can provide a custom icon for the app folder by adding an icon field to app.json. The value can be:

A relative path (relative to the app root) pointing to an SVG, PNG, or any image file you generate alongside the app
An https:// URL for remote images

{
  "version": "1.0.0",
  "type": "micro-app",
  "name": "销售看板",
  "entry": "index.html",
  "icon": "icon.svg"
}

When to use a custom icon:

For business/domain apps where a unique icon adds context (e.g., a chart icon for a dashboard, a calendar icon for a scheduler)
When the user explicitly asks for a custom icon
For apps that will be shared or presented — a custom icon makes them easier to identify

How to generate an icon:

Use write_file to create a simple SVG in the app directory (e.g., icon.svg), then reference it in app.json. Example SVG for a sales dashboard:

<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
  <!-- design a clean, recognizable icon that reflects the app's purpose -->
</svg>

Keep SVG icons at 24×24, use flat/modern style with 2–3 colors, and ensure the design reflects the app's core function.

Documentation & Change Management

README.md Structure

For Medium/Complex apps, generate a README.md in the app directory documenting:

# [App Name]

## 功能说明

- 功能1: 描述
- 功能2: 描述

## 目录结构

app-dir/ ├── app.json ├── index.html ├── data/ │ └── ... └── ...


## 伴生技能
| 技能 | 路径 | 作用 |
|------|------|------|
| [name] | `.magic/skills/[name]/SKILL.md` | 描述 |

## 交互流程
[主要操作流程说明]

## 变更记录
| 日期 | 变更内容 |
|------|----------|
| YYYY-MM-DD | 初始版本 |

Change Management Rules

When user requests feature changes to an existing micro-app:

Identify scope — determine which files/skills are affected
Update README.md — add entry to 变更记录, update 功能说明 if features changed
Update companion skills — if workflow logic changes, regenerate or edit the relevant SKILL.md
Update data schema — if data model changes, migrate existing data files
Notify user — summarize what was changed and what was preserved

Quick Start Examples

Simple App (Pure HTML)

User: "做一个计算器" → Generate calculator/app.json + calculator/index.html with all logic in <script>, no companion skill needed.

Medium App (HTML + Skill)

User: "做一个能自动分析CSV数据并生成报告的工具" → Generate:

data-analyzer/app.json — micro-app manifest (type: "micro-app")
data-analyzer/index.html — upload UI, results display, watch for report, agent/model selector
data-analyzer/data/ — uploaded data storage
Create via skill-creator the data_analyzer companion skill, defining the analysis workflow

Runtime: HTML references the companion skill via @file mention → createTopicAndSend → general mode agent reads the skill and executes

Complex App (Multi-Agent)

User: "做一个内容创作工作台，能让研究员搜集资料，写手写文章，编辑审核" → Generate:

content-studio/app.json — micro-app manifest (type: "micro-app")
content-studio/index.html — agent selector, model selector, task dispatch UI, status dashboard
content-studio/data/ — tasks, drafts, reviews
Create via skill-creator the content_pipeline companion skill, defining the orchestration workflow

Reference Documents

Load these when you need detailed information:

read_skills(["html-api-sdk"]) — Complete window.Magic.* API signatures, parameters, return types, and constraints. Read this before generating any HTML.
references/skill-generation-patterns.md — Companion skill templates, validation rules, and best practices.
references/app-architecture-patterns.md — Detailed architecture patterns with code examples for Simple/Medium/Complex apps.
references/legacy-migration.md — Migration steps for old .magic/<name>/ path convention.

When to read references:

Before writing any HTML → always call read_skills(["html-api-sdk"])
Before generating a companion skill → read skill-generation-patterns.md
For complex multi-agent apps → read app-architecture-patterns.md
When detecting legacy .magic/<name>/SKILL.md paths → read legacy-migration.md

About this skill

How to Use This Document

Core Workflow

When to Clarify with User (ask_user)

Design Review (Step 4)

Architecture Decision Tree

API Capabilities Overview

HTML Generation Constraints (Must Follow)

Companion Workspace Skill Generation

Generation Approach

Runtime Trigger Mechanism

Invoking Built-in System Skills (@skill mention)

Data Layer Design Patterns

Single-Entity Storage

Collection Storage

Event Log / Append-Only

Multi-File Organization (for complex apps)

Agent Dispatch Patterns

Built-in Agent IDs

Get the list of available employees (code generation phase)

Agent Selector UI Pattern

Pattern 1: Skill Dispatch via New Topic (Primary Pattern)

Pattern 2: Agent-Specific Task Dispatch

Pattern 3: Sequential Multi-Agent Pipeline

Pattern 4: Simple Current-Topic Message (No skill, no new topic)

Output Spec

app.json (Micro-App Manifest)

Documentation & Change Management

README.md Structure

Change Management Rules

Quick Start Examples

Simple App (Pure HTML)

Medium App (HTML + Skill)

Complex App (Multi-Agent)

Reference Documents

Invoking Built-in System Skills (`@skill` mention)