skill-grep

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
3. if needed, ask one clarification
4. call POST /search_multi 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

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).

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)

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

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