JTBD Validator Skill

What It Validates

• ✅ Frontmatter (name, description)
• ✅ Step headers (sequential, matching YAML blocks)
• ✅ YAML structure (api, operationId, inputs)
• ✅ API URNs (folder exists, spec valid)
• ✅ OperationIds (exist in API specs)
• ✅ Step dependencies (no forward references, outputs exist)

How to Use

Validate a Single File

python3 .claude/skills/jtbd-validator/scripts/validate_jtbd.py path/to/job.md .

Validate All JTBDs in a Folder

for job in skills/*/SKILL.md; do
  python3 .claude/skills/jtbd-validator/scripts/validate_jtbd.py "$job" .
done

Find All JTBD Files

find . -path "*/skills/*/SKILL.md" -type f | grep -v node_modules

Workflow

When User Requests Validation

• Specific file: Use the provided path
• All JTBDs: Find all

  skills/*/SKILL.md

  files

python3 .claude/skills/jtbd-validator/scripts/validate_jtbd.py <file> .

• ✅ PASSED: Just confirm it's valid
• ❌ FAILED: Explain errors in plain English

Example Interactions

User: Validate skills/deploy-api-with-rate-limiting/SKILL.md

You: [Runs validator]
✅ Valid - 5 steps, all references correct

User: Validate all JTBDs

You: [Finds and validates all JTBD files]
Validated 7 files:
✅ 6 passed
❌ 1 failed (broken-example.md: operation not found)

Common Errors & Fixes

• Error:

  Operation 'createApis' not found in urn:api:api-manager

• Fix: Check correct operationId in api-manager/api.yaml

• Error:

  References unknown output 'apiId' from step 1

• Fix: Add output to Step 1 or correct reference name

• Error:

  References step 3 which comes after step 2

• Fix: Steps can only reference previous steps

• Error:

  API folder not found for 'urn:api:api-mgr'

• Fix: Use correct folder name (e.g.,

  urn:api:api-manager

  )

• 0 = Valid
• 1 = Invalid

• jtbd-generator (uses this validator automatically)