jtbd-validator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

JTBD Validator Skill

Validates Jobs-to-be-Done (JTBD) markdown files to ensure correct structure, valid API references, and proper step dependencies.

验证 Jobs-to-be-Done（JTBD）Markdown 文件，确保结构正确、API 引用有效且步骤依赖关系合理。

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)

✅ Frontmatter（name、description）
✅ 步骤标题（顺序连续，并与 YAML 块匹配）
✅ YAML 结构（api、operationId、inputs）
✅ API URN（文件夹存在、规范有效）
✅ OperationIds（存在于 API 规范中）
✅ 步骤依赖关系（不存在前向引用，输出项存在）

How to Use

使用方法

Validate a Single File

验证单个文件

bash

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

bash

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

Validate All JTBDs in a Folder

验证文件夹中的所有 JTBD

bash

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

bash

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

Find All JTBD Files

查找所有 JTBD 文件

bash

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

bash

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

Workflow

工作流

When User Requests Validation

当用户请求验证时

1. Identify files to validate:

Specific file: Use the provided path
All JTBDs: Find all
```
skills/*/SKILL.md
```
files

2. Run validator:

bash

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

3. Report results:

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

4. If errors, explain how to fix them

1. 确定要验证的文件：

指定文件：使用提供的路径
所有 JTBD：查找所有
```
skills/*/SKILL.md
```
文件

2. 运行验证器：

bash

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

3. 报告结果：

✅ PASSED：确认文件有效
❌ FAILED：使用通俗易懂的语言解释错误

4. 如果存在错误，说明修复方法

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)

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

常见错误与修复方法

Operation not found:

Error:

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

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

Missing output reference:

Error:

References unknown output 'apiId' from step 1

Fix: Add output to Step 1 or correct reference name

Forward reference:

Error:

References step 3 which comes after step 2

Fix: Steps can only reference previous steps

Invalid URN:

Error:

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

Fix: Use correct folder name (e.g.,
```
urn:api:api-manager
```
)

Exit Codes:

0 = Valid
1 = Invalid

Related Skills:

jtbd-generator (uses this validator automatically)

未找到 Operation：

错误：

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

修复：检查 api-manager/api.yaml 中正确的 operationId

缺少输出引用：

错误：

References unknown output 'apiId' from step 1

修复：为步骤 1 添加输出项，或修正引用名称

前向引用：

错误：

References step 3 which comes after step 2

修复：步骤只能引用之前的步骤

无效 URN：

错误：

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

修复：使用正确的文件夹名称，例如
```
urn:api:api-manager
```

退出代码：

0 = 有效
1 = 无效

相关 Skill：

jtbd-generator（会自动使用此验证器）