jtbd-generator
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseJTBD Generator Skill
JTBD 生成器 Skill
This skill generates complete JTBD (Jobs-to-be-Done) markdown files from user-provided step descriptions. It discovers the correct API operations, maps data flow between steps, and produces validated, hybrid-format JTBD files.
此 Skill 根据用户提供的步骤描述生成完整的 JTBD(Jobs-to-be-Done)Markdown 文件。它会发现正确的 API 操作、映射步骤之间的数据流,并生成经过验证的混合格式 JTBD 文件。
How to Use
使用方法
When the user wants to create a JTBD, they will provide:
- Prerequisites: Conditions that must be met (e.g., "user logged in", "API asset exists in Exchange")
- Steps: List of operations in natural language (e.g., "Get GAV from Exchange", "Create API in API Manager")
You will guide them through discovery, validation, and generation.
当用户想要创建 JTBD 时,他们将提供:
- 前置条件:必须满足的条件(例如“用户已登录”“Exchange 中存在 API 资产”)
- 步骤:以自然语言描述的操作列表(例如“从 Exchange 获取 GAV”“在 API Manager 中创建 API”)
你将引导用户完成发现、验证和生成过程。
Workflow
工作流
Step 1: Parse User Input
第 1 步:解析用户输入
Extract the user's intent:
- Job purpose/title
- Prerequisites
- Step descriptions (in natural language)
If anything is unclear, ask clarifying questions:
- What's the goal of this workflow?
- What should happen in each step?
- Are there specific APIs you want to use?
提取用户意图:
- 工作目标/标题
- 前置条件
- 步骤描述(使用自然语言)
如果有任何不清楚的地方,请提出澄清问题:
- 此工作流的目标是什么?
- 每个步骤应该执行什么操作?
- 是否要使用特定的 API?
Step 2: Discover Operations
第 2 步:发现操作
For each step description:
-
Search for matching operations:python
import sys from pathlib import Path # Add JTBD generator library to path sys.path.insert(0, '.claude/skills/jtbd-generator') from lib import api_discovery # Search for operations matching the description results = api_discovery.search_operations( "create api", # User's description keywords None, # Search all APIs, or specify URN like "urn:api:api-manager" repo_root=Path(".") ) # Show top 3-5 matches for op in results[:5]: print(f"{op['score']:.2f} - {op['operationId']} ({op['api']})") print(f" {op['method']} {op['path']}") print(f" {op['summary']}") -
Present options to user:
- Show the top matches with scores
- Include operation summary and API
- Ask user to confirm or choose
-
Get operation details:python
# Once user confirms, get full details details = api_discovery.get_operation_details( api_urn="urn:api:api-manager", operation_id="createOrganizationsEnvironmentsApis", repo_root=Path(".") ) print(f"Parameters: {len(details['parameters'])}") print(f"Method: {details['method']} {details['path']}") -
Store selection:
- Step number
- Step name (user-provided)
- API URN
- Operation ID
- Operation details
对于每个步骤描述:
-
搜索匹配的操作:python
import sys from pathlib import Path # Add JTBD generator library to path sys.path.insert(0, '.claude/skills/jtbd-generator') from lib import api_discovery # Search for operations matching the description results = api_discovery.search_operations( "create api", # User's description keywords None, # Search all APIs, or specify URN like "urn:api:api-manager" repo_root=Path(".") ) # Show top 3-5 matches for op in results[:5]: print(f"{op['score']:.2f} - {op['operationId']} ({op['api']})") print(f" {op['method']} {op['path']}") print(f" {op['summary']}") -
向用户提供选项:
- 显示得分最高的匹配项
- 包含操作摘要和 API
- 请用户确认或选择
-
获取操作详情:python
# Once user confirms, get full details details = api_discovery.get_operation_details( api_urn="urn:api:api-manager", operation_id="createOrganizationsEnvironmentsApis", repo_root=Path(".") ) print(f"Parameters: {len(details['parameters'])}") print(f"Method: {details['method']} {details['path']}") -
保存选择结果:
- 步骤编号
- 步骤名称(用户提供)
- API URN
- Operation ID
- 操作详情
Step 3: Analyze Parameters & Data Flow
第 3 步:分析参数与数据流
For each step (in order from 1 to N):
-
Analyze parameters:python
from lib import parameter_analyzer # Build inputs considering previous steps inputs = parameter_analyzer.build_all_inputs( api_urn="urn:api:api-manager", operation_id="createOrganizationsEnvironmentsApis", repo_root=Path("."), previous_steps=previous_steps # List of already-processed steps ) # Review detected sources for param_name, input_def in inputs.items(): if 'from' in input_def: source = input_def['from'] print(f"{param_name}: from {source.get('api', source.get('step'))}") elif input_def.get('userProvided'): print(f"{param_name}: user-provided") -
Suggest outputs:python
from lib import response_analyzer # Suggest outputs considering next steps outputs = response_analyzer.analyze_response_for_operation( api_urn="urn:api:api-manager", operation_id="createOrganizationsEnvironmentsApis", repo_root=Path("."), next_steps=remaining_steps # Steps not yet processed ) # Show suggestions for output in outputs: print(f"{output['name']}: {output['path']}") if 'used_by' in output: print(f" → Used by: {', '.join(output['used_by'])}") -
Confirm with user:
- Show detected data flow
- Highlight any user-provided parameters
- Ask if adjustments are needed
按从 1 到 N 的顺序,针对每个步骤执行以下操作:
-
分析参数:python
from lib import parameter_analyzer # Build inputs considering previous steps inputs = parameter_analyzer.build_all_inputs( api_urn="urn:api:api-manager", operation_id="createOrganizationsEnvironmentsApis", repo_root=Path("."), previous_steps=previous_steps # List of already-processed steps ) # Review detected sources for param_name, input_def in inputs.items(): if 'from' in input_def: source = input_def['from'] print(f"{param_name}: from {source.get('api', source.get('step'))}") elif input_def.get('userProvided'): print(f"{param_name}: user-provided") -
建议输出:python
from lib import response_analyzer # Suggest outputs considering next steps outputs = response_analyzer.analyze_response_for_operation( api_urn="urn:api:api-manager", operation_id="createOrganizationsEnvironmentsApis", repo_root=Path("."), next_steps=remaining_steps # Steps not yet processed ) # Show suggestions for output in outputs: print(f"{output['name']}: {output['path']}") if 'used_by' in output: print(f" → Used by: {', '.join(output['used_by'])}") -
与用户确认:
- 展示检测到的数据流
- 突出显示所有由用户提供的参数
- 询问是否需要调整
Step 4: Generate JTBD Structure
第 4 步:生成 JTBD 结构
-
Create kebab-case name:python
from lib.utils import kebab_case name = kebab_case("Deploy API with Omni Gateway") # Result: "deploy-api-with-flex-gateway" -
Build YAML blocks for each step:python
from lib import jtbd_builder yaml_block = jtbd_builder.build_step_yaml( api_urn="urn:api:api-manager", operation_id="createOrganizationsEnvironmentsApis", inputs=inputs, outputs=outputs ) -
Generate prose sections:Use your intelligence to write:
- Overview: Action-oriented description (start with verb: "Deploys...", "Creates...", "Configures...")
- What you'll build: Clear outcome statement
- Step descriptions: Explain what each step does and why
- What you'll need: Prerequisites for each step
- What happens next: Outcomes and connections to next steps
Quality guidelines:- Be conversational and helpful
- Explain the "why", not just the "what"
- Connect steps logically
- Anticipate common questions
-
Build complete markdown:python
from lib import jtbd_builder # Prepare step definitions steps = [] for i, step_info in enumerate(step_definitions, 1): step_md = jtbd_builder.build_step_markdown( step_number=i, step_name=step_info['name'], step_description="[Your prose explanation]", operation_summary=step_info['operation_summary'], yaml_block=step_info['yaml_block'], what_you_need=step_info.get('what_you_need'), what_happens_next="[Your explanation of outcomes]" ) steps.append({'markdown': step_md}) # Assemble complete JTBD jtbd_content = jtbd_builder.build_complete_jtbd( name="deploy-api-with-flex-gateway", description="Deploy API instance to Omni Gateway. Use when deploying APIs to Omni Gateway, setting up API instances, or connecting Exchange assets to gateways.", title="Deploy API with Omni Gateway", overview="Deploys an API instance to a Omni Gateway by retrieving asset details from Exchange, discovering available gateway targets, and creating the API instance in API Manager with the proper configuration.", what_youll_build="An API instance connected to your Omni Gateway target", prerequisites=[ "**Authentication** - Valid Bearer token for Anypoint Platform with API Manager and Exchange permissions", "**Resources** - API asset published in Exchange and Omni Gateway deployed" ], steps=steps, completion_items=[ "Asset retrieved from Exchange", "Gateway target identified", "API instance created in API Manager" ], what_youve_built="✅ **API Deployment** - Connected Exchange asset to API Manager, configured Omni Gateway as target, API ready for policy configuration", next_steps=[ "**Apply Policies** - Add security policies (OAuth2, IP allowlist) and configure rate limiting", "**Test API** - Verify endpoint is accessible and test through gateway" ] )
-
创建 kebab-case 名称:python
from lib.utils import kebab_case name = kebab_case("Deploy API with Omni Gateway") # Result: "deploy-api-with-flex-gateway" -
为每个步骤构建 YAML 块:python
from lib import jtbd_builder yaml_block = jtbd_builder.build_step_yaml( api_urn="urn:api:api-manager", operation_id="createOrganizationsEnvironmentsApis", inputs=inputs, outputs=outputs ) -
生成说明性章节:运用你的理解能力编写:
- 概述:以动作导向的描述(以动词开头:“部署……”“创建……”“配置……”)
- 你将构建什么:清晰的结果陈述
- 步骤说明:解释每个步骤执行什么操作及其原因
- 你需要什么:每个步骤的前置条件
- 接下来会发生什么:执行结果及其与后续步骤的关联
质量指南:- 保持对话式且乐于助人
- 解释“为什么”,而不只是说明“做什么”
- 在逻辑上连接各个步骤
- 预判常见问题
-
构建完整的 Markdown:python
from lib import jtbd_builder # Prepare step definitions steps = [] for i, step_info in enumerate(step_definitions, 1): step_md = jtbd_builder.build_step_markdown( step_number=i, step_name=step_info['name'], step_description="[Your prose explanation]", operation_summary=step_info['operation_summary'], yaml_block=step_info['yaml_block'], what_you_need=step_info.get('what_you_need'), what_happens_next="[Your explanation of outcomes]" ) steps.append({'markdown': step_md}) # Assemble complete JTBD jtbd_content = jtbd_builder.build_complete_jtbd( name="deploy-api-with-flex-gateway", description="Deploy API instance to Omni Gateway. Use when deploying APIs to Omni Gateway, setting up API instances, or connecting Exchange assets to gateways.", title="Deploy API with Omni Gateway", overview="Deploys an API instance to a Omni Gateway by retrieving asset details from Exchange, discovering available gateway targets, and creating the API instance in API Manager with the proper configuration.", what_youll_build="An API instance connected to your Omni Gateway target", prerequisites=[ "**Authentication** - Valid Bearer token for Anypoint Platform with API Manager and Exchange permissions", "**Resources** - API asset published in Exchange and Omni Gateway deployed" ], steps=steps, completion_items=[ "Asset retrieved from Exchange", "Gateway target identified", "API instance created in API Manager" ], what_youve_built="✅ **API Deployment** - Connected Exchange asset to API Manager, configured Omni Gateway as target, API ready for policy configuration", next_steps=[ "**Apply Policies** - Add security policies (OAuth2, IP allowlist) and configure rate limiting", "**Test API** - Verify endpoint is accessible and test through gateway" ] )
Step 5: Validate
第 5 步:验证
Run the validator to ensure correctness:
bash
python3 .claude/skills/jtbd-generator/scripts/validate_jtbd.py /tmp/generated-job.md .If validation fails:
- Explain the error in plain English
- Auto-fix when possible:
- Add missing outputs (common IDs)
- Correct step references
- Generate basic descriptions
- Regenerate and validate again
If validation succeeds:
- Show success message
- Proceed to save
运行验证器以确保正确性:
bash
python3 .claude/skills/jtbd-generator/scripts/validate_jtbd.py /tmp/generated-job.md .如果验证失败:
- 用通俗易懂的语言解释错误
- 尽可能自动修复:
- 添加缺失的输出(常见 ID)
- 修正步骤引用
- 生成基础说明
- 重新生成并再次验证
如果验证成功:
- 显示成功消息
- 继续保存
Step 6: Save & Confirm
第 6 步:保存并确认
-
Determine save location:
- Default:
skills/{name}/SKILL.md - Ask user if unsure
- Default:
-
Save the file:python
from pathlib import Path output_dir = Path("skills/deploy-api-with-flex-gateway") output_dir.mkdir(parents=True, exist_ok=True) output_path = output_dir / "SKILL.md" output_path.write_text(jtbd_content) -
Confirm with user:
- Show file path
- Mention validation status
- Suggest next actions
-
Suggest related workflows:
- Based on the APIs used
- Based on similar existing JTBDs
- Based on common next steps
-
确定保存位置:
- 默认位置:
skills/{name}/SKILL.md - 如果不确定,请询问用户
- 默认位置:
-
保存文件:python
from pathlib import Path output_dir = Path("skills/deploy-api-with-flex-gateway") output_dir.mkdir(parents=True, exist_ok=True) output_path = output_dir / "SKILL.md" output_path.write_text(jtbd_content) -
与用户确认:
- 展示文件路径
- 说明验证状态
- 建议后续操作
-
建议相关工作流:
- 根据所使用的 API
- 根据相似的现有 JTBD
- 根据常见后续步骤
Example Interaction
交互示例
User: Create a JTBD with these prerequisites: user logged in, API asset in Exchange.
Steps: 1) Get GAV from Exchange, 2) Get omni gateway targets, 3) Create API in api-manager.
You: I'll create a workflow for deploying an API with a Omni Gateway target.
Let me find the right operations for each step...
[Calls search_operations for each step]
I found these operations:
Step 1: Get GAV from Exchange
→ getAssetsByGroupidByAssetid (urn:api:exchange-experience)
GET /assets/{groupId}/{assetId}
Score: 0.85
Step 2: Get omni gateway targets
→ getOrganizationsByOrganizationidEnvironmentsByEnvironmentidGateways (urn:api:flex-gateway-manager)
GET /organizations/{organizationId}/environments/{environmentId}/gateways
Score: 0.78
Step 3: Create API in api-manager
→ createOrganizationsEnvironmentsApis (urn:api:api-manager)
POST /organizations/{organizationId}/environments/{environmentId}/apis
Score: 0.92
Does this match your intent?
User: Yes
You: Building the workflow...
[Analyzes parameters and data flow]
Data flow detected:
✓ Step 1 outputs: groupId, assetId, version
✓ Step 2 outputs: gatewayId
✓ Step 3 uses: groupId, assetId, version (from Step 1), gatewayId (from Step 2)
[Generates complete JTBD with prose]
Generated JTBD:
- Name: deploy-api-with-flex-gateway
- Steps: 3
- Prerequisites: User authentication, Exchange asset, Omni Gateway
[Validates]
Validation: ✅ PASSED
Save to skills/deploy-api-with-flex-gateway/SKILL.md?
User: Yes
You: ✅ Saved successfully!
File: skills/deploy-api-with-flex-gateway/SKILL.md
Next steps:
- Review the generated workflow
- Test with: python3 .claude/skills/jtbd-generator/scripts/validate_jtbd.py skills/deploy-api-with-flex-gateway/SKILL.md .
- Related workflows: deploy-api-with-rate-limiting, setup-multi-upstream-routingUser: Create a JTBD with these prerequisites: user logged in, API asset in Exchange.
Steps: 1) Get GAV from Exchange, 2) Get omni gateway targets, 3) Create API in api-manager.
You: I'll create a workflow for deploying an API with a Omni Gateway target.
Let me find the right operations for each step...
[Calls search_operations for each step]
I found these operations:
Step 1: Get GAV from Exchange
→ getAssetsByGroupidByAssetid (urn:api:exchange-experience)
GET /assets/{groupId}/{assetId}
Score: 0.85
Step 2: Get omni gateway targets
→ getOrganizationsByOrganizationidEnvironmentsByEnvironmentidGateways (urn:api:flex-gateway-manager)
GET /organizations/{organizationId}/environments/{environmentId}/gateways
Score: 0.78
Step 3: Create API in api-manager
→ createOrganizationsEnvironmentsApis (urn:api:api-manager)
POST /organizations/{organizationId}/environments/{environmentId}/apis
Score: 0.92
Does this match your intent?
User: Yes
You: Building the workflow...
[Analyzes parameters and data flow]
Data flow detected:
✓ Step 1 outputs: groupId, assetId, version
✓ Step 2 outputs: gatewayId
✓ Step 3 uses: groupId, assetId, version (from Step 1), gatewayId (from Step 2)
[Generates complete JTBD with prose]
Generated JTBD:
- Name: deploy-api-with-flex-gateway
- Steps: 3
- Prerequisites: User authentication, Exchange asset, Omni Gateway
[Validates]
Validation: ✅ PASSED
Save to skills/deploy-api-with-flex-gateway/SKILL.md?
User: Yes
You: ✅ Saved successfully!
File: skills/deploy-api-with-flex-gateway/SKILL.md
Next steps:
- Review the generated workflow
- Test with: python3 .claude/skills/jtbd-generator/scripts/validate_jtbd.py skills/deploy-api-with-flex-gateway/SKILL.md .
- Related workflows: deploy-api-with-rate-limiting, setup-multi-upstream-routingData Flow Intelligence
数据流智能
Apply these rules when detecting parameter sources:
Rule 1: Output → Input Matching (High Confidence)
If Step N outputs 'environmentApiId' AND Step N+1 needs 'environmentApiId':
→ Auto-link with { from: { step: "Step N", output: "environmentApiId" } }Rule 2: Input Reuse (High Confidence)
If Step N uses 'organizationId' AND Step N+1 needs 'organizationId':
→ Reuse with { from: { step: "Step N", input: "organizationId" } }
(Not from original source - reuse the previous step's input)Rule 3: x-origin Suggestions (High Confidence)
If parameter has x-origin annotation:
→ Use that as the default source
→ Add alternatives if providedRule 4: Common Patterns (Medium Confidence)
If parameter is 'organizationId' and no previous source:
→ Default to access-management#getOrganizations
If parameter is 'environmentId' and no previous source:
→ Default to access-management#listEnvironmentsRule 5: User-Provided Fallback (Low Confidence)
If no source detected:
→ Mark as userProvided: true
→ Add example if parameter has example in schema
→ Mention in conversation that this needs user input应用以下规则检测参数来源:
规则 1:输出 → 输入匹配(高置信度)
If Step N outputs 'environmentApiId' AND Step N+1 needs 'environmentApiId':
→ Auto-link with { from: { step: "Step N", output: "environmentApiId" } }规则 2:输入复用(高置信度)
If Step N uses 'organizationId' AND Step N+1 needs 'organizationId':
→ Reuse with { from: { step: "Step N", input: "organizationId" } }
(Not from original source - reuse the previous step's input)规则 3:x-origin 建议(高置信度)
If parameter has x-origin annotation:
→ Use that as the default source
→ Add alternatives if provided规则 4:常见模式(中等置信度)
If parameter is 'organizationId' and no previous source:
→ Default to access-management#getOrganizations
If parameter is 'environmentId' and no previous source:
→ Default to access-management#listEnvironments规则 5:用户提供的回退值(低置信度)
If no source detected:
→ Mark as userProvided: true
→ Add example if parameter has example in schema
→ Mention in conversation that this needs user inputError Handling
错误处理
Operation Not Found
未找到操作
"I couldn't find an operation matching '{description}' in {api_urn}.
Let me search more broadly..."
[Search all APIs, show top matches]
"Here are some operations that might work:
1. {operationId} ({api}) - {summary}
2. {operationId} ({api}) - {summary}
Which one fits best, or would you like to search differently?""I couldn't find an operation matching '{description}' in {api_urn}.
Let me search more broadly..."
[Search all APIs, show top matches]
"Here are some operations that might work:
1. {operationId} ({api}) - {summary}
2. {operationId} ({api}) - {summary}
Which one fits best, or would you like to search differently?"Validation Fails
验证失败
"The generated JTBD has validation errors:
❌ Step 2 references unknown output 'apiId' from Step 1
I'll fix this by:
- Checking Step 1's actual outputs
- Updating Step 2's input to use the correct output name
Regenerating...""The generated JTBD has validation errors:
❌ Step 2 references unknown output 'apiId' from Step 1
I'll fix this by:
- Checking Step 1's actual outputs
- Updating Step 2's input to use the correct output name
Regenerating..."Ambiguous Step Description
步骤描述存在歧义
"Step 2: 'Get gateway targets' is ambiguous.
I found operations in two APIs:
1. Omni Gateway Manager - List omni gateways
2. Runtime Manager - List CloudHub workers
Which one should I use?""Step 2: 'Get gateway targets' is ambiguous.
I found operations in two APIs:
1. Omni Gateway Manager - List omni gateways
2. Runtime Manager - List CloudHub workers
Which one should I use?"Tips for Quality Output
高质量输出技巧
-
Write conversational prose:
- "Start by retrieving..." not "This step retrieves..."
- "You'll need the organization ID..." not "organizationId is required"
-
Explain the why:
- Not just "Create an API instance"
- But "Create an API instance to register your Exchange asset with API Manager, enabling policy application and gateway routing"
-
Connect steps logically:
- End each step with "What happens next" that leads into the next step
- Show how outputs become inputs
-
Anticipate issues:
- Add "Common issues" for known problems
- Mention typical error responses
-
Be specific:
- "Organization Business Group GUID" not just "organization ID"
- "Target environment ID (e.g., Production, Sandbox)" not just "environment ID"
-
编写对话式说明:
- 使用“先获取……”而不是“此步骤获取……”
- 使用“你需要 organization ID……”而不是“必须提供 organizationId”
-
解释原因:
- 不只是“创建 API 实例”
- 而是“创建 API 实例,将 Exchange 资产注册到 API Manager,从而支持策略应用和网关路由”
-
在逻辑上连接各个步骤:
- 以“接下来会发生什么”结束每个步骤,自然引出下一步
- 展示输出如何成为输入
-
预判问题:
- 为已知问题添加“常见问题”
- 提及典型的错误响应
-
保持具体:
- 使用“组织业务组 GUID”而不是“组织 ID”
- 使用“目标环境 ID(例如 Production、Sandbox)”而不是“环境 ID”
Available Python Utilities
可用的 Python 工具
You have access to these utilities in :
.claude/skills/jtbd-generator/lib/你可以使用 中的以下工具:
.claude/skills/jtbd-generator/lib/api_discovery.py
api_discovery.py
- - List all APIs with metadata
list_available_apis(repo_root) - - Fuzzy search for operations
search_operations(query, api_urn, repo_root) - - Get full operation details
get_operation_details(api_urn, operation_id, repo_root) - - List all operations in an API
get_operations_by_api(api_urn, repo_root)
- - 列出所有 API 及其元数据
list_available_apis(repo_root) - - 模糊搜索操作
search_operations(query, api_urn, repo_root) - - 获取完整的操作详情
get_operation_details(api_urn, operation_id, repo_root) - - 列出指定 API 中的所有操作
get_operations_by_api(api_urn, repo_root)
parameter_analyzer.py
parameter_analyzer.py
- - Extract all parameters with metadata
analyze_parameters(spec, operation_id, spec_path) - - Detect where parameter should come from
detect_parameter_source(param_name, param_def, previous_steps) - - Build JTBD input definition
build_input_definition(param_name, param_def, source) - - Build complete inputs section
build_all_inputs(api_urn, operation_id, repo_root, previous_steps)
- - 提取所有参数及其元数据
analyze_parameters(spec, operation_id, spec_path) - - 检测参数应来自何处
detect_parameter_source(param_name, param_def, previous_steps) - - 构建 JTBD 输入定义
build_input_definition(param_name, param_def, source) - - 构建完整的 inputs 部分
build_all_inputs(api_urn, operation_id, repo_root, previous_steps)
response_analyzer.py
response_analyzer.py
- - Suggest which fields to capture
suggest_outputs(spec, operation_id, spec_path, next_steps) - - Generate JSONPath expressions
generate_jsonpath(field_path) - - Main entry point
analyze_response_for_operation(api_urn, operation_id, repo_root, next_steps)
- - 建议应捕获的字段
suggest_outputs(spec, operation_id, spec_path, next_steps) - - 生成 JSONPath 表达式
generate_jsonpath(field_path) - - 主入口
analyze_response_for_operation(api_urn, operation_id, repo_root, next_steps)
jtbd_builder.py
jtbd_builder.py
- - Generate YAML frontmatter
build_frontmatter(name, description) - - Generate YAML block for step
build_step_yaml(api_urn, operation_id, inputs, outputs) - - Generate complete step section
build_step_markdown(step_number, step_name, ...) - - Assemble complete JTBD
build_complete_jtbd(name, description, title, ...)
- - 生成 YAML frontmatter
build_frontmatter(name, description) - - 生成步骤的 YAML 块
build_step_yaml(api_urn, operation_id, inputs, outputs) - - 生成完整的步骤章节
build_step_markdown(step_number, step_name, ...) - - 组装完整的 JTBD
build_complete_jtbd(name, description, title, ...)
utils.py
utils.py
- - Load and parse OpenAPI spec
load_openapi_spec(api_path) - - Convert URN to filesystem path
urn_to_path(urn, repo_root) - - Convert filesystem path to URN
path_to_urn(api_path) - - Convert text to kebab-case
kebab_case(text) - - Resolve $ref references
resolve_ref(ref, spec, spec_path) - - Find all API directories
find_api_dirs(repo_root)
- - 加载并解析 OpenAPI 规范
load_openapi_spec(api_path) - - 将 URN 转换为文件系统路径
urn_to_path(urn, repo_root) - - 将文件路径转换为 URN
path_to_urn(api_path) - - 将文本转换为 kebab-case
kebab_case(text) - - 解析 $ref 引用
resolve_ref(ref, spec, spec_path) - - 查找所有 API 目录
find_api_dirs(repo_root)
common_patterns.py
common_patterns.py
- - Check for known patterns
match_common_pattern(param_name) - - Check if likely user-provided
is_likely_user_provided(param_name) - - Get example values
get_example_for_param(param_name, param_schema)
- - 检查已知模式
match_common_pattern(param_name) - - 检查是否可能由用户提供
is_likely_user_provided(param_name) - - 获取示例值
get_example_for_param(param_name, param_schema)
Success Criteria
成功标准
A successful JTBD generation:
- ✅ Passes validation ()
validate_jtbd.py - ✅ All operations exist in referenced API specs
- ✅ Data flow correctly maps outputs to inputs
- ✅ Prose sections are clear and helpful (not template-like)
- ✅ User completed generation in <5 minutes of interaction
- ✅ User understands what the workflow does and how to use it
成功生成 JTBD 应满足以下条件:
- ✅ 通过验证()
validate_jtbd.py - ✅ 引用的 API 规范中均存在所有操作
- ✅ 正确映射输出到输入的数据流
- ✅ 说明性章节清晰且乐于助人,而不是模板化文本
- ✅ 用户在不到 5 分钟的交互中完成生成
- ✅ 用户理解此工作流的功能及其使用方式
Notes
注意事项
- Always run the workflow in order: Parse → Discover → Analyze → Generate → Validate → Save
- Use the Python utilities for spec parsing and structure building
- Use your intelligence for prose generation and user interaction
- Be conversational and helpful
- When in doubt, ask the user for clarification
- Default to skills/{name}/SKILL.md for output location
- 始终按以下顺序运行工作流:解析 → 发现 → 分析 → 生成 → 验证 → 保存
- 使用 Python 工具解析规范并构建结构
- 使用你的智能能力生成说明文字并与用户交互
- 保持对话式且乐于助人
- 如有疑问,请向用户寻求澄清
- 默认输出位置为
skills/{name}/SKILL.md