agent-skill-search 0.1.0__tar.gz

agent_skill_search-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+*.db
+uv.lock

agent_skill_search-0.1.0/INSTALL.md

@@ -0,0 +1,228 @@
+# Installing skill-search into agent clients
+
+`skill-search` ships an MCP server (`skill-search-mcp`) and a CLI (`skill-search`). Every
+major agent client can use it; the right channel depends on what the client supports:
+
+| Client | Channel | What `install` does |
+| --- | --- | --- |
+| Claude Code | stdio MCP | runs `claude mcp add --scope user` |
+| Codex CLI | stdio MCP | runs `codex mcp add` |
+| OpenClaw | stdio MCP | runs `openclaw mcp add` |
+| Hermes | stdio MCP | runs `hermes mcp add` |
+| Gemini CLI | stdio MCP | merges `~/.gemini/settings.json` |
+| Claude Desktop | stdio MCP | merges `claude_desktop_config.json` |
+| pi | stdio MCP | merges `./mcp.json` (needs the `pi-mcp` extension) |
+| ChatGPT | remote HTTPS MCP | prints self-host instructions (no local config) |
+| Anything else | CLI from a SKILL.md | nothing to install — see below |
+
+## 1. Install the package
+
+Python 3.10+ required.
+
+```bash
+# recommended — isolated tool install, no environment conflicts
+uv tool install agent-skill-search
+# or
+pipx install agent-skill-search
+# or, into the current environment
+pip install agent-skill-search
+```
+
+This gives you:
+
+- `skill-search` — the CLI (`search`, `view`, `list`, `add`, `install`, `uninstall`)
+- `skill-search-mcp` — the MCP server binary
+
+> **Name collision warning:** an unrelated PyPI package named `skill-search` also installs
+> a `skill-search` command. This project's distribution is **`agent-skill-search`**. If both
+> end up in one environment, whichever was installed last owns the command — prefer
+> `uv tool install` / `pipx`, which isolate each tool.
+
+## 2. Prepare a catalog (optional)
+
+The server reads SKILL.md catalogs from, in order:
+
+1. `SKILL_CATALOG_DIRS` (colon-separated, e.g. `~/skills:~/more-skills`)
+2. `~/.agents/skills-catalog` (default; created on demand)
+3. `./.agents/skills-catalog` (project-local default)
+
+`skill-search install` writes the resolved catalog dirs into each client's config as
+`SKILL_CATALOG_DIRS`, so the client does not need the env var set. Override per install:
+
+```bash
+skill-search install gemini --catalog ~/my-skills --catalog ~/team-skills
+```
+
+## 3. Install into clients
+
+Run `skill-search install --list` for the registry, then per client:
+
+### Claude Code
+
+```bash
+skill-search install claude-code            # claude mcp add --scope user
+skill-search install claude-code --dry-run  # print the command, write nothing
+```
+
+Verify: `claude mcp list`, or `/mcp` inside a session.
+
+### Codex CLI
+
+```bash
+skill-search install codex
+```
+
+Verify: `codex mcp list`, then start `codex` and confirm the `skill_search` tools.
+
+If your Codex version's `mcp add` does not accept `-e KEY=VALUE`, remove the
+`[mcp_servers.skill-search]` entry it may have half-written and add it by hand:
+
+```toml
+[mcp_servers.skill-search]
+command = "/absolute/path/to/skill-search-mcp"
+env = { "SKILL_CATALOG_DIRS" = "/path/to/catalog" }
+```
+
+### Gemini CLI
+
+```bash
+skill-search install gemini
+```
+
+Merges `mcpServers` into `~/.gemini/settings.json`, backs the file up first
+(`settings.json.bak-1`), and refuses to touch a malformed file. Verify: run `gemini`
+and use `/mcp`.
+
+Manual fallback:
+
+```json
+{
+  "mcpServers": {
+    "skill-search": {
+      "command": "/absolute/path/to/skill-search-mcp",
+      "args": [],
+      "env": { "SKILL_CATALOG_DIRS": "/path/to/catalog" }
+    }
+  }
+}
+```
+
+### OpenClaw
+
+```bash
+skill-search install openclaw
+```
+
+Verify: `/mcp` in an OpenClaw session. If your OpenClaw version has no `mcp add`
+command, add the entry under `mcp.servers` in `~/.openclaw/openclaw.json` by hand —
+same shape as the Gemini snippet above, nested under `"mcp": {"servers": {...}}`.
+
+### Hermes
+
+```bash
+skill-search install hermes
+```
+
+Hermes config is YAML, so the installer goes through `hermes mcp add` rather than
+editing the file. Manual fallback: add a `skill-search` entry under `mcp_servers` in
+`~/.hermes/config.yaml`.
+
+### pi
+
+```bash
+skill-search install pi
+```
+
+Writes `mcp.json` in the **current project root**. Requires the
+[`pi-mcp` extension](https://github.com/badlogic/pi-mcp) in that project. Verify:
+restart pi and check the tool list.
+
+### Claude Desktop
+
+```bash
+skill-search install claude-desktop
+```
+
+macOS/Windows only (there is no official Linux build). Merges `mcpServers` into:
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+Verify: fully quit and reopen Claude Desktop — the server appears under
+Settings → Connectors / the tools icon. Logs: `~/Library/Logs/Claude/mcp*.log`
+(macOS) or `%APPDATA%\Claude\logs` (Windows).
+
+### ChatGPT (self-hosted connector)
+
+ChatGPT cannot run local stdio MCP servers. It connects to remote HTTPS MCP
+endpoints, so run this server in HTTP mode and expose it over TLS:
+
+```bash
+skill-search-mcp --http --host 127.0.0.1 --port 8787
+# then terminate TLS and forward, e.g. with Caddy:
+#   caddy reverse-proxy --from mcp.example.com --to 127.0.0.1:8787
+```
+
+In ChatGPT: **Settings → Apps & Connectors → enable Developer mode → Create**,
+with Server URL `https://your-domain/mcp`.
+
+Server flags: `--host` (default `127.0.0.1`), `--port` (default `8787`).
+
+> **Warning:** the endpoint publishes the whole catalog, read-only, to anyone who can
+> reach it. The server implements no auth — authentication and TLS are the reverse
+> proxy's job. Keep it behind auth or a private network. Binding a non-loopback host
+> disables the SDK's DNS-rebinding protection for exactly this reason.
+
+### Any other agent (CLI fallback)
+
+Agents that load `SKILL.md` skills but have no MCP support can shell out to the CLI.
+Install the package, then drop this repo's `SKILL.md` into their skills directory and
+point the agent at:
+
+```bash
+skill-search search "react performance"   # find skills
+skill-search view "react-perf"            # load one
+```
+
+## CLI usage hint for agents without MCP
+
+Agents without an MCP connection can still call the CLI directly. Opt in with
+`--cli-hint` to append a short usage snippet to existing `CLAUDE.md`/`AGENTS.md`
+files (`~/.claude/CLAUDE.md`, `~/CLAUDE.md`, `~/AGENTS.md`, `./CLAUDE.md`,
+`./AGENTS.md`). Append-only: marker-checked, skipped when already present,
+backed up before the write, never created from scratch. `--dry-run` shows
+what would change. `uninstall --cli-hint` removes the snippet again.
+
+```bash
+skill-search install gemini --cli-hint             # MCP config + hint snippet
+skill-search install gemini --cli-hint --dry-run   # preview both, write nothing
+```
+
+## Uninstall
+
+```bash
+skill-search uninstall claude-code    # claude mcp remove
+skill-search uninstall gemini         # removes the JSON entry, keeps a backup
+skill-search uninstall --all          # every detected client
+skill-search uninstall gemini --cli-hint  # also removes the hint snippet
+```
+
+## Troubleshooting
+
+- **Server won't start in the client** — the config must reference an absolute path.
+  The installer resolves `skill-search-mcp` on your `PATH` and writes the absolute
+  location; if it wasn't found it writes `<python> -m skill_search.server` instead
+  (printed at install time). Hand-edited configs must do the same.
+- **No skills found** — `SKILL_CATALOG_DIRS` is colon-separated
+  (`dir1:dir2`). Check what got written with `skill-search install <client> --dry-run`,
+  and test locally with `SKILL_CATALOG_DIRS=... skill-search list`.
+- **`skill-search` command belongs to another package** — see the collision warning
+  above; use `uv tool install agent-skill-search` or `pipx`.
+- **Claude Desktop logs** — `~/Library/Logs/Claude/mcp*.log` (macOS),
+  `%APPDATA%\Claude\logs` (Windows).
+- **`skill-search add` moves directories** — it moves skill dirs out of the source
+  tree into `~/.agents/skills-catalog` (not a copy).
+- **Client config schema drift** — command-backed clients (Claude Code, Codex,
+  OpenClaw, Hermes) delegate to their own `mcp add`, so their vendor owns the schema.
+  The file-backed targets (Gemini CLI, Claude Desktop, pi) are the ones that may need
+  updates if their config format changes.

agent_skill_search-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kinged007
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_skill_search-0.1.0/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.5
+Name: agent-skill-search
+Version: 0.1.0
+Summary: Portable skill catalog search for AI agents — MCP server + CLI
+Project-URL: Homepage, https://github.com/kinged007/agent-skill-search
+Project-URL: Repository, https://github.com/kinged007/agent-skill-search
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: mcp>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# skill-search
+
+Portable skill catalog search for AI agents. MCP server + CLI.
+
+Universal skill search tool. Use grep like search terms to find relevant skills for your task. Always use this tool.
+
+## Install
+
+```bash
+# recommended — isolated tool install
+uv tool install agent-skill-search
+# or
+pip install agent-skill-search
+```
+
+> The PyPI distribution is **`agent-skill-search`** — the name `skill-search` on PyPI
+> belongs to an unrelated package. The commands stay `skill-search` and `skill-search-mcp`.
+
+## Usage
+
+### CLI
+
+```bash
+export SKILL_CATALOG_DIRS="$HOME/.hermes/skills"
+
+skill-search search "react performance"
+skill-search view "vercel-react-best-practices"
+skill-search list
+
+# Move skills from a source dir into the catalog (frees agent context).
+# Note: `add` MOVES directories out of the source tree, it does not copy.
+skill-search add ~/.hermes/skills
+```
+
+### MCP server
+
+One command installs it into your client:
+
+```bash
+skill-search install claude-code   # or codex / gemini / openclaw / hermes / pi / claude-desktop / chatgpt
+```
+
+See **[INSTALL.md](INSTALL.md)** for per-client details, manual config snippets, the
+ChatGPT remote-HTTP setup, and troubleshooting.

agent_skill_search-0.1.0/README.md

@@ -0,0 +1,44 @@
+# skill-search
+
+Portable skill catalog search for AI agents. MCP server + CLI.
+
+Universal skill search tool. Use grep like search terms to find relevant skills for your task. Always use this tool.
+
+## Install
+
+```bash
+# recommended — isolated tool install
+uv tool install agent-skill-search
+# or
+pip install agent-skill-search
+```
+
+> The PyPI distribution is **`agent-skill-search`** — the name `skill-search` on PyPI
+> belongs to an unrelated package. The commands stay `skill-search` and `skill-search-mcp`.
+
+## Usage
+
+### CLI
+
+```bash
+export SKILL_CATALOG_DIRS="$HOME/.hermes/skills"
+
+skill-search search "react performance"
+skill-search view "vercel-react-best-practices"
+skill-search list
+
+# Move skills from a source dir into the catalog (frees agent context).
+# Note: `add` MOVES directories out of the source tree, it does not copy.
+skill-search add ~/.hermes/skills
+```
+
+### MCP server
+
+One command installs it into your client:
+
+```bash
+skill-search install claude-code   # or codex / gemini / openclaw / hermes / pi / claude-desktop / chatgpt
+```
+
+See **[INSTALL.md](INSTALL.md)** for per-client details, manual config snippets, the
+ChatGPT remote-HTTP setup, and troubleshooting.

agent_skill_search-0.1.0/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: skill-search
+description: "Universal skill search tool. Use grep like search terms to find relevant skills for your task. Always use this tool."
+---
+
+# Skill Search
+
+A portable tool that lets agents search through a catalog of SKILL.md files and load only the relevant ones — instead of dumping 100+ skills into context.
+
+## How It Works
+
+The tool has two modes:
+
+1. **MCP Server** — for Claude Code, Claude Desktop, Codex, Gemini CLI, OpenClaw, Hermes, pi, or any MCP-capable agent. Exposes `skill_search`, `skill_view`, and `skill_list` as tools.
+2. **CLI** — for any agent. Run `skill-search search <query>` to find skills, `skill-search view <name>` to load one.
+
+## Setup
+
+Install the package first (distribution name is `agent-skill-search`):
+
+```bash
+uv tool install agent-skill-search
+# or: pip install agent-skill-search
+```
+
+### Option A: MCP Server (recommended)
+
+One command per client:
+
+```bash
+skill-search install claude-code   # or codex / gemini / openclaw / hermes / pi / claude-desktop
+```
+
+Manual fallback for any `mcpServers`-style JSON config:
+
+```json
+{
+  "mcpServers": {
+    "skill-search": {
+      "command": "/absolute/path/to/skill-search-mcp",
+      "args": [],
+      "env": {
+        "SKILL_CATALOG_DIRS": "/path/to/your/skills:/path/to/more/skills"
+      }
+    }
+  }
+}
+```
+
+Or with `uvx` (note the `--from`, since the distribution is `agent-skill-search`):
+
+```json
+{
+  "mcpServers": {
+    "skill-search": {
+      "command": "uvx",
+      "args": ["--from", "agent-skill-search", "skill-search-mcp"],
+      "env": {
+        "SKILL_CATALOG_DIRS": "~/.hermes/skills:~/.agents/skills"
+      }
+    }
+  }
+}
+```
+
+Full per-client instructions, the ChatGPT remote-HTTP setup, and troubleshooting:
+**[INSTALL.md](INSTALL.md)**.
+
+### Option B: CLI (any agent)
+
+```bash
+pip install agent-skill-search
+
+# Set your catalog directories (colon-separated)
+export SKILL_CATALOG_DIRS="$HOME/.hermes/skills:$HOME/.agents/skills"
+
+# Search
+skill-search search "react performance"
+
+# View a skill
+skill-search view "vercel-react-best-practices"
+
+# List all
+skill-search list
+```
+
+### Option C: Local development
+
+```bash
+cd skill-search
+pip install -e .
+export SKILL_CATALOG_DIRS="."
+skill-search list
+```
+
+## Catalog management
+
+`skill-search add <dir>` **moves** skill directories out of the source tree into
+`~/.agents/skills-catalog` — it does not copy them. The originals will no longer be in
+place for the tool they came from.
+
+## Usage Pattern for Agents
+
+1. **Discover** — run `skill_search(query="your topic")` to find matching skills
+2. **Evaluate** — read the name + description from results
+3. **Load** — run `skill_view(name="the-skill")` to get full instructions
+4. **Execute** — follow the skill's procedure
+
+This keeps context lean: only the catalog index (~3k tokens) plus the one skill you actually need.
+
+## Catalog Structure
+
+Point the tool at directories containing SKILL.md files:
+
+```
+your-catalog/
+├── react-performance/
+│   └── SKILL.md
+├── kubernetes-deploy/
+│   └── SKILL.md
+└── api-design/
+    └── SKILL.md
+```
+
+Any directory tree containing SKILL.md files works — the tool scans recursively.

agent_skill_search-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agent-skill-search"
+version = "0.1.0"
+description = "Portable skill catalog search for AI agents — MCP server + CLI"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+dependencies = [
+    "mcp>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest"]
+
+[project.scripts]
+skill-search = "skill_search.cli:main"
+skill-search-mcp = "skill_search.server:run"
+
+[project.urls]
+Homepage = "https://github.com/kinged007/agent-skill-search"
+Repository = "https://github.com/kinged007/agent-skill-search"
+
+[tool.hatch.build.targets.wheel]
+packages = ["skill_search"]

agent_skill_search-0.1.0/skill_search/__init__.py

@@ -0,0 +1,3 @@
+"""Skill Search — portable skill catalog search for AI agents."""
+
+__version__ = "0.1.0"