ProcessFlow Code Snippet Generation Skill

This guide helps you generate ProcessFlow step snippets that pass sandbox validation and remain reliable in production. It focuses on practical authoring rules, a predictable return contract, and a repeatable workflow you can apply when creating or updating step code.

Start with the right step context

A high-quality snippet starts with complete step context, not just a prompt to “write code.” Before generation, confirm the step goal, required input fields from process_input, expected output fields for downstream steps, and any integration identifiers that the step depends on.

If you are editing existing code, preserve valid behavior and apply minimal, targeted changes. This avoids regressions and keeps process history understandable for teams operating the workflow.

Follow sandbox-safe authoring rules

ProcessFlow snippets should remain flat and procedural, with no class or function definitions. Keep logic linear, validate required input early, and avoid low-level primitives that the sandbox blocks, such as direct shell execution, include/require usage, raw cURL primitives, and output/debug functions like echo or print_r.

For service access, prefer injected platform services such as tenantDb, api, integration, keystore, and files where appropriate. These services enforce tenant boundaries and align your snippet with guardrails documented in Process step code guide and Process Environment Variables.

Use a consistent success and error contract

Every snippet should return a structured object for both success and failure paths. Returning predictable shapes makes downstream steps easier to design and gives operators clear error codes for triage.

type SnippetResult =
  | { success: true; data: { normalized_email: string; processed_at: string } }
  | { success: false; error: { code: string; message: string; details?: string }; data: null };

function buildResult(input: { email?: string }): SnippetResult {
  if (!input.email) {
    return {
      success: false,
      error: { code: "MISSING_EMAIL", message: "email is required" },
      data: null,
    };
  }

  return {
    success: true,
    data: {
      normalized_email: input.email.trim().toLowerCase(),
      processed_at: new Date().toISOString(),
    },
  };
}

Apply integration-safe generation patterns

When a snippet needs external data, use integration or api and treat integration failures as controlled error return paths. Use try/catch only around operations that can throw, and keep business validation as explicit, readable guard clauses.

For secrets, load values with keystore.get(...) and return a clear MISSING_SECRET-style error when configuration is missing. This prevents hidden runtime failures and speeds up environment troubleshooting.

Verify generated behavior through ProcessFlow API

After generating or updating a snippet, run an execution test through the ProcessFlow API to confirm the step contract and error handling behave as expected. Include tenant and authorization headers so the test path matches production behavior.

curl -X POST "https://<YOUR_DOMAIN>/api/v1/processflow?action=execute-process" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "process_id": "<PROCESS_ID>",
    "input_data": {
      "email": "agent.test@example.com"
    },
    "async": false
  }'

{
  "success": true,
  "data": {
    "execution_id": "exec_4aa021f3",
    "status": "completed"
  }
}

Use a repeatable generation workflow

A practical workflow is to capture input and output contracts, draft with sandbox-safe services, run a self-check against forbidden constructs, and then validate with execution tests. Keeping snippets concise and scoped to one step responsibility improves maintainability and reduces guardrail failures.

Use this skill as a generation baseline for step snippets only. It is intentionally focused on ProcessFlow step code and does not define broader multi-file application architecture patterns.