adding-templates

name: adding-templates description: "Adds new workflow templates to the ComfyUI template repository. Guides through creating workflow JSON, thumbnails, index.json entry, bundle assignment, model embedding, and i18n sync. Use when asked to: add a template, create a new template, submit a workflow, new workflow template, add a workflow, contribute a template, import a workflow, set up a new template, register a template, onboard a template, include a new workflow, publish a template, ship a template, upload a workflow, or make a new template available. Triggers on: add template, new template, new workflow, import workflow, contribute workflow, submit template, create template."

Adding a Workflow Template

This skill walks through every step needed to add a new workflow template to the ComfyUI workflow_templates repository.

Rules

• Never modify scripts, build tooling, or CI configuration.
• Always validate after changes (see Step 7).
• Template file names must be snake_case — no spaces, dots, or special characters.
• Always run python scripts/sync/sync_bundles.py after editing bundles.json.
• Always run python scripts/sync/sync_data.py --templates-dir templates after editing templates/index.json.
• Bump the version in the root pyproject.toml before finalising.
• Use double-quotes " in all JSON files (never single-quotes).
• Ensure model download URLs produce filenames that exactly match the widgets_values entries in the workflow JSON.

Step 1 — Obtain the Workflow JSON

The user provides (or the agent locates) a .json workflow file.

• The workflow must be exported from ComfyUI via Save → Export.
• Ideally, ComfyUI was started with --disable-all-custom-nodes when creating the file so custom extensions don't inject extra metadata.
• To extract a workflow embedded in an image or video, use https://comfyui-embedded-workflow-editor.vercel.app/.

Naming: choose a snake_case name with no spaces, dots, or special characters.

your_template_name.json

Place the file in templates/.

Step 2 — Obtain and Prepare Thumbnails

Thumbnail files live in templates/ and must be named:

{template_name}-1.webp          # required — primary thumbnail
{template_name}-2.webp          # optional — needed for compareSlider / hoverDissolve

Thumbnail variant types

Preparation checklist

1. Convert to webp format (lossy ~65% quality is fine).
2. Resize to a reasonable resolution — thumbnails never fill the full screen.
3. Compress further if the file is large. EzGif works.
4. For video thumbnails, convert to animated webp before resizing.

Step 3 — Add Entry to templates/index.json

Open templates/index.json and add the template object inside the appropriate category's templates array. If no category fits, create a new category object.

Required fields

Optional fields

Example entry

{
  "name": "text_to_video_wan",
  "description": "Generate videos from text descriptions.",
  "mediaType": "image",
  "mediaSubtype": "webp",
  "tutorialUrl": "https://comfyanonymous.github.io/ComfyUI_examples/wan/"
}

Step 4 — Assign to a Bundle in bundles.json

Open bundles.json and add the template name string to the correct bundle array:

Then sync:

python scripts/sync/sync_bundles.py

Step 5 — Embed Model Metadata

For every model-loading node in the workflow JSON (e.g. UNETLoader, VAELoader, CLIPLoader), add a "models" array inside the node's "properties" object.

Each model entry has these fields:

Example

"properties": {
  "Node name for S&R": "VAELoader",
  "models": [
    {
      "name": "wan_2.1_vae.safetensors",
      "url": "https://huggingface.co/Comfy-Org/Wan_2.1_ComfyUI_repackaged/resolve/main/split_files/vae/wan_2.1_vae.safetensors?download=true",
      "hash": "2fc39d31359a4b0a64f55876d8ff7fa8d780956ae2cb13463b0223e15148976b",
      "hash_type": "SHA256",
      "directory": "vae"
    }
  ]
}

You can find model hashes on HuggingFace file pages or compute them locally.

Step 6 — Embed Node Versions (Optional)

For nodes that require a specific ComfyUI or custom-node version, add cnr_id and ver to the node's "properties":

"properties": {
  "Node name for S&R": "SaveWEBM",
  "cnr_id": "comfy-core",
  "ver": "0.3.26"
}

Step 7 — Run Sync and Validation

python scripts/sync/sync_bundles.py
python scripts/validate/validate_templates.py
python scripts/validate/validate_thumbnails.py

Fix any errors before continuing. CI will fail if bundles/manifests are out of sync.

Step 8 — Sync Translations (i18n)

python scripts/sync/sync_data.py --templates-dir templates

This propagates the new template to all locale index files (index.zh.json, index.ja.json, etc.) and updates scripts/data/i18n.json for translation tracking.

Optionally, add translations directly in scripts/data/i18n.json:

{
  "templates": {
    "your_template_name": {
      "title": {
        "en": "Your Template Title",
        "zh": "您的模板标题"
      },
      "description": {
        "en": "Your template description",
        "zh": "您的模板描述"
      }
    }
  }
}

Then re-run python scripts/sync/sync_data.py --templates-dir templates to apply.

Step 9 — Bump Version

Increment the version field in the root pyproject.toml. CI uses this to detect which subpackages changed and publishes only affected packages to PyPI.

Common User Requests

File Quick-Reference