Skip to content

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:

json
{
  "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 ​

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

1.2 Method 2: Let AI Install Them ​

text
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:

text
.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:

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:

text
Help me make a new photo frame generator

or:

text
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.

If you want Compatibility Refactoring:

text
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:

text
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 ​

text
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:

text
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:

text
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:

Last Step: Configure in CMS ​

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

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."

MIT Licensed