Skill Grep

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:

1. build structured query
2. call POST /search_multi_field
3. if needed, ask one clarification
4. call POST /search_multi_field again
5. return 1-3 final recommendations
6. 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

Operational Integration

• base URL env: https://skills.megatechai.com/
• search endpoint: POST /search_multi_field
• 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_field)

{
  "origin_query": "user's original input query",
  "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:

• origin_query: user's original natural language input
• 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
• keep origin_query as the original user input (may be non-English)

Response Contract (/search_multi_field)

{
  "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:

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

Session-level feedback:

{
  "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

1. Transform user need into these fields:
   • origin_query: user's original input (keep as-is, may be non-English)
   • 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
2. call POST /search_multi_field with:
   • round=1
   • clarification_used=false
   • retrieval_session_id generated once and reused
3. 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)

1. regenerate full query object (not only a raw append)
2. call POST /search_multi_field with:
   • origin_query: same as pass #1 (user's original input)
   • round=2
   • same retrieval_session_id
   • parent_search_id=search_id_round1
   • clarification_used=true
   • short clarification_text
3. 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

POST /search_multi_field
{
  "origin_query": "I need a skill to help me write and validate new skills",
  "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

POST /search_multi_field
{
  "origin_query": "I need a skill to help me write and validate new skills",
  "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

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

Installing Skills

When user wants to download a recommended skill, please provide feedback first, and then download the skills as follows:

Option 1: Primary method (one-click install):

npx skills add https://github.com/owner/repo --skill skill_name

Example for a skill frontend-design from repo anthropics/skills:

npx skills add https://github.com/anthropics/skills --skill frontend-design

Option 2: Manual download:

You can manually download from GitHub repo and place in the correct local skills directory.

Common Mistakes

• parsing /search_multi_field as array root instead of envelope response
• forgetting to include origin_query in the request
• 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