skill-compass

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Search Skills

搜索Skill

Overview

概述

Use real API calls only. Do not output pseudo-instructions.

Primary objective for this deployment:

ship stable retrieval and complete feedback telemetry for each recommendation cycle

High-level flow:

build structured query
call
```
POST /search_multi
```
if needed, ask one clarification
call
```
POST /search_multi
```
again
return 1-3 final recommendations
call
```
POST /feedback
```
after user verdict

Hard limits:

at most two retrieval passes
at most one clarification question
never skip feedback submission after final verdict

<HARD-GATE> If clarification was asked, the next user reply MUST be treated as continuation input for this same retrieval session. Do not exit this skill before pass #2 (or explicit stop on API failure). </HARD-GATE>

仅使用真实API调用。不要输出伪指令。

本次部署的主要目标：

交付稳定的检索功能，并为每个推荐周期完成反馈遥测

高级流程：

构建结构化查询
调用
```
POST /search_multi
```
如有需要，提出一个澄清问题
再次调用
```
POST /search_multi
```
返回1-3个最终推荐结果
用户给出评价后调用
```
POST /feedback
```

硬性限制：

最多进行两次检索调用
最多提出一个澄清问题
收到最终评价后绝不能跳过反馈提交

<HARD-GATE> 如果已经提出澄清问题，用户的下一条回复必须视为当前检索会话的延续输入。在完成第二次调用前（或API明确调用失败前），不要退出该Skill。 </HARD-GATE>

Operational Integration

运营集成

base URL env:
```
https://skills.megatechai.com/
```
search endpoint:
```
POST /search_multi
```
feedback endpoint:
```
POST /feedback
```

Session policy:

create one
```
retrieval_session_id
```
at pass #1 and reuse it for pass #2
always set
```
round
```
explicitly (
```
1
```
then
```
2
```
)
when pass #2 is used, always set
```
parent_search_id
```
to pass #1
```
search_id
```

基础URL环境变量：
```
https://skills.megatechai.com/
```
搜索端点：
```
POST /search_multi
```
反馈端点：
```
POST /feedback
```

会话策略：

在第一次调用时生成一个
```
retrieval_session_id
```
，并在第二次调用中复用
必须显式设置
```
round
```
参数（第一次为
```
1
```
，第二次为
```
2
```
）
当进行第二次调用时，必须将
```
parent_search_id
```
设置为第一次调用返回的
```
search_id
```

Request Contract (

/search_multi

)

请求契约 (

/search_multi

)

json

{
  "query": "optional broad query",
  "query_fields": {
    "name": "short capability label",
    "description": "core problem",
    "when_to_use": "triggering scenario",
    "sections": "optional expected coverage"
  },
  "weights": {
    "name": 0.1,
    "description": 0.6,
    "when_to_use": 0.2,
    "sections": 0.1
  },
  "top_k": 10,
  "candidate_k": 200,
  "quality_weight": 0.1,
  "retrieval_session_id": "optional session id",
  "round": 1,
  "parent_search_id": "optional previous search id",
  "clarification_used": false,
  "clarification_text": "optional short summary",
  "consent_granted": true
}

Field rules:

```
retrieval_session_id
```
: shared across pass #1 and pass #2
```
round
```
: pass number (
```
1
```
,
```
2
```
, ...), API records only and does not block
```
parent_search_id
```
: pass #2 points to pass #1
```
search_id
```
```
clarification_used
```
: true only when pass #2 is triggered by clarification
```
clarification_text
```
: short summary of clarification reason
```
consent_granted
```
: whether detailed telemetry may be stored
```
query_fields.description
```
: preferred strongest signal; keep concise and task-focused
keep unknown fields empty instead of copying the same sentence into all fields

Language rule:

if user input is not English, translate to natural English before sending payload text

json

{
  "query": "optional broad query",
  "query_fields": {
    "name": "short capability label",
    "description": "core problem",
    "when_to_use": "triggering scenario",
    "sections": "optional expected coverage"
  },
  "weights": {
    "name": 0.1,
    "description": 0.6,
    "when_to_use": 0.2,
    "sections": 0.1
  },
  "top_k": 10,
  "candidate_k": 200,
  "quality_weight": 0.1,
  "retrieval_session_id": "optional session id",
  "round": 1,
  "parent_search_id": "optional previous search id",
  "clarification_used": false,
  "clarification_text": "optional short summary",
  "consent_granted": true
}

字段规则：

```
retrieval_session_id
```
: 在第一次和第二次调用间共享
```
round
```
: 调用次数（
```
1
```
、
```
2
```
...），仅用于API记录，不会阻止调用
```
parent_search_id
```
: 第二次调用时指向第一次调用的
```
search_id
```
```
clarification_used
```
: 仅当第二次调用是由澄清问题触发时设为
```
true
```
```
clarification_text
```
: 澄清原因的简短总结
```
consent_granted
```
: 是否允许存储详细遥测数据
```
query_fields.description
```
: 优先级最高的信号；保持简洁且聚焦于任务
未知字段留空，不要将同一句话复制到所有字段中

语言规则：

如果用户输入不是英文，在发送请求前先将其翻译成自然的英文

Response Contract (

/search_multi

)

响应契约 (

/search_multi

)

json

{
  "search_id": "uuid",
  "retrieval_session_id": "uuid-or-provided",
  "results": [
    {
      "skill_id": "owner/repo@skill",
      "repo": "repo",
      "name": "skill",
      "description": "...",
      "when_to_use": ["..."],
      "weekly_installs_num": 100,
      "github_stars_num": 300,
      "final_score": 0.8
    }
  ]
}

Response notes (envelope response, not array root):

```
search_id
```
: anchor for search-level feedback and round linking
```
retrieval_session_id
```
: anchor for session-level feedback
```
results
```
: rank output for recommendation reasoning
- ```
github_stars_num
```
  : GitHub star count of the skill repository
- ```
weekly_installs_num
```
  : weekly install volume
- ```
final_score
```
  : final retrieval/ranking score

Validation before using results:

require
```
search_id
```
as non-empty string
require
```
retrieval_session_id
```
as non-empty string
require
```
results
```
as array (can be empty)
if contract is broken, return parse/contract error and stop

json

{
  "search_id": "uuid",
  "retrieval_session_id": "uuid-or-provided",
  "results": [
    {
      "skill_id": "owner/repo@skill",
      "repo": "repo",
      "name": "skill",
      "description": "...",
      "when_to_use": ["..."],
      "weekly_installs_num": 100,
      "github_stars_num": 300,
      "final_score": 0.8
    }
  ]
}

响应说明（信封式响应，而非数组根节点）：

```
search_id
```
: 用于搜索级反馈和调用关联的锚点
```
retrieval_session_id
```
: 用于会话级反馈的锚点
```
results
```
: 用于推荐推理的排名输出
- ```
github_stars_num
```
  : Skill仓库的GitHub星标数量
- ```
weekly_installs_num
```
  : 每周安装量
- ```
final_score
```
  : 最终检索/排名得分

使用结果前的验证：

要求
```
search_id
```
为非空字符串
要求
```
retrieval_session_id
```
为非空字符串
要求
```
results
```
为数组（可以为空）
如果契约被破坏，返回解析/契约错误并终止流程

Feedback Contract (

/feedback

)

反馈契约 (

/feedback

)

Search-level feedback:

json

{
  "target_type": "search",
  "search_id": "search-id",
  "feedback_type": "thumb_up",
  "selected_skill_ids": ["owner/repo@skill"],
  "comment": "optional"
}

Session-level feedback:

json

{
  "target_type": "session",
  "retrieval_session_id": "session-id",
  "feedback_type": "thumb_up",
  "selected_skill_ids": ["owner/repo@skill"],
  "comment": "optional"
}

Feedback types:

```
thumb_up
```
```
irrelevant
```
```
clicked_only
```

Feedback policy:

prefer
```
target_type=session
```
for final user verdict
fallback to
```
target_type=search
```
only when session id is unavailable
include
```
selected_skill_ids
```
when user explicitly approves/rejects specific items
keep
```
comment
```
short and factual; omit if none

搜索级反馈：

json

{
  "target_type": "search",
  "search_id": "search-id",
  "feedback_type": "thumb_up",
  "selected_skill_ids": ["owner/repo@skill"],
  "comment": "optional"
}

会话级反馈：

json

{
  "target_type": "session",
  "retrieval_session_id": "session-id",
  "feedback_type": "thumb_up",
  "selected_skill_ids": ["owner/repo@skill"],
  "comment": "optional"
}

反馈类型：

```
thumb_up
```
```
irrelevant
```
```
clicked_only
```

反馈策略：

针对用户最终评价，优先使用
```
target_type=session
```
仅当会话ID不可用时，回退到
```
target_type=search
```
当用户明确批准/拒绝特定项时，包含
```
selected_skill_ids
```
```
comment
```
保持简短且基于事实；若无则省略

Full Retrieval + Feedback Procedure

完整检索+反馈流程

1) Generate structured query

1) 生成结构化查询

Transform user need into these fields:
- ```
name
```
  : short capability label
- ```
description
```
  : main problem to solve (strongest field)
- ```
when_to_use
```
  : triggering scenario
- ```
sections
```
  : optional coverage expectation Guidelines:
- keep unknown fields empty
- do not duplicate one sentence into all fields
- use
```
sections
```
  only when user explicitly cares about coverage

call

POST /search_multi

with:

```
round=1
```
```
clarification_used=false
```
```
retrieval_session_id
```
generated once and reused

keep returned
```
search_id
```
as
```
search_id_round1
```

将用户需求转换为以下字段：
- ```
name
```
  : 简短的能力标签
- ```
description
```
  : 要解决的核心问题（优先级最高的字段）
- ```
when_to_use
```
  : 触发场景
- ```
sections
```
  : 可选的覆盖范围预期指导原则：
- 未知字段留空
- 不要将同一句话复制到所有字段中
- 仅当用户明确关注覆盖范围时使用
```
sections
```

调用

POST /search_multi

，参数包括：

```
round=1
```
```
clarification_used=false
```
生成一个
```
retrieval_session_id
```
并复用

将返回的
```
search_id
```
保存为
```
search_id_round1
```

2) Clarification decision

2) 澄清决策

if top results are coherent: skip clarification, finalize
if top results split: ask exactly one targeted clarification

Use clarification when one or more is true:

top candidates represent different intents (for example tooling vs process)
top 2 scores are close and imply different recommendation directions
user request is under-specified for an irreversible recommendation

Clarification question quality bar:

one question only
present 2-3 concrete options found in pass #1
ask for one decisive preference, not open-ended brainstorming

如果顶部结果连贯：跳过澄清，直接定稿
如果顶部结果分散：提出恰好一个针对性的澄清问题

满足以下任一条件时使用澄清：

顶部候选结果代表不同意图（例如工具类 vs 流程类）
前两个得分接近且暗示不同的推荐方向
用户请求的描述不够明确，无法给出不可逆的推荐

澄清问题的质量标准：

仅提一个问题
展示第一次调用中找到的2-3个具体选项
请求明确的偏好选择，而非开放式的头脑风暴

3) Regenerate structured query and retrieve again (only if clarification happened)

3) 重新生成结构化查询并再次检索（仅在进行澄清后执行）

regenerate full query object (not only a raw append)

call

POST /search_multi

with:

```
round=2
```
same
```
retrieval_session_id
```
```
parent_search_id=search_id_round1
```
```
clarification_used=true
```
short
```
clarification_text
```

finalize with 1-3 recommendations

Final recommendation output must include per item:

```
skill_id
```
fit reason linked to user intent/query fields
```
final_score
```
```
github_stars_num
```

重新生成完整的查询对象（不仅是追加内容）

调用

POST /search_multi

，参数包括：

```
round=2
```
相同的
```
retrieval_session_id
```
```
parent_search_id=search_id_round1
```
```
clarification_used=true
```
简短的
```
clarification_text
```

最终给出1-3个推荐结果

最终推荐输出必须包含每个项的：

```
skill_id
```
与用户意图/查询字段相关的适配理由
```
final_score
```
```
github_stars_num
```

4) Feedback submission

4) 反馈提交

After user accepts/rejects recommendations, call

POST /feedback

Recommended mapping:

user approves final recommendation ->
```
thumb_up
```
user says irrelevant/wrong direction ->
```
irrelevant
```
user clicked but no clear verdict ->
```
clicked_only
```

Feedback timing rules:

do not send final feedback before user verdict exists
once verdict exists, send exactly one final feedback event for this session
if user updates verdict in the same conversation, send one additional corrected feedback event

用户接受/拒绝推荐后，调用

POST /feedback

。

推荐映射规则：

用户批准最终推荐 ->
```
thumb_up
```
用户表示不相关/方向错误 ->
```
irrelevant
```
用户仅点击但无明确评价 ->
```
clicked_only
```

反馈时间规则：

在用户给出评价前不要发送最终反馈
一旦收到评价，针对本次会话发送恰好一个最终反馈事件
如果用户在同一场对话中更新评价，发送一个额外的修正反馈事件

End-to-End Example

端到端示例

1) Pass #1

1) 第一次调用

json

POST /search_multi
{
  "query_fields": {
    "description": "find a skill to author and validate new skills"
  },
  "top_k": 10,
  "candidate_k": 200,
  "quality_weight": 0.1,
  "retrieval_session_id": "sess-abc",
  "round": 1,
  "clarification_used": false,
  "consent_granted": true
}

json

POST /search_multi
{
  "query_fields": {
    "description": "find a skill to author and validate new skills"
  },
  "top_k": 10,
  "candidate_k": 200,
  "quality_weight": 0.1,
  "retrieval_session_id": "sess-abc",
  "round": 1,
  "clarification_used": false,
  "consent_granted": true
}

2) Pass #2

2) 第二次调用

json

POST /search_multi
{
  "query_fields": {
    "name": "writing-skills",
    "description": "author reusable skills and verify quality before release",
    "when_to_use": "after deciding to create or edit a skill",
    "sections": "testing, anti-patterns, deployment"
  },
  "weights": {
    "name": 0.2,
    "description": 0.45,
    "when_to_use": 0.25,
    "sections": 0.1
  },
  "top_k": 6,
  "candidate_k": 150,
  "quality_weight": 0.1,
  "retrieval_session_id": "sess-abc",
  "round": 2,
  "parent_search_id": "<search_id_round1>",
  "clarification_used": true,
  "clarification_text": "focus on writing-skills instead of generic skill discovery",
  "consent_granted": true
}

json

POST /search_multi
{
  "query_fields": {
    "name": "writing-skills",
    "description": "author reusable skills and verify quality before release",
    "when_to_use": "after deciding to create or edit a skill",
    "sections": "testing, anti-patterns, deployment"
  },
  "weights": {
    "name": 0.2,
    "description": 0.45,
    "when_to_use": 0.25,
    "sections": 0.1
  },
  "top_k": 6,
  "candidate_k": 150,
  "quality_weight": 0.1,
  "retrieval_session_id": "sess-abc",
  "round": 2,
  "parent_search_id": "<search_id_round1>",
  "clarification_used": true,
  "clarification_text": "focus on writing-skills instead of generic skill discovery",
  "consent_granted": true
}

3) Feedback

3) 反馈

json

POST /feedback
{
  "target_type": "session",
  "retrieval_session_id": "sess-abc",
  "feedback_type": "thumb_up",
  "selected_skill_ids": ["obra/superpowers@writing-skills"],
  "comment": "second pass solved ambiguity"
}

json

POST /feedback
{
  "target_type": "session",
  "retrieval_session_id": "sess-abc",
  "feedback_type": "thumb_up",
  "selected_skill_ids": ["obra/superpowers@writing-skills"],
  "comment": "second pass solved ambiguity"
}

Error Handling

错误处理

if API call fails after retry: return concrete error and stop
if API returns non-JSON/invalid schema: return contract error and stop
if pass #1 returns empty
```
results
```
: tell user no relevant skills found and request refined intent (no pass #2 unless this is the one clarification)
do not fabricate retrieval results
do not continue to recommendation stage without at least one successful retrieval

如果API调用重试后仍然失败：返回具体错误并终止流程
如果API返回非JSON/无效 schema：返回契约错误并终止流程
如果第一次调用返回空
```
results
```
：告知用户未找到相关Skill，并请求细化意图（除非这是唯一的澄清请求，否则不进行第二次调用）
不要编造检索结果
至少成功完成一次检索后，才能进入推荐阶段

Completion Rules

完成规则

recommend 1-3 skills and briefly explain why they are relevant to user needs
DO NOT show users
```
final_score
```
or
```
weekly_installs_num
```
display the GitHub star count of the repository it belongs to. Make it explicit that this is the star count of the GitHub repository
when launch goal is explicit, state which recommendation helps API launch vs skill authoring
stop after pass #2
after final user verdict, call
```
POST /feedback
```

推荐1-3个Skill，并简要说明它们与用户需求的相关性
不要向用户展示
```
final_score
```
或
```
weekly_installs_num
```
显示其所属仓库的GitHub星标数量。要明确说明这是GitHub仓库的星标数量
当启动目标明确时，说明哪个推荐有助于API启动 vs Skill创作
第二次调用后终止流程
用户给出最终评价后，调用
```
POST /feedback
```

Common Mistakes

常见错误

parsing
```
/search_multi
```
as array root instead of envelope response
forgetting to persist
```
search_id
```
/
```
retrieval_session_id
```
skipping
```
parent_search_id
```
on pass #2
asking a second clarification question
skipping
```
consent_granted
```
or
```
round
```
not sending
```
/feedback
```
after final user verdict

将
```
/search_multi
```
的响应解析为数组根节点而非信封式响应
忘记保存
```
search_id
```
/
```
retrieval_session_id
```
第二次调用时遗漏
```
parent_search_id
```
提出第二个澄清问题
遗漏
```
consent_granted
```
或
```
round
```
参数
用户给出最终评价后未调用
```
/feedback
```

skill-compass

Original

Translation

Search Skills

搜索Skill

Overview

概述

Operational Integration

运营集成

Request Contract (
`/search_multi`
)

请求契约 (
`/search_multi`
)

Response Contract (
`/search_multi`
)

响应契约 (
`/search_multi`
)

Feedback Contract (
`/feedback`
)

反馈契约 (
`/feedback`
)

Full Retrieval + Feedback Procedure

完整检索+反馈流程

1) Generate structured query

1) 生成结构化查询

2) Clarification decision

2) 澄清决策

3) Regenerate structured query and retrieve again (only if clarification happened)

3) 重新生成结构化查询并再次检索（仅在进行澄清后执行）

4) Feedback submission

4) 反馈提交

End-to-End Example

端到端示例

1) Pass #1

1) 第一次调用

2) Pass #2

2) 第二次调用

3) Feedback

3) 反馈

Error Handling

错误处理

Completion Rules

完成规则

Common Mistakes

常见错误

skill-compass

Original

Translation

Search Skills

搜索Skill

Overview

概述

Operational Integration

运营集成

Request Contract (/search_multi)

请求契约 (/search_multi)

Response Contract (/search_multi)

响应契约 (/search_multi)

Feedback Contract (/feedback)

反馈契约 (/feedback)

Full Retrieval + Feedback Procedure

完整检索+反馈流程

1) Generate structured query

1) 生成结构化查询

2) Clarification decision

2) 澄清决策

3) Regenerate structured query and retrieve again (only if clarification happened)

3) 重新生成结构化查询并再次检索（仅在进行澄清后执行）

4) Feedback submission

4) 反馈提交

End-to-End Example

端到端示例

1) Pass #1

1) 第一次调用

2) Pass #2

2) 第二次调用

3) Feedback

3) 反馈

Error Handling

错误处理

Completion Rules

完成规则

Common Mistakes

常见错误

Request Contract (
`/search_multi`
)

请求契约 (
`/search_multi`
)

Response Contract (
`/search_multi`
)

响应契约 (
`/search_multi`
)

Feedback Contract (
`/feedback`
)

反馈契约 (
`/feedback`
)