workflow-validator

当用户想要验证 looplia 工作流输出、检查工件是否满足验证标准或调试验证失败时,应使用此技能。当有人说"验证此 looplia 输出"、"检查工作流输出是否有效"、"验证工件 JSON"或"调试验证失败原因"时使用。对 JSON 工件运行确定性验证脚本。主要用于手动重试/调试,因为自动验证由 PostToolUse 钩子处理。looplia 的单步 → 单技能执行器 → 多技能架构的一部分。

📖 中文导读:当用户想要验证 looplia 工作流输出、检查工件是否满足验证标准或调试验证失败时,应使用此技能。当有人说"验证此 looplia 输出"、"检查工作流输出是否有效"、"验证工件 JSON"或"调试验证失败原因"时使用。对 JSON 工件运行确定性验证脚本。主要用于手动重试/调试,因为自动验证由 PostToolUse 钩子处理。looplia 的单步 → 单技能执行器 → 多技能架构的一部分。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: workflow-validator description: | This skill should be used when the user wants to validate a looplia workflow output, check if an artifact meets validation criteria, or debug validation failures. Use when someone says "validate this looplia output", "check if the workflow output is valid", "verify the artifact JSON", or "debug why validation failed".

Runs deterministic validation scripts against JSON artifacts. Primarily used for manual retry/debugging since automatic validation is handled by PostToolUse hooks. Part of looplia's one step → one skill-executor → multiple skills architecture.

Workflow Validator Skill

Validates JSON artifacts against validation criteria using deterministic script execution.

Automatic Validation via Hook (v0.6.0)

As of v0.6.0, the PostToolUse:Write hook automatically calls this validation script whenever an artifact is written to sandbox/*/outputs/*.json.

You typically don't need to manually invoke this skill - the hook handles it.

When to Manually Use This Skill

Use this skill only in these scenarios:

  • Retrying after validation failure - when the hook blocked a write and you need to debug
  • Debugging validation issues - to see detailed check results
  • Checking artifacts outside the normal workflow - for ad-hoc validation
  • Pre-checking before write - to validate data before writing to sandbox

What This Skill Does

  • Reads validation criteria from sandbox/{id}/validation.json
  • Runs deterministic validation script (no LLM tokens consumed)
  • Returns pass/fail status with detailed check results
  • Enables workflow completion verification

Validation Process

Step 1: Read Validation Criteria

Read the validation manifest at sandbox/{id}/validation.json:

{
  "workflow": "writing-kit",
  "version": "1.0.0",
  "sandboxId": "article-2025-12-18-xk7m",
  "steps": {
    "summary": {
      "output": "outputs/summary.json",
      "validate": {
        "required_fields": ["contentId", "headline", "tldr", "keyThemes"],
        "min_quotes": 3,
        "min_key_points": 5
      },
      "validated": false
    }
  }
}

Step 2: Run Validation Script

Execute the validation script with artifact path and criteria:

bun scripts/validate.ts <artifact-path> '<criteria-json>'

Example:

bun scripts/validate.ts sandbox/podcast-2024-12-08-ai/outputs/summary.json '{"required_fields":["contentId","headline"],"min_quotes":3}'

Step 3: Parse Results

The script returns JSON with pass/fail and individual checks:

{
  "passed": true,
  "checks": [
    { "name": "has_contentId", "passed": true, "message": "OK" },
    { "name": "has_headline", "passed": true, "message": "OK" },
    { "name": "min_quotes", "passed": true, "message": "Found 5 quotes (min: 3)" }
  ]
}

Step 4: Handle Results

If validation passes:

  • Update validation.json to set validated: true for this output
  • Continue to next workflow step

If validation fails:

  • Review failed checks
  • Either retry the subagent with feedback
  • Or report the issue to the user

Validation Criteria Reference

required_fields

Array of field names that must exist in the artifact:

"required_fields": ["contentId", "headline", "tldr"]

min_quotes

Minimum number of items in importantQuotes array:

"min_quotes": 3

min_key_points

Minimum number of items in bullets or key points array:

"min_key_points": 5

min_outline_sections

Minimum number of outline sections:

"min_outline_sections": 4

has_hooks

Requires hooks array with at least one item:

"has_hooks": true

Output Format

The validation script returns:

{
  "passed": boolean,
  "checks": [
    {
      "name": "check_name",
      "passed": boolean,
      "message": "Human-readable result"
    }
  ]
}

Important Rules

  • Automatic validation via hook - Hook handles validation on write; manual use only for retry/debugging
  • Script is deterministic - No LLM context consumed
  • Update validation.json - Mark steps validated when passed (v0.6.0 uses .steps not .outputs)
  • Retry on failure - Give subagent feedback on what failed
  • Check dependencies - Ensure required steps are validated before dependent steps
  • Use exact paths - Artifact paths are relative to workspace root

Script Location

The validation script is at:

.claude/skills/workflow-validator/scripts/validate.ts

Run with Bun for TypeScript execution:

bun .claude/skills/workflow-validator/scripts/validate.ts <artifact> '<criteria>'