dancing-bear: Skill for Claude Code

Validate Workflow

Validates workflow YAML files and the skill SKILL.md docs that reference them. Catches stale CLI commands, wrong --params syntax, and stage name drift before they reach CI or confuse agents at runtime.

When to Use

• Before committing new or modified workflow YAML files
• After renaming or adding stages (stage references in skills go stale)
• After adding --params to skill docs (easy to mis-spell trigger param names)
• User says "validate workflow", "check workflow commands", "lint workflows"
• As part of a PR review when workflows/ or .claude/skills/ changed

Two Layers of Validation

Layer 1 — Workflow YAML structural + command lint

# Lint one file (structure only, fast)
./bin/workflow lint workflows/code/code-review.yaml

# Lint with CLI command probing (validates ./bin/<cli> <sub> references in stage descriptions)
./bin/workflow lint workflows/code/code-review.yaml --check-commands

# Strict mode — warnings become errors
./bin/workflow lint workflows/code/code-review.yaml --check-commands --strict

# YAML output for programmatic use (this is the default format)
./bin/workflow lint workflows/code/code-review.yaml --check-commands --format yaml

Shared fragments are not runnable standalone — they carry a top-level fragment: true key and must be validated with the dedicated subcommand:

./bin/workflow validate-fragment workflows/shared/expand-coverage.yaml

Layer 2 — Skill doc correctness checks (manual)

Skill docs reference workflow files in two ways the linter cannot check:

1. ./bin/workflow run <path> --params key=value — param names must match trigger.params in the YAML
2. Stage name tables — must match stage names in the compiled DAG (including fragment prefixes)

Run these checks manually:

# Extract trigger.params from a workflow
python3 -I -c "
import yaml
d = yaml.safe_load(open('workflows/code/code-review.yaml'))
print('\n'.join((d.get('trigger') or {}).get('params', {})))
"

# List all stage names after fragment expansion (compiled DAG).
# Stage names live under groups[].stages as comma-joined strings — a bare
# `grep name:` would match the workflow name and warning keys instead.
./bin/workflow compile workflows/code/code-review.yaml --format yaml 2>/dev/null | python3 -I -c "
import sys, yaml
d = yaml.safe_load(sys.stdin)
for g in d.get('groups', []):
    for s in str(g.get('stages', '')).split(','):
        if s.strip(): print(s.strip())
"

# Extract --params keys from a skill doc (BSD grep on macOS has no -P; use -oE)
grep -oE '\-\-params [a-z_]+' .claude/skills/code-review/SKILL.md | awk '{print $2}' | sort -u