Search Skills

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>

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

Request Contract (

/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

Response Contract (

/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

Feedback Contract (

/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

Full Retrieval + Feedback Procedure

1) Generate structured query

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

2) Clarification decision

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

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

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

4) Feedback submission

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

End-to-End Example

1) Pass #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
}

2) Pass #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
}

3) Feedback

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

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

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

skill-compass

NPX Install

Tags

SKILL.md Content

Search Skills

Overview

Operational Integration

Request Contract (
`/search_multi`
)

Response Contract (
`/search_multi`
)

Feedback Contract (
`/feedback`
)

Full Retrieval + Feedback Procedure

1) Generate structured query

2) Clarification decision

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

4) Feedback submission

End-to-End Example

1) Pass #1

2) Pass #2

3) Feedback

Error Handling

Completion Rules

Common Mistakes

skill-compass

NPX Install

Tags

SKILL.md Content

Search Skills

Overview

Operational Integration

Request Contract (/search_multi)

Response Contract (/search_multi)

Feedback Contract (/feedback)

Full Retrieval + Feedback Procedure

1) Generate structured query

2) Clarification decision

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

4) Feedback submission

End-to-End Example

1) Pass #1

2) Pass #2

3) Feedback

Error Handling

Completion Rules

Common Mistakes

Request Contract (
`/search_multi`
)

Response Contract (
`/search_multi`
)

Feedback Contract (
`/feedback`
)