Generator Onboarding

This document is for developers who want to develop new generators or refactor existing ones using Cursor + AI. The goal is not just to generate a full page, but to have the generator converge into a standard integration form that includes generator-sdk platform capabilities and full / embed modes by default.

What You Get

By using this workflow, the AI will default to the following goals in new or refactoring scenarios:

• Access platform capabilities like login, export, Open in Studio, credits, and billing via generator-sdk.
• Expose window.__GENERATOR_RUNTIME__.
• Support embed mode in both full pages and template pages.
• Support PanelSchema and PanelFilter.
• Enable left-side canvas and right-side partial parameter panels in template pages.
• Automatically enable the template feature if template authoring capabilities are explicitly needed, generating a template publish/import skeleton.

For existing generators, the AI should also distinguish between two task types:

• Compatibility Refactoring: Prioritizes non-regression and minimal changes, allowing for phased delivery.
• Standardization Refactoring: Ultimately converges to a standard generator structure, not just stopping at "SDK + lightweight bridge".

Prerequisites

Before starting, please prepare:

• A working Cursor environment.
• Node.js 18 or higher.
• CMS login permissions.

For new generators created through AI, the skill will auto-generate a development appKey in the form dev_<random> and write it into GeneratorSDK.init({ appKey }). The appKey is the generator ID, and developers can define a stable ID themselves when integrating manually.

Step 1: Install Agent Skills and MCP

Add the following to your Cursor MCP Servers configuration:

{
  "mcpServers": {
    "generator-sdk": {
      "command": "npx",
      "args": [
        "-y",
        "@atomm-developer/generator-sdk-mcp@latest"
      ]
    }
  }
}

Save and restart Cursor.

Step 2: Add Skills to Your Project

The public skills repository is xtool-official/xtool-skills. If you want to inspect the source of creating-generators, browse available installable skills, or confirm the marketplace repository, use this repo directly.

1.1 Method 1: Manual Installation

claude plugin marketplace add xtool-official/xtool-skills
claude plugin install creating-generators@xtool-skills

1.2 Method 2: Let AI Install Them

Please help me install the skills related to creating-generators.
1. Add the marketplace source (if not already added):
   xtool-official/xtool-skills
2. Then install the following plugins:
   - creating-generators
Tell me the result after installation.

1.3 Method 3: Create in Your Project Root

Create the following structure in your generator project root:

.cursor/
  skills/
    creating-generators/
      SKILL.md
      reference.md

If you cannot find the skill files in the release package, you can copy them directly from the documentation:

• Reusable Skill Files

Step 3: How to Ask the AI for the First Time

Once the MCP and skills are installed, you don't need to paste a large block of fixed specifications. Usually, you just need to express your intent to "develop a generator."

For example:

Help me make a new photo frame generator

or:

Help me develop a pendant generator

Normally, the skill will automatically follow up with:

1. Generator name
2. Auto-generated development appKey (for new generators)
3. Tech stack: html or vue
4. Which SDK features to integrate
5. Whether template authoring capabilities are needed

After answering, the AI will default to these constraints:

• Use a runtime starter instead of just generating a full page.
• Enable full / embed by default.
• Expose window.__GENERATOR_RUNTIME__ by default.
• Implement getState, setState, patchState, getPanelSchema, export, and subscribe by default.
• Support PanelFilter for parameter panels.
• Automatically enable the template feature if templates, template pages, sub-generators, or partial parameter adjustments are mentioned.

If you are giving a refactoring task for an existing generator, the new default follow-up sequence should clarify:

1. Whether it's Compatibility Refactoring or Standardization Refactoring.
2. Where the old code directory or repository is.
3. Whether to reuse the existing generator appKey.
4. Current tech stack: html / vue / bridge / partial runtime.
5. Whether phased delivery is allowed.

Recommended Prompts for Existing Generators

If you want Compatibility Refactoring:

This is an existing generator source at @index.html.
Please perform compatibility refactoring in the @refactor directory:
1. All functionality, interaction, style, and export behavior must remain unchanged.
2. Integrate generator-sdk.
3. Allow phased delivery, but do not describe phased delivery as standardization completion.

If you want Standardization Refactoring:

This is an existing generator source at @index.html.
Please perform standardization refactoring in the @refactor directory, not just minimal compatibility changes:
1. All functionality, interaction, style, and export behavior must remain unchanged.
2. Integrate generator-sdk.
3. Complete the full Generator Runtime Contract.
4. Provide full / embed dual entry points.
5. Support PanelSchema + PanelFilter.
6. Use the unified template protocol if template scenarios are involved.
7. Do not claim standardization completion until the standard generator refactor is finished.

A Real Conversation Example

Developer: Help me make a new photo frame generator.

AI: First, let's confirm the generator name. What name do you want for this generator?

Developer: Spring Photo Frame Generator

AI: Please provide the appKey for this generator. The appKey is the generator ID and will be written directly into `GeneratorSDK.init({ appKey })`.

Developer: mk_gen_frame_spring

AI: Which tech stack would you like to use? Options: html / vue. Default recommendation: html for quick vibe coding, vue for engineered projects.

Developer: vue

AI: Which SDK features do you need to integrate? You can select multiple: Login, Export SVG, Open in Studio, Credits, Billing, Cloud Save, History.

Developer: Login, Export SVG, Open in Studio, Credits

AI: Do you need template authoring capabilities? If templates, template pages, sub-generators, or partial parameter adjustments are involved, I will automatically enable the template feature.

Developer: Yes, I need to support publishing and importing templates.

AI: Understood. I will generate a project skeleton based on starter-vue-runtime, enable full / embed dual modes by default, and automatically include __GENERATOR_RUNTIME__, getState, setState, patchState, getPanelSchema, export, subscribe, and the PanelFilter capability required for template pages. I will also enable the template feature and generate the unified template JSON protocol and "Publish Template / Import Template" skeleton. Let's start generating the code.

What the AI Actually Does

Normally, the AI will perform these tasks via the MCP:

1. Identify the "develop generator" intent.
2. Determine if it's a new project, compatibility refactoring, or standardization refactoring.
3. Ask for the generator name / old code location / generator appKey / tech stack / SDK features.
4. Query the generator-sdk and Runtime Contract documentation.
5. Call generate_runtime_starter for new projects.
6. For refactoring, perform a gap analysis first, then decide on an adapter, runtime wrapper, or reference starter refactor.
7. Enable the template feature if explicitly needed.
8. Output phases, unfinished items, and CMS/migration notes instead of just saying "completed."

What to Check After Generation

You can ask the AI to self-check the following:

Please confirm if this generator already supports:
1. full / embed dual modes
2. window.__GENERATOR_RUNTIME__
3. getPanelSchema + PanelFilter
4. Template pages only mounting the canvas and partial parameter panel

For existing generator refactors, we also recommend a "completion status" self-check:

Please report the current status using these fields:
1. Task Type: Compatibility Refactoring / Standardization Refactoring
2. Current Phase
3. Completed Items
4. Unfinished Items
5. Is Standardization Complete?
6. Compatibility and Migration Notes

Only when generator-sdk, the full runtime, full/embed, window.__GENERATOR_RUNTIME__, getPanelSchema + PanelFilter, and the required template protocol are all in place should you claim "Standardization Refactoring Complete."

If your goal is to integrate the generator into a template page, we also recommend reading:

• Runtime Contract
• HTML Runtime Starter
• Vue Runtime Starter
• Template Host Demo

Last Step: Configure in CMS

After the code is finished, you also need to complete the platform-side configuration in the CMS:

• Address: xtool Backend Management System

At a minimum, you need to configure:

• appKey
• Generator name
• Sharing-related configurations
• Credits / free quota-related configurations

Common Mistakes

Only letting the AI generate a full page

This leads to no embed mode, making it impossible to integrate into template pages stably.

Hardcoding login, export, and credits into the page

The correct way is to integrate them via generator-sdk rather than reinventing the protocol.

Rewriting parameter logic for template pages

The correct way is to have the generator return a PanelSchema, and then the template page renders partial parameters via PanelFilter.

Describing phased delivery as "completed according to skill"

If only the SDK integration, compatibility layer, or partial runtime is finished, it should be described as "phased delivery" or "compatibility refactoring complete," not "standardization refactoring complete."

One-Sentence Principle

Don't "make the page first, then add embed"; instead, "start from the runtime starter, then continue making the page."