https://github.com/mturac/skill-hunter
Pre-execution layer for coding agents — scan the ecosystem for existing skills/tools/MCPs before building from scratch.
https://github.com/mturac/skill-hunter
Last synced: about 2 months ago
JSON representation
Pre-execution layer for coding agents — scan the ecosystem for existing skills/tools/MCPs before building from scratch.
- Host: GitHub
- URL: https://github.com/mturac/skill-hunter
- Owner: mturac
- License: mit
- Created: 2026-04-24T18:03:45.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-24T20:11:41.000Z (about 2 months ago)
- Last Synced: 2026-04-24T20:35:56.494Z (about 2 months ago)
- Language: Python
- Size: 47.9 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Skill Hunter
A pre-execution layer for coding/automation agents (Codex, Claude, OpenClaw, …) that asks a single question before writing any code:
> "Is there already a skill, MCP server, CLI tool, plugin, repo, template, SDK, API, or workflow that can solve this — or accelerate it?"
If yes, it surfaces the best candidate, evaluates risk, and asks for approval before use.
If no, it says so plainly and builds manually with a clean, minimal approach.
The core insight: in agent systems, intelligence is not only knowing how to build — it is knowing **when not to build**.
## Why
The internet is now a landfill of skills, MCPs, plugins, templates, and half-finished repos. The bottleneck for agents is no longer *capability* — it is *discovery*. Skill Hunter sits in front of execution and prevents:
- rebuilding what already exists
- picking the most popular tool instead of the right one
- pulling in abandoned or unsafe repos
- silently installing things that need credentials or system access
## How it works
1. **Classify** the request (coding, design, browser automation, file conversion, scraping, CI/CD, …).
2. **Decide** whether a reusable skill/tool likely exists.
3. **Search** local skills, project docs, GitHub, MCP registry, package managers, tool docs.
4. **Evaluate** candidates by relevance, maintenance, docs, stack fit, security, effort, licensing.
5. **Present** one recommendation, a shortlist of three, or an honest "build it yourself".
6. **Gate** on user approval before running anything external.
## Install
Five distribution channels:
### 1. Claude Code plugin (marketplace)
```text
/plugin marketplace add mturac/skill-hunter
/plugin install skill-hunter@skill-hunter
```
Claude installs both the skill and the `UserPromptSubmit` hook from the plugin manifest — no clone, no shell script.
### 2. Codex CLI plugin
```bash
codex plugin marketplace add mturac/skill-hunter
```
Then enable it in `~/.codex/config.toml`:
```toml
[plugins."skill-hunter@skill-hunter"]
enabled = true
```
Codex pulls the marketplace straight from GitHub, no central registry.
### 3. OpenClaw (ClawHub registry)
```bash
openclaw skills install openclaw-skill-hunter
# or via ClawHub CLI
clawhub install openclaw-skill-hunter
```
Published at [clawhub.com/mturac/openclaw-skill-hunter](https://clawhub.com). Drops into `~/.openclaw/skills/`.
### 4. `npx skills` (Hermes and any other agentskills.io-compatible runtime)
```bash
npx skills add mturac/skill-hunter@skill_hunter -g -y
```
Installs into `~/.agents/skills/skill_hunter/`. The `-g` flag is user-wide; drop it for a per-project install into `./.agents/skills/`.
### 5. Clone + `./install.sh` (development or non-plugin hosts)
Useful when you want the skill to live as a symlink to a checkout so edits propagate without reinstalling:
```bash
git clone https://github.com/mturac/skill-hunter.git
cd skill-hunter
./install.sh all # Claude Code + Codex CLI (skill + hook)
./install.sh status # verify
```
---
Skill Hunter ships as a **skill + hook pair** for each runtime:
- The **skill** (`SKILL.md`) gets picked up when the user's prompt matches its description — the standard [agentskills.io](https://agentskills.io) path.
- The **hook** (`hooks/skill-hunter-hook.sh`) injects the Skill Discovery Pass into *every* interactive turn via `UserPromptSubmit`, so the pass fires even when a more specific skill would otherwise win the matcher.
Clone the repo, then run the installer:
```bash
git clone https://github.com/mturac/skill-hunter.git
cd skill-hunter
./install.sh all # Claude Code + Codex CLI (skill + hook)
./install.sh status # verify
```
Per-runtime:
```bash
./install.sh claude # Claude Code — ~/.claude/skills/skill_hunter + ~/.claude/hooks.json
./install.sh codex # Codex CLI — ~/.codex/skills/skill_hunter + ~/.codex/hooks/hooks.json
./install.sh uninstall # remove skill + hook from both
```
Each runtime target installs **both** the skill and the hook. The skill is symlinked back to the cloned repo so local edits propagate without reinstalling. Hook registration is idempotent (jq-merged into existing `hooks.json`, no clobbering).
Optional runtimes (no hooks — skill only):
```bash
./install.sh openclaw # ~/.openclaw/skills/skill_hunter (copy — OpenClaw rejects symlinks)
./install.sh hermes # ~/.hermes/skills/utility/skill_hunter
./install.sh cursor # ./.cursor/rules/skill-hunter.md (per-project)
```
**Requires:** `jq` (for hook registration). `brew install jq` on macOS.
### What installs where
| Runtime | Skill path | Hook path |
|-----------|---------------------------------------------|--------------------------------------|
| Claude Code | `~/.claude/skills/skill_hunter → repo` | `~/.claude/hooks.json` |
| Codex CLI | `~/.codex/skills/skill_hunter → repo` | `~/.codex/hooks/hooks.json` |
| OpenClaw | `~/.openclaw/skills/skill_hunter/SKILL.md` | — (OpenClaw hook API differs) |
| Hermes | `~/.hermes/skills/utility/skill_hunter/SKILL.md` | — |
The hook only fires in **interactive** Claude / Codex sessions. `codex exec` and Claude's `-p` headless modes currently do not fire `UserPromptSubmit` — for those, the skill's implicit matching is the only mechanism.
## Verify it works
Open `claude` or `codex` (interactive TUI). Type:
```
Scrape e-ticaret sitelerinden fiyat veri çekip günlük CSV olarak kaydet.
```
Expected: a short **"Skill Discovery Pass..."** status indicator, then a structured reply beginning with "Best candidate:" (Name / Type / Why it fits / Risk / Effort) or "Three viable options:", followed by **"Use this? 1/2/3"** before any code is written.
If the pass doesn't fire, run `./install.sh status` and check that both `skill` and `hook` show `✓` for your runtime.
## Response shapes
**One good candidate**
```
A reusable skill/tool looks like a good fit for this.
Best candidate:
- Name: …
- Type: …
- Why it fits: …
- Risk: …
- Effort: …
Use this?
1. Yes 2. No, build manually 3. Show alternatives
```
**Shortlist of three** — side-by-side pros/cons + a pick.
**Nothing good exists** — explicit reason (outdated / too broad / unsafe / low quality), then build manually.
## Examples
See [`examples/`](./examples) for real interactions — single-candidate pick, 3-way shortlist, skipped discovery, "build it yourself", and a credential-scope warning.
## Security posture
- Never install or run unknown tools without approval.
- Always explain credential/permission scope before recommending a tool that needs them.
- Prefer official and well-maintained sources. Flag abandoned repos.
## License
MIT — see [`LICENSE`](./LICENSE).