Claude-skill-registry flow-validation-checklist

Complete migration validation checklist for Flow to Output SDK. Use after migration to verify completeness and correctness.

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/flow-validation-checklist" ~/.claude/skills/majiayu000-claude-skill-registry-flow-validation-checklist && rm -rf "$T"

manifest: skills/data/flow-validation-checklist/SKILL.md

Migration Validation Checklist

Overview

This skill provides a comprehensive checklist to validate a completed Flow to Output SDK migration. Use this after migration to ensure nothing was missed.

When to Use This Skill

After Migration:

Verifying migration completeness
Before marking migration as done
During code review of migrated workflow

Complete Validation Checklist

1. Type Safety

All step Input/Output interfaces defined in types.ts
Workflow input/output schemas defined with Zod
Steps use typed input parameters
Zod schemas match original type definitions
All
```
z
```
imports from
```
@output.ai/core
```
(not
```
zod
```
)

Validation Commands:

# Check for wrong zod imports
grep -r "from 'zod'" src/workflows/my_workflow/
grep -r 'from "zod"' src/workflows/my_workflow/

# Should return nothing - all zod should be from @output.ai/core

# Verify types.ts has Zod schemas
grep -c "z.object" src/workflows/my_workflow/types.ts

2. Template & Prompt Conversion

All prompts extracted to
```
.prompt
```
files
YAML frontmatter includes provider and model
Template conditionals use Liquid.js (
```
{% if %}
```
not
```
{{#if}}
```
)
Variable spacing correct (
```
{{ var }}
```
not
```
{{var}}
```
)
Boolean template variables handled as strings
Prompt files follow naming convention (
```
name@version.prompt
```
)

Validation Commands:

# Check for remaining Handlebars syntax
grep -r "{{#if" src/workflows/my_workflow/
grep -r "{{/if}}" src/workflows/my_workflow/

# Should return nothing

# Check for variables without spaces
grep -r "{{[^{]" src/workflows/my_workflow/*.prompt 2>/dev/null | grep -v "{{ "

# Should return nothing - all variables should have spaces

# List all prompt files
ls src/workflows/my_workflow/*.prompt

# Verify frontmatter in each
head -10 src/workflows/my_workflow/*.prompt

3. API & Imports

All files import
```
z
```
from
```
@output.ai/core
```
```
step()
```
and
```
workflow()
```
imported from
```
@output.ai/core
```

LLM calls use

generateText()

generateObject()

from

@output.ai/llm

ValidationError

FatalError

imported from

@output.ai/core

No leftover Flow SDK imports

Validation Commands:

# Check for Flow SDK imports
grep -r "@flow/sdk" src/workflows/my_workflow/
grep -r "WorkflowScope" src/workflows/my_workflow/

# Should return nothing

# Verify correct imports
grep -r "@output.ai/core" src/workflows/my_workflow/
grep -r "@output.ai/llm" src/workflows/my_workflow/

4. File Structure

```
workflow.ts
```
contains workflow definition with
```
export default
```
```
steps.ts
```
contains all step definitions
```
types.ts
```
contains Input/Output interfaces and Zod schemas
Prompt files named
```
name@version.prompt
```
No leftover
```
activities.ts
```
(renamed to
```
steps.ts
```
)
No leftover
```
prompts.ts
```
or
```
prompts.xml
```
File imports have
```
.js
```
extension

Validation Commands:

# Check file structure
ls -la src/workflows/my_workflow/

# Expected files:
# - workflow.ts
# - steps.ts
# - types.ts
# - *.prompt files
# - scenarios/ directory (optional)

# Check for leftover files
ls src/workflows/my_workflow/activities.ts 2>/dev/null
ls src/workflows/my_workflow/prompts.ts 2>/dev/null
ls src/workflows/my_workflow/prompts.xml 2>/dev/null

# Should all return "No such file"

# Check import extensions
grep -r "from './" src/workflows/my_workflow/*.ts | grep -v ".js'"

# Should return nothing - all local imports should end with .js

5. Workflow Definition

Workflow uses
```
workflow()
```
function (not class)
Workflow has
```
name
```
property
Workflow has
```
description
```
property
Workflow uses
```
export default
```
Workflow name matches legacy name (if required)

Validation Commands:

# Check workflow definition
grep -A10 "export default workflow" src/workflows/my_workflow/workflow.ts

# Verify no class-based workflow
grep "class.*Workflow" src/workflows/my_workflow/workflow.ts

# Should return nothing

6. Step Definitions

All activities converted to steps
Steps use
```
step()
```
function
Steps have
```
inputSchema
```
defined
Steps use object parameters (not direct parameters)
Step names are descriptive

Validation Commands:

# List all steps
grep "export const.*= step" src/workflows/my_workflow/steps.ts

# Verify inputSchema for each step
grep -c "inputSchema:" src/workflows/my_workflow/steps.ts

7. Error Handling

No try-catch blocks wrapping step calls in workflow
```
ValidationError
```
used for validation failures
```
FatalError
```
used for unrecoverable errors
Errors propagate naturally (not re-wrapped)

Validation Commands:

# Check for try-catch in workflow
grep -A20 "fn: async" src/workflows/my_workflow/workflow.ts | grep "try {"

# Should return nothing or minimal results

8. Business Logic

Original workflow logic preserved
All activities converted to steps
Parameter passing maintains data flow
Conditional logic intact
Loop logic intact
External API calls preserved

Manual Review:

Compare step-by-step execution flow
Verify data transformations
Check edge case handling

9. ESLint Compliance

Validation Commands:

# Run lint
npm run lint -- src/workflows/my_workflow/

# Should pass with no errors

10. Runtime Validation

Workflow builds successfully
Workflow runs with test input
Output matches expected format
No runtime errors

Validation Commands:

# Build
npm run output:workflow:build

# Run with test input
npx output workflow run my_workflow --input '{"testKey": "testValue"}'

Quick Validation Script

Run this to check common issues:

#!/bin/bash
WORKFLOW_PATH="src/workflows/my_workflow"

echo "=== Migration Validation ==="

echo -e "\n1. Checking for wrong zod imports..."
grep -r "from 'zod'" $WORKFLOW_PATH && echo "FAIL: Found direct zod imports" || echo "PASS"

echo -e "\n2. Checking for Handlebars syntax..."
grep -r "{{#if" $WORKFLOW_PATH && echo "FAIL: Found Handlebars syntax" || echo "PASS"

echo -e "\n3. Checking for Flow SDK imports..."
grep -r "@flow/sdk" $WORKFLOW_PATH && echo "FAIL: Found Flow SDK imports" || echo "PASS"

echo -e "\n4. Checking for class-based workflow..."
grep "class.*Workflow" $WORKFLOW_PATH/workflow.ts && echo "FAIL: Found class-based workflow" || echo "PASS"

echo -e "\n5. Checking for try-catch in workflow..."
grep -A20 "fn: async" $WORKFLOW_PATH/workflow.ts | grep "try {" && echo "WARN: Found try-catch" || echo "PASS"

echo -e "\n6. Checking import extensions..."
grep "from './" $WORKFLOW_PATH/*.ts | grep -v ".js'" && echo "FAIL: Missing .js extension" || echo "PASS"

echo -e "\n7. Verifying file structure..."
[ -f "$WORKFLOW_PATH/workflow.ts" ] && echo "PASS: workflow.ts exists" || echo "FAIL: workflow.ts missing"
[ -f "$WORKFLOW_PATH/steps.ts" ] && echo "PASS: steps.ts exists" || echo "FAIL: steps.ts missing"
[ -f "$WORKFLOW_PATH/types.ts" ] && echo "PASS: types.ts exists" || echo "FAIL: types.ts missing"

echo -e "\n=== Validation Complete ==="

Related Skills

```
flow-error-zod-import
```
- Fix zod import issues
```
flow-error-try-catch-removal
```
- Remove try-catch antipattern
```
flow-error-eslint-compliance
```
- Fix ESLint issues
```
flow-conventions-folder-structure
```
- Folder structure reference