OpenSkillIndex← back to search
claude-code

skill-grep

Use when a user is trying to discover an installable or reusable skill or workflow, especially when they ask for a skill for a task, want to compare nearby skill categories, or need help narrowing discovery results.

install
source · Clone the upstream repo
git clone https://github.com/LittleDinoC/skill-grep
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/LittleDinoC/skill-grep "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/skill-grep" ~/.claude/skills/littledinoc-skill-grep-skill-grep && rm -rf "$T"
manifest: skills/skill-grep/SKILL.md
source content

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