flow-conventions-folder-structure

growthxai 的头像作者 growthxai

验证并修复输出 SDK 工作流程的文件夹结构。用于确保迁移的工作流程遵循正确的结构约定。

📖 中文导读:验证并修复输出 SDK 工作流程的文件夹结构。用于确保迁移的工作流程遵循正确的结构约定。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: flow-conventions-folder-structure description: Validate and fix folder structure for Output SDK workflows. Use to ensure migrated workflows follow the correct structure conventions. allowed-tools: [Bash, Read, Grep, Glob]

Output SDK Folder Structure Conventions

Overview

This skill documents the required folder structure for Output SDK workflows and helps validate/fix structure issues after migration.

When to Use This Skill

After Migration:

  • Validating folder structure is correct
  • Fixing structure issues
  • Renaming files to match conventions

During Setup:

  • Creating new workflow directories
  • Understanding project organization

Folder Structure Comparison

Flow SDK (Old Structure)

src/
└── workflows/
    └── example_workflow/
        ├── activities.ts      # Activity functions
        ├── helpers.ts         # Optional helpers
        ├── prompts.ts         # JS prompt arrays
        ├── prompts.xml        # XML prompts
        ├── readme.xml         # Documentation
        ├── types.ts           # Type definitions
        └── workflow.ts        # Workflow class

Output SDK (New Structure)

src/
└── workflows/
    └── example_workflow/
        ├── workflow.ts              # Workflow function (export default)
        ├── steps.ts                 # Step definitions
        ├── types.ts                 # Types + Zod schemas
        ├── analyzeDocument@v1.prompt   # Prompt files
        ├── generateSummary@v1.prompt
        └── scenarios/               # Test input files
            ├── basic_input.json
            └── full_options.json

File Naming Conventions

Workflow Folder

  • Use snake_case for folder names
  • Match the workflow name
# Correct
user_onboarding/
generate_report/
analyze_document/

# Wrong
userOnboarding/
GenerateReport/
analyze-document/

Core Files

File Naming Purpose
workflow.ts Exact name Workflow definition
steps.ts Exact name All step definitions
types.ts Exact name Types and Zod schemas

Prompt Files

Format: {descriptiveName}@{version}.prompt

# Correct
analyzeDocument@v1.prompt
generateSummary@v1.prompt
extractEntities@v2.prompt

# Wrong
analyze.prompt           # Missing version
analyzeDocument.txt      # Wrong extension
analyze-document@v1.md   # Wrong extension

Scenario Files

Format: {descriptive_name}.json

# Correct
basic_input.json
full_options.json
edge_case_empty.json
question_ada_lovelace.json

# Wrong
test1.json              # Not descriptive
BasicInput.json         # Not snake_case

Required vs Optional Files

Required Files

File Must Exist Purpose
workflow.ts Yes Workflow entry point
steps.ts Yes (if steps exist) Step definitions
types.ts Yes Schemas and types

Optional Files/Folders

File/Folder Optional Purpose
*.prompt If LLM calls Prompt templates
scenarios/ Recommended Test inputs
helpers.ts If needed Utility functions

Files to Remove After Migration

File Action
activities.ts Rename to steps.ts or delete after conversion
prompts.ts Delete after converting to .prompt files
prompts.xml Delete after converting to .prompt files
readme.xml Can keep for reference or delete

Validation Commands

Check Folder Structure

WORKFLOW="src/workflows/my_workflow"

# List all files
ls -la $WORKFLOW/

# Check for required files
[ -f "$WORKFLOW/workflow.ts" ] && echo "✓ workflow.ts" || echo "✗ workflow.ts missing"
[ -f "$WORKFLOW/steps.ts" ] && echo "✓ steps.ts" || echo "✗ steps.ts missing"
[ -f "$WORKFLOW/types.ts" ] && echo "✓ types.ts" || echo "✗ types.ts missing"

# Check for leftover files
[ -f "$WORKFLOW/activities.ts" ] && echo "⚠ activities.ts should be removed" || echo "✓ No activities.ts"
[ -f "$WORKFLOW/prompts.ts" ] && echo "⚠ prompts.ts should be removed" || echo "✓ No prompts.ts"
[ -f "$WORKFLOW/prompts.xml" ] && echo "⚠ prompts.xml should be removed" || echo "✓ No prompts.xml"

Check Folder Naming

# List workflow folders
ls -d src/workflows/*/

# Check for non-snake_case folders
ls -d src/workflows/*/ | while read dir; do
  name=$(basename "$dir")
  if [[ "$name" =~ [A-Z] ]] || [[ "$name" =~ "-" ]]; then
    echo "⚠ Non-snake_case folder: $name"
  fi
done

Check Prompt File Naming

# List prompt files
ls src/workflows/my_workflow/*.prompt 2>/dev/null

# Check for version in prompt names
for f in src/workflows/my_workflow/*.prompt; do
  if [[ ! "$f" =~ @v[0-9]+\.prompt$ ]]; then
    echo "⚠ Missing version: $f"
  fi
done

Fixing Structure Issues

Rename activities.ts to steps.ts

mv src/workflows/my_workflow/activities.ts src/workflows/my_workflow/steps.ts

Create scenarios directory

mkdir -p src/workflows/my_workflow/scenarios

Fix folder naming

# Rename from camelCase to snake_case
mv src/workflows/userOnboarding src/workflows/user_onboarding

Remove old files

rm src/workflows/my_workflow/prompts.ts
rm src/workflows/my_workflow/prompts.xml

Complete Example

Before Migration

src/workflows/userReport/
├── activities.ts
├── helpers.ts
├── prompts.ts
├── prompts.xml
├── readme.xml
├── types.ts
└── workflow.ts

After Migration

src/workflows/user_report/      # Renamed to snake_case
├── workflow.ts                 # Converted to workflow()
├── steps.ts                    # Converted from activities.ts
├── types.ts                    # Added Zod schemas
├── generateReport@v1.prompt    # Converted from prompts.ts
├── formatOutput@v1.prompt
└── scenarios/                  # NEW
    ├── daily_report.json
    ├── weekly_report.json
    └── full_options.json

Project-Wide Structure

src/
├── workflows/
│   ├── user_onboarding/
│   │   ├── workflow.ts
│   │   ├── steps.ts
│   │   ├── types.ts
│   │   ├── welcome@v1.prompt
│   │   └── scenarios/
│   ├── generate_report/
│   │   ├── workflow.ts
│   │   ├── steps.ts
│   │   ├── types.ts
│   │   ├── analyze@v1.prompt
│   │   └── scenarios/
│   └── shared_steps/           # Optional: shared steps
│       └── shared_steps.ts
├── shared/                     # Optional: shared utilities
│   ├── types.ts
│   └── helpers.ts
└── index.ts                    # Exports

Validation Checklist

  • Workflow folder uses snake_case
  • workflow.ts exists
  • steps.ts exists (if workflow has steps)
  • types.ts exists
  • Prompt files use name@version.prompt format
  • No leftover activities.ts
  • No leftover prompts.ts or prompts.xml
  • scenarios/ directory exists (recommended)
  • Scenario files use snake_case.json format
  • flow-validation-checklist - Complete migration validation
  • flow-create-scenario-files - Creating test scenarios
  • flow-analyze-workflow-structure - Pre-migration analysis