comfyui-node-update

Files (1)

• SKILL.md

SKILL.md (first lines)

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

```text
src/data/nodes/
  _metadata.json                              — metadata + schema_version
  comfy_nodes/<category>/<NodeName>.json      — core ComfyUI nodes (511)
  partner_nodes/<category>/<NodeName>.json    — API/partner nodes (203)
  subgraph_blueprints/<category>/<Name>.json  — subgraph blueprints (65)
  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_*.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)
- **Extraction script:** `scripts/extract-comfyui-nodes.sh` (pulls from running ComfyUI)
- **Import script:** `scripts/import-new-nodes.sh` (creates skeletal files, updates metadata)

### Finding a node file

To locate a node's JSON file:
```bash
find src/data/nodes -name 'KSampler.json'
# → src/data/nodes/comfy_nodes/sampling/KSampler.json
```

To search across all nodes:
```bash
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`:

```json
[
  {

From espennilsen/pi, MIT.

More from espennilsen/pi