Document Node Skill

Generate production-quality

{node_name}.example.json

workflow files demonstrating correct usage of Workscript nodes.

Required Context

Before generating documentation, you MUST:

1. Read the node source file (

   .ts

   file) to understand:

   • metadata.id

     - The node type identifier

   • metadata.inputs

     - Expected configuration parameters

   • metadata.outputs

     - Output data structure

   • metadata.ai_hints

     - Purpose, when_to_use, expected_edges, post_to_state

   • execute()

     method - All conditional logic and edge returns

2. Locate the node in

   /packages/nodes/src/

   or subdirectories:
   • Core nodes:

     /packages/nodes/src/{NodeName}.ts

   • Data nodes:

     /packages/nodes/src/data/{NodeName}.ts

   • Custom nodes:

     /packages/nodes/src/custom/{integration}/{NodeName}.ts

Output Format

Create file:

{node_name}.example.json

in same directory as the node source.

{
  "id": "{node-id}-examples",
  "name": "{NodeName} Examples",
  "version": "1.0.0",
  "description": "Comprehensive examples demonstrating all {NodeName} capabilities",
  "initialState": { /* Realistic test data */ },
  "workflow": [ /* Inline nested configuration examples */ ]
}

Critical Rules

Rule 1: Sequential Feature Showcase (NOT Deep Nesting)

For documentation examples, use a flat sequential array where each step demonstrates a different feature of the node being documented. This makes examples clear and easy to understand.

DO NOT create deeply nested workflows - even if they are technically correct, they obscure the features being demonstrated.

// WRONG - Deeply nested (hard to read, obscures individual features)
{
  "workflow": [
    {
      "extractText": {
        "method": "extractAll",
        "extractType": "email",
        "success?": {
          "extractText": {
            "method": "extractAll",
            "extractType": "url",
            "success?": {
              "extractText": {
                "method": "regex",
                "pattern": "...",
                "success?": {
                  "log": { "message": "Done" }
                }
              }
            }
          }
        }
      }
    }
  ]
}

// CORRECT - Sequential steps showcasing each feature clearly
{
  "workflow": [
    {
      "extractText": {
        "method": "extractAll",
        "field": "emailText",
        "extractType": "email",
        "outputField": "allEmails",
        "success?": "log"
      }
    },
    {
      "extractText": {
        "method": "extractSpecific",
        "field": "emailText",
        "extractType": "email",
        "occurrence": 0,
        "outputField": "primaryEmail",
        "success?": "log"
      }
    },
    {
      "extractText": {
        "method": "regex",
        "field": "productData",
        "pattern": "Product: ([A-Z0-9]+)",
        "flags": "g",
        "outputField": "productIds",
        "success?": "log"
      }
    },
    {
      "log": {
        "message": "All examples completed!",
        "results": "$.allEmails"
      }
    }
  ]
}

Key principles for documentation examples:

• Each workflow step = one feature/operation demonstration
• Use simple edge terminations (

  "success?": "log"

  ) not deep nesting
• Group related examples by operation type in sequence
• End with a summary log showing all collected results
• Edges CAN use string references like

  "log"

  in documentation examples

Rule 2: Realistic Initial State

Create domain-appropriate test data:

{
  "initialState": {
    "products": [
      { "id": 1, "name": "Laptop", "price": 999.99, "inStock": true, "category": "Electronics" },
      { "id": 2, "name": "Mouse", "price": 29.99, "inStock": false, "category": "Electronics" }
    ],
    "users": [
      { "id": 1, "name": "Alice", "email": "alice@example.com", "role": "admin" }
    ]
  }
}

Rule 3: Demonstrate ALL Edges

For each node, show workflows that trigger each possible edge:

// Node with success/error/found/not_found edges
{
  "database": {
    "operation": "find",
    "table": "users",
    "query": { "id": "$.userId" },
    "found?": { /* next node inline */ },
    "not_found?": { /* handle missing */ },
    "error?": { /* handle error */ }
  }
}

Rule 4: Show All Operations

If the node supports multiple operations, demonstrate each:

// Math node - show add, subtract, multiply, divide
// Filter node - show equals, contains, gt, lt, between, regex
// Transform node - show stringify, parse, uppercase, lowercase

Rule 5: Edge Naming with

?

Suffix

Edges always end with

?

:

• success?

  ,

  error?

  ,

  found?

  ,

  not_found?

• true?

  ,

  false?

  ,

  valid?

  ,

  invalid?

• exists?

  ,

  not_exists?

  ,

  passed?

  ,

  filtered?

Generation Process

1. Read node source file - Extract metadata and execute logic
2. Identify all operations - List every operation/mode the node supports
3. Identify all edges - List every edge the node can return
4. Design initial state - Create realistic test data matching node inputs
5. Create examples - One workflow section per major use case
6. Add documentation logs - Include log nodes showing results

Example Structure Template

{
  "id": "{node-id}-examples",
  "name": "{NodeName} Examples",
  "version": "1.0.0",
  "description": "Comprehensive examples demonstrating all {NodeName} capabilities",
  "initialState": {
    "/* Realistic domain data matching node inputs - provide multiple data sources to showcase different features */"
  },
  "workflow": [
    {
      "{node-id}": {
        "/* Example 1: Basic usage - simplest configuration */",
        "outputField": "example1Result",
        "success?": "log"
      }
    },
    {
      "{node-id}": {
        "/* Example 2: Different operation/mode */",
        "outputField": "example2Result",
        "success?": "log"
      }
    },
    {
      "{node-id}": {
        "/* Example 3: Advanced usage with all options */",
        "outputField": "example3Result",
        "success?": "log"
      }
    },
    {
      "{node-id}": {
        "/* Example 4: Edge case or alternative configuration */",
        "outputField": "example4Result",
        "success?": "log"
      }
    },
    {
      "log": {
        "message": "All {NodeName} examples completed successfully!",
        "example1Result": "$.example1Result",
        "example2Result": "$.example2Result",
        "example3Result": "$.example3Result",
        "example4Result": "$.example4Result"
      }
    }
  ]
}

Template guidelines:

• Add one workflow step per feature/operation you want to demonstrate
• Each step should have a unique

  outputField

  to store results
• Use

  "success?": "log"

  as a simple edge terminator (not deep nesting!)
• Final log step summarizes all results using state references

State References

Use

$.

syntax for state access:

• $.products

  - Access state.products

• $.user.name

  - Access nested state.user.name

• $.filterPassed

  - Access node output stored in state

State Keys Written by Nodes

Common node state outputs (reference from node's

ai_hints.post_to_state

):

• math:

  mathResult

• logic:

  logicResult

• filter:

  filterPassed

  ,

  filterFiltered

  ,

  filterStats

• sort:

  sortedItems

• validateData:

  validationResult

  ,

  validationErrors

• editFields:

  editFieldsResult

  ,

  fieldsModified

• database:

  dbInserted

  ,

  dbRecord

  ,

  dbUpdated

  ,

  dbDeleted

  ,

  dbRecords

• filesystem:

  fileContent

  ,

  fileWritten

  ,

  fileExists

Quality Checklist

Before finalizing, verify:

• Read the actual node source file
• Used sequential flat array pattern (NOT deeply nested workflows)
• Each workflow step showcases ONE feature/operation of the node
• Created realistic initialState with multiple data sources for different features
• Demonstrated all operations/modes the node supports
• Showed all edge paths (success, error, and conditional edges)
• Used correct edge naming with

  ?

  suffix
• Used

  "success?": "log"

  as simple terminators (not deep nesting)
• Referenced correct state keys (from ai_hints.post_to_state)
• Each step writes to unique outputField for clear result tracking
• Final summary log shows all collected results
• File saved as

  {node_id}.example.json

  in node's directory

Quick Reference: Workflow JSON Schema

{
  "id": "string (required, pattern: ^[a-zA-Z0-9_-]+$)",
  "name": "string (required)",
  "version": "string (required, pattern: ^\\d+\\.\\d+\\.\\d+$)",
  "description": "string (optional)",
  "initialState": "object (optional)",
  "workflow": "array (required, min: 1 item)"
}

Reference: Reading Node Source

When reading a node's

.ts

file, extract:

metadata = {
  id: 'node-id',           // Use this in workflow
  name: 'Node Name',       // Use in description
  inputs: ['param1'],      // Config parameters
  outputs: ['result'],     // Edge data keys
  ai_hints: {
    purpose: '...',
    when_to_use: '...',
    expected_edges: ['success', 'error'],  // All possible edges
    example_config: '...',
    post_to_state: ['stateKey']            // State keys written
  }
};

Analyze the

execute()

method to understand:

• All

  return { edgeName: () => ({...}) }

  statements
• Conditional logic that determines which edge is returned
• Required vs optional configuration parameters