# skill-grep

Adopt this skill: https://proskills.md/skills/other/littledinoc-skill-grep-skills-skill-grep

Page: https://proskills.md/skills/other/littledinoc-skill-grep-skills-skill-grep
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/skill-grep/SKILL.md
size: 8000
upstream: https://github.com/littledinoc/skill-grep/blob/main/skills/skill-grep/SKILL.md

````text
---
name: skill-grep
description: 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.
---

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

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

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

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
1. call `POST /search_multi_field` with:
   - `round=1`
   - `clarification_used=false`
   - `retrieval_session_id` generated once and reused
2. 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

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

```json
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, deplo
````

## File: README.md
upstream: https://github.com/littledinoc/skill-grep/blob/main/README.md

````text
<h1 align="center">Skill Grep</h1>

<p align="center">
  <strong>Navigate the skill universe — Stop reinventing the wheel, start discovering.</strong>
</p>

A smart skill search engine for agents — discover reusable skills and workflows instantly.

🌐 Try the Web Version: [skillgrep.net](https://www.skillgrep.net/) . Search skills directly in your browser!

## 🌟 Why Skill Grep?

**Finding the right skill shouldn't be harder than building it yourself.**

When you need a capability, you shouldn't have to:
- Wonder if a solution already exists
- Manually browse multiple marketplaces
- Guess which skills are actually high-quality

Skill Grep searches across sources using multi-field retrieval and returns ranked recommendations with quality signals (e.g., GitHub stars), so you can quickly find the best option.

## 🛠️ How It Works

```text
1. You: "I need a skill for CI/CD automation"

2. Skill Grep:
   ├── Builds structured query from your intent
   ├── Calls search API with query fields
   ├── (Optional) Asks one clarification question if needed
   └── Returns 1-3 ranked recommendations

3. You: Select the best match
   └── Skill Grep learns from your feedback
```

## ✨ Key Features

| Feature | Description |
|---------|-------------|
| Smart Retrieval | Jointly searches over name, description, and usage context for better relevance |
| Quality Signals | Shows relevance + GitHub stars |
| Clarification Loop | Asks one targeted question if results are ambiguous |
| Feedback Telemetry | Continuously improves ranking |

## 🚀 Installation

### For Claude Code

You can register this repository as a Claude Code Plugin marketplace by running the following command in Claude Code:

```bash
/plugin marketplace add LittleDinoC/skill-grep
```

```bash
/plugin install skill-grep@skill-grep
```

### Option 1: Via skill manager

```bash
npx skills add https://github.com/LittleDinoC/skill-grep --skill skill-grep
```

### Option 2: Manual install

You can download the specific skill folder and place it in your skills directory.

```bash
# Navigate to your skills directory (e.g., for OpenClaw)
cd ~/.openclaw/skills 

# Extract only the specific skill folder
npx degit LittleDinoC/skill-grep/skills/skill-grep skill-grep
```

Note: This installs only the skill-grep package without cloning the entire repository history.

## 🔍 Usage

The skill activates automatically when you ask your agent to discover, find, or search for skills.

### Example Sessions

Simple search:

```
You: "Find me a skill for git commit conventions"

Skill Grep:
> Searching for skills...

Recommendations:
1. conventional-commits (github/awesome-copilot, 26.8k repo stars ⭐)
   Best for: Structured commit message generation following Conventional Commits specification.
   This skill guides you through creating standardized, descriptive commit messages with a structured XML format. It includes instructions, examples, and validation to ensure your commits follow the Conventional Commits specification.

2. git-commit (github/awesome-copilot, 26.8k repo stars ⭐)
   Best for: Complete commit workflow with intelligent staging
   A more comprehensive option that handles the full git commit workflow: auto-detecting type and scope from changes, generating conventional commit messages from diff, interactive commits with overrides, and intelligent file staging for logical grouping.
```

Search with clarification:

```
You: "I need a skill for testing"

Skill Grep:
> I found several testing skills, but they serve different purposes. What type of testing do you need?
   1. Test-Driven Development (TDD) — Write tests first, then implement code to make them pass
   2. Test Generation — Generate comprehensive tests for existing code (multi-language)
   3. Language-Specific Testing — Focused testing for specific languages (Python, C++, etc.)

You: "End-to-end testing"

Skill Grep:
> Refined search...

Recommendations:
1. e2e-testing-patterns (wshobson/agents, 32.3k repo stars ⭐)
   - Fit: Master E2E testing with Playwright and Cypress, flaky test debugging, CI/CD integration.
```

## 🎯 Search Behavior

| Scenario | Behavior |
|----------|----------|
| Clear intent | Returns top recommendations immediately |
| Ambiguous results | Asks exactly one clarification question |
| No results | Prompts for refined intent |
| User verdict | Sends feedback for ranking improvement |

## 📚 Research & Citation

Skill Grep is the practical extension of our paper [Multi-Field Tool Retrieval](https://arxiv.org/abs/2602.05366). While the paper proposes a framework for retrieving tools across multiple metadata fields, this project brings those insights into a functional search engine for AI agents.

If you find this work helpful for your research or projects, please cite our paper:

```text
@misc{tang2026multifieldtoolretrieval,
   title={Multi-Field Tool Retrieval}, 
   author={Yichen Tang and Weihang Su and Yiqun Liu and Qingyao Ai},
   year={2026},
   eprint={2602.05366},
   archivePrefix={arXiv},
   primaryClass={cs.IR},
   url={https://arxiv.org/abs/2602.05366}, 
}
```

## ⚖️ License

Released under the Apache License 2.0.

## 📋 User Agreement

By using Skill Grep, you agree to our [User Agreement](USER_AGREEMENT.md).

Data Collection Notice: We collect search interaction data (without involving personal privacy information) to construct public research datasets. This helps advance research in skill retrieval and agent capabilities. See the [User Agreement](USER_AGREEMENT.md) for full details.
````
