SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsnode-docs

node-docs

Writing & research

View repository

Updated 10-16 05:07

About this skill

Node Documentation Writer

Write original, beginner-friendly documentation for ComfyUI nodes. Each node is stored as an individual JSON file. Use the embedded docs as a reference source but always rewrite content — never copy-paste.

File Structure

Node data is split into per-node JSON files organized by section and category:

src/data/nodes/
  _metadata.json                              — metadata + schema_version
  comfy_nodes/<category>/<NodeName>.json      — core ComfyUI nodes (476)
  partner_nodes/<category>/<NodeName>.json    — API/partner nodes (177)
  subgraph_blueprints/<category>/<Name>.json  — subgraph blueprints (36)
  extensions/<category>/<NodeName>.json       — extension nodes (1)

The top-level directories (comfy_nodes, partner_nodes, subgraph_blueprints, extensions) match the tree pane sections. Below that, the category path matches the node's category field with spaces replaced by hyphens.

Key files

  • Per-node data: src/data/nodes/<section>/<category>/<NodeName>.json
  • Metadata: src/data/nodes/_metadata.json
  • Export data: exports/comfyui_nodes_2026-03-14_0-17-0.json (structural source of truth)
  • Embedded docs: embedded-docs/comfyui_embedded_docs/docs/<NodeName>/en.md (reference only)
  • Update plan: exports/NODE_UPDATE_PLAN.md (progress tracking)

Finding a node file

To locate a node's JSON file:

find src/data/nodes -name 'KSampler.json'
# → src/data/nodes/comfy_nodes/sampling/KSampler.json

To search across all nodes:

rg '"documentation_complete": false' src/data/nodes/ -l

Content Fields to Write

For each node, write these fields:

Field What to write Length
description Technical but clear explanation of what the node does 50–200 chars
beginner_description Plain-language explanation for someone new to ComfyUI 100–400 chars
tips.general_tips Practical advice any user should know 2–5 tips
tips.beginner_tips "Start here" guidance with specific values and settings 2–4 tips
tips.advanced_tips Power-user techniques, edge cases, combo strategies 1–4 tips (skip for simple nodes)
use_cases Concrete scenarios with context 2–4 use cases
common_errors Real problems users hit, with actionable fixes 1–4 errors
complexity_level "beginner", "intermediate", or "advanced" —
documentation_complete Set true when all content fields are filled —

Writing Standards

Voice & Audience

  • Write for people learning ComfyUI, not ML researchers
  • Use active voice: "Connect to VAE Decode" not "Should be connected to"
  • Explain WHY, not just WHAT: "Lower CFG (4–6) gives the model more creative freedom" not "CFG controls guidance strength"
  • Use analogies for complex concepts: "Think of it like adjusting the contrast on a photo" not "Modifies the latent tensor distribution"

description

One or two sentences. Technical but accessible. State what the node does and its role in a workflow.

Good: "Loads a Stable Diffusion checkpoint file containing the model weights, text encoder, and VAE needed for image generation."

Bad: "Checkpoint loader node." (too short, says nothing) Bad: Copy-pasting the export's description field verbatim.

beginner_description

Explain the node as if the reader has used ComfyUI for a week. Avoid jargon or explain it inline. Say what it does in practical terms.

Good: "This node loads the AI model that generates your images. Think of it as picking which artist you want to work with — different checkpoints produce different styles, from photorealistic to anime to oil paintings."

Bad: "Loads checkpoint files for diffusion model inference." (jargon) Bad: Repeating description with slightly different words.

tips

Each tip must be specific and actionable. Include concrete values, settings, node names, or workflows.

Good tip: "Start with euler sampler, 25 steps, CFG 7.5 — this works reliably for most models and gives good results in about 10 seconds."

Bad tip: "Experiment with different settings to find what works best." (vague, unhelpful)

Good tip: "For Flux models, set CFG to 1.0 and use the FluxGuidance node instead — Flux uses guidance differently than SD 1.5 or SDXL."

Bad tip: "Different models may require different settings." (obvious)

use_cases

Use an array of objects with scenario and context:

[
  {
    "scenario": "Text-to-image generation",
    "context": "The most common workflow — connect Empty Latent Image as input with denoise 1.0 to generate from scratch"
  }
]

common_errors

Use an array of objects with symptom and solution:

[
  {
    "symptom": "Black or completely blank images",
    "solution": "CFG scale too high (>15). Lower to 7–9 range. Also check that model, VAE, and conditioning are all connected."
  }
]

How to Use Embedded Docs

The embedded docs at embedded-docs/comfyui_embedded_docs/docs/<NodeName>/en.md are a reference source, not a template.

  1. Read the embedded doc to understand what the node does
  2. Read the input/output tables to understand parameters
  3. Note any tips, notes, or gotchas mentioned
  4. Write your own content — informed by the doc but in your own words
  5. Strip any "AI-generated" disclaimer lines

What to extract from embedded docs:

  • Technical understanding of what the node does
  • Parameter ranges, defaults, and constraints
  • Specific tips or warnings the doc mentions
  • How the node fits into workflows

What NOT to do:

  • Copy the intro paragraph as beginner_description
  • Copy input/output tables as tips
  • Use the same phrasing or structure

Workflow

Batch documenting nodes

When asked to document a set of nodes (e.g. "document the new audio nodes"):

  1. Find target nodes: find src/data/nodes -name '*.json' -path '*audio*'
  2. Group nodes by category for context
  3. For each node: a. Read the per-node JSON file b. Read the embedded doc if it exists: embedded-docs/comfyui_embedded_docs/docs/<NodeName>/en.md c. Read the export entry for structural context: check exports/comfyui_nodes_*.json d. Write all content fields e. Set documentation_complete: true
  4. Write updated JSON back to the same per-node file (edit in place)
  5. Update progress in exports/NODE_UPDATE_PLAN.md if relevant

Improving existing nodes

When asked to improve node docs:

  1. Identify nodes with weak content:
    • documentation_complete: false
    • Empty beginner_description
    • Generic tips like "Experiment with settings"
    • Empty use_cases or common_errors
    • description under 50 chars
  2. Rewrite weak fields following the standards above
  3. Keep existing good content — don't rewrite what's already well-written

Quality check

To find nodes needing work:

# Incomplete nodes
rg '"documentation_complete": false' src/data/nodes/ -l | wc -l

# Nodes where beginner_description copies description
python3 -c "
import json, os
for root, dirs, files in os.walk('src/data/nodes'):
    for f in files:
        if not f.endswith('.json') or f == '_metadata.json': continue
        path = os.path.join(root, f)
        try:
            with open(path) as fh: d = json.load(fh)
        except json.JSONDecodeError:
            print(f'BAD_JSON: {path}')
            continue
        except UnicodeDecodeError:
            continue
        desc = d.get('description','')
        bdesc = d.get('beginner_description','')
        if desc and desc == bdesc:
            print(f'LAZY: {d.get(\"name\",f)}  ({path})')
"

# Nodes missing tips
python3 -c "
import json, os
for root, dirs, files in os.walk('src/data/nodes'):
    for f in files:
        if not f.endswith('.json') or f == '_metadata.json': continue
        path = os.path.join(root, f)
        try:
            with open(os.path.join(root, f)) as fh: d = json.load(fh)
        except json.JSONDecodeError:
            print(f'BAD_JSON: {path}')
            continue
        except UnicodeDecodeError:
            continue
        if not d.get('tips',{}).get('general_tips'):
            print(d.get('name', f))
"

Category-Specific Guidance

API nodes (api node/...) — found in partner_nodes/

  • Always mention: requires API key, uses cloud processing, may have costs
  • Note the provider and what type of media it handles
  • Mention rate limits or size restrictions if the embedded doc says
  • Don't write advanced_tips unless there's something genuinely advanced

Dataset nodes (dataset/...)

  • Explain how it fits into a training data pipeline
  • Mention what formats it accepts/produces
  • Note batch processing behavior

Sampling nodes (sampling/...)

  • Explain what the sampler/scheduler does in practical terms
  • Give recommended starting values
  • Note which models it works best with
  • Compare to common alternatives (euler vs dpm++ etc.)

Latent nodes (latent/...)

  • Always mention: "Connect to VAE Decode to see the result as an image"
  • Explain the latent space concept briefly for beginners
  • Note resolution requirements if applicable

Audio nodes (audio/...)

  • Explain the audio format requirements
  • Note sample rate / channel constraints
  • Describe how it fits into audio workflows

Subagent Usage

For large batches (50+ nodes), use parallel subagents grouped by category. Each subagent gets a category batch and writes docs for all nodes in that group. This keeps context focused and produces more consistent output within a category.

Coordination: The subagents should write their results to per-node JSON files (different files per node, so no write conflicts) rather than editing a single shared plan file. A single coordinator agent can update exports/NODE_UPDATE_PLAN.md after all workers complete.