jtbd-generator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

JTBD 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:
  1. Prerequisites: Conditions that must be met (e.g., "user logged in", "API asset exists in Exchange")
  2. 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 时,他们将提供:
  1. 前置条件:必须满足的条件(例如“用户已登录”“Exchange 中存在 API 资产”)
  2. 步骤:以自然语言描述的操作列表(例如“从 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:
  1. 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']}")
  2. Present options to user:
    • Show the top matches with scores
    • Include operation summary and API
    • Ask user to confirm or choose
  3. 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']}")
  4. Store selection:
    • Step number
    • Step name (user-provided)
    • API URN
    • Operation ID
    • Operation details
对于每个步骤描述:
  1. 搜索匹配的操作:
    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']}")
  2. 向用户提供选项:
    • 显示得分最高的匹配项
    • 包含操作摘要和 API
    • 请用户确认或选择
  3. 获取操作详情:
    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']}")
  4. 保存选择结果:
    • 步骤编号
    • 步骤名称(用户提供)
    • API URN
    • Operation ID
    • 操作详情

Step 3: Analyze Parameters & Data Flow

第 3 步:分析参数与数据流

For each step (in order from 1 to N):
  1. 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")
  2. 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'])}")
  3. Confirm with user:
    • Show detected data flow
    • Highlight any user-provided parameters
    • Ask if adjustments are needed
按从 1 到 N 的顺序,针对每个步骤执行以下操作:
  1. 分析参数:
    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")
  2. 建议输出:
    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'])}")
  3. 与用户确认:
    • 展示检测到的数据流
    • 突出显示所有由用户提供的参数
    • 询问是否需要调整

Step 4: Generate JTBD Structure

第 4 步:生成 JTBD 结构

  1. 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"
  2. 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
    )
  3. 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
  4. 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"
        ]
    )
  1. 创建 kebab-case 名称:
    python
    from lib.utils import kebab_case
    
    name = kebab_case("Deploy API with Omni Gateway")
    # Result: "deploy-api-with-flex-gateway"
  2. 为每个步骤构建 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
    )
  3. 生成说明性章节:
    运用你的理解能力编写:
    • 概述:以动作导向的描述(以动词开头:“部署……”“创建……”“配置……”)
    • 你将构建什么:清晰的结果陈述
    • 步骤说明:解释每个步骤执行什么操作及其原因
    • 你需要什么:每个步骤的前置条件
    • 接下来会发生什么:执行结果及其与后续步骤的关联
    质量指南:
    • 保持对话式且乐于助人
    • 解释“为什么”,而不只是说明“做什么”
    • 在逻辑上连接各个步骤
    • 预判常见问题
  4. 构建完整的 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 步:保存并确认

  1. Determine save location:
    • Default:
      skills/{name}/SKILL.md
    • Ask user if unsure
  2. 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)
  3. Confirm with user:
    • Show file path
    • Mention validation status
    • Suggest next actions
  4. Suggest related workflows:
    • Based on the APIs used
    • Based on similar existing JTBDs
    • Based on common next steps

  1. 确定保存位置:
    • 默认位置:
      skills/{name}/SKILL.md
    • 如果不确定,请询问用户
  2. 保存文件:
    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)
  3. 与用户确认:
    • 展示文件路径
    • 说明验证状态
    • 建议后续操作
  4. 建议相关工作流:
    • 根据所使用的 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-routing

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-routing

Data 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 provided
Rule 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#listEnvironments
Rule 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 input

Error 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

高质量输出技巧

  1. Write conversational prose:
    • "Start by retrieving..." not "This step retrieves..."
    • "You'll need the organization ID..." not "organizationId is required"
  2. 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"
  3. Connect steps logically:
    • End each step with "What happens next" that leads into the next step
    • Show how outputs become inputs
  4. Anticipate issues:
    • Add "Common issues" for known problems
    • Mention typical error responses
  5. Be specific:
    • "Organization Business Group GUID" not just "organization ID"
    • "Target environment ID (e.g., Production, Sandbox)" not just "environment ID"

  1. 编写对话式说明:
    • 使用“先获取……”而不是“此步骤获取……”
    • 使用“你需要 organization ID……”而不是“必须提供 organizationId”
  2. 解释原因:
    • 不只是“创建 API 实例”
    • 而是“创建 API 实例,将 Exchange 资产注册到 API Manager,从而支持策略应用和网关路由”
  3. 在逻辑上连接各个步骤:
    • 以“接下来会发生什么”结束每个步骤,自然引出下一步
    • 展示输出如何成为输入
  4. 预判问题:
    • 为已知问题添加“常见问题”
    • 提及典型的错误响应
  5. 保持具体:
    • 使用“组织业务组 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_available_apis(repo_root)
    - List all APIs with metadata
  • search_operations(query, api_urn, repo_root)
    - Fuzzy search for operations
  • get_operation_details(api_urn, operation_id, repo_root)
    - Get full operation details
  • get_operations_by_api(api_urn, repo_root)
    - List all operations in an API
  • list_available_apis(repo_root)
    - 列出所有 API 及其元数据
  • search_operations(query, api_urn, repo_root)
    - 模糊搜索操作
  • get_operation_details(api_urn, operation_id, repo_root)
    - 获取完整的操作详情
  • get_operations_by_api(api_urn, repo_root)
    - 列出指定 API 中的所有操作

parameter_analyzer.py

parameter_analyzer.py

  • analyze_parameters(spec, operation_id, spec_path)
    - Extract all parameters with metadata
  • detect_parameter_source(param_name, param_def, previous_steps)
    - Detect where parameter should come from
  • build_input_definition(param_name, param_def, source)
    - Build JTBD input definition
  • build_all_inputs(api_urn, operation_id, repo_root, previous_steps)
    - Build complete inputs section
  • analyze_parameters(spec, operation_id, spec_path)
    - 提取所有参数及其元数据
  • detect_parameter_source(param_name, param_def, previous_steps)
    - 检测参数应来自何处
  • build_input_definition(param_name, param_def, source)
    - 构建 JTBD 输入定义
  • build_all_inputs(api_urn, operation_id, repo_root, previous_steps)
    - 构建完整的 inputs 部分

response_analyzer.py

response_analyzer.py

  • suggest_outputs(spec, operation_id, spec_path, next_steps)
    - Suggest which fields to capture
  • generate_jsonpath(field_path)
    - Generate JSONPath expressions
  • analyze_response_for_operation(api_urn, operation_id, repo_root, next_steps)
    - Main entry point
  • suggest_outputs(spec, operation_id, spec_path, next_steps)
    - 建议应捕获的字段
  • generate_jsonpath(field_path)
    - 生成 JSONPath 表达式
  • analyze_response_for_operation(api_urn, operation_id, repo_root, next_steps)
    - 主入口

jtbd_builder.py

jtbd_builder.py

  • build_frontmatter(name, description)
    - Generate YAML frontmatter
  • build_step_yaml(api_urn, operation_id, inputs, outputs)
    - Generate YAML block for step
  • build_step_markdown(step_number, step_name, ...)
    - Generate complete step section
  • build_complete_jtbd(name, description, title, ...)
    - Assemble complete JTBD
  • build_frontmatter(name, description)
    - 生成 YAML frontmatter
  • build_step_yaml(api_urn, operation_id, inputs, outputs)
    - 生成步骤的 YAML 块
  • build_step_markdown(step_number, step_name, ...)
    - 生成完整的步骤章节
  • build_complete_jtbd(name, description, title, ...)
    - 组装完整的 JTBD

utils.py

utils.py

  • load_openapi_spec(api_path)
    - Load and parse OpenAPI spec
  • urn_to_path(urn, repo_root)
    - Convert URN to filesystem path
  • path_to_urn(api_path)
    - Convert filesystem path to URN
  • kebab_case(text)
    - Convert text to kebab-case
  • resolve_ref(ref, spec, spec_path)
    - Resolve $ref references
  • find_api_dirs(repo_root)
    - Find all API directories
  • load_openapi_spec(api_path)
    - 加载并解析 OpenAPI 规范
  • urn_to_path(urn, repo_root)
    - 将 URN 转换为文件系统路径
  • path_to_urn(api_path)
    - 将文件路径转换为 URN
  • kebab_case(text)
    - 将文本转换为 kebab-case
  • resolve_ref(ref, spec, spec_path)
    - 解析 $ref 引用
  • find_api_dirs(repo_root)
    - 查找所有 API 目录

common_patterns.py

common_patterns.py

  • match_common_pattern(param_name)
    - Check for known patterns
  • is_likely_user_provided(param_name)
    - Check if likely user-provided
  • get_example_for_param(param_name, param_schema)
    - Get example values

  • 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:
  1. ✅ Passes validation (
    validate_jtbd.py
    )
  2. ✅ All operations exist in referenced API specs
  3. ✅ Data flow correctly maps outputs to inputs
  4. ✅ Prose sections are clear and helpful (not template-like)
  5. ✅ User completed generation in <5 minutes of interaction
  6. ✅ User understands what the workflow does and how to use it

成功生成 JTBD 应满足以下条件:
  1. ✅ 通过验证(
    validate_jtbd.py
    )
  2. ✅ 引用的 API 规范中均存在所有操作
  3. ✅ 正确映射输出到输入的数据流
  4. ✅ 说明性章节清晰且乐于助人,而不是模板化文本
  5. ✅ 用户在不到 5 分钟的交互中完成生成
  6. ✅ 用户理解此工作流的功能及其使用方式

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