AgentSkillsCN

document-node

生成全面的 {node_name}.example.json 文件，展示 Workscript 工作流节点的真实使用场景。在被要求记录节点、创建节点文档、生成节点示例或为工作流节点制作使用示例时使用。当子代理需要在节点开发或审查过程中创建节点文档时也使用。

SKILL.md
--- frontmatter
name: document-node
description: Generate comprehensive {node_name}.example.json files that showcase real-world usage of Workscript workflow nodes. Use when asked to document a node, create node documentation, generate node examples, or produce usage examples for workflow nodes. Also use when a subagent needs to create node documentation as part of node development or review.

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.

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

json
// 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:

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

json
// 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:

json
// 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

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

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

typescript
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