skillmesh 0.1.0__tar.gz

skillmesh-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Open Skill Registry Contributors
+
+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.

skillmesh-0.1.0/PKG-INFO

@@ -0,0 +1,298 @@
+Metadata-Version: 2.4
+Name: skillmesh
+Version: 0.1.0
+Summary: A retrieval-gated skill architecture for LLM agents that scales to hundreds of tools by exposing only the top-K relevant capabilities per request.
+Author: Open Skill Registry Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/varunreddy/SkillMesh
+Project-URL: Repository, https://github.com/varunreddy/SkillMesh
+Project-URL: Issues, https://github.com/varunreddy/SkillMesh/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: rank-bm25>=0.2.2
+Requires-Dist: jsonschema>=4.0
+Requires-Dist: chromadb>=0.5.0
+Provides-Extra: dense
+Requires-Dist: sentence-transformers>=2.7.0; extra == "dense"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.6.0; extra == "dev"
+Dynamic: license-file
+
+# SkillMesh
+
+[![CI](https://github.com/varunreddy/SkillMesh/actions/workflows/ci.yml/badge.svg)](https://github.com/varunreddy/SkillMesh/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+
+**Stop stuffing hundreds of tools into your LLM prompt. Route to the right ones.**
+
+## The Problem
+
+LLM agents break when you load every tool into the prompt. Token counts explode, accuracy drops, and cost scales linearly with your catalog size. Teams with 50+ skills end up with bloated system prompts that confuse the model and burn budget.
+
+SkillMesh solves this with retrieval-based routing: given a user query, it selects only the top-K most relevant expert cards and injects them into the prompt — keeping context small, accurate, and cheap.
+
+## Before vs After
+
+| | Without SkillMesh | With SkillMesh |
+|---|---|---|
+| **Prompt tokens** | ~50,000+ (all tools loaded) | ~3,000 (top-K only) |
+| **Tool selection** | Model guesses from a huge list | BM25+Dense retrieval picks the best match |
+| **Cost per call** | High (full catalog every time) | Low (only relevant cards) |
+| **Accuracy** | Degrades as catalog grows | Stays consistent |
+| **Multi-domain tasks** | Confusing for the model | Routed precisely (clean + train + deploy) |
+
+## How It Works
+
+```
+User Query
+    │
+    ▼
+┌─────────────────────┐
+│  BM25 + Dense Index  │  ← Scores every card in your registry
+└─────────┬───────────┘
+          │
+          ▼
+┌─────────────────────┐
+│   RRF Fusion Rank    │  ← Merges sparse + dense rankings
+└─────────┬───────────┘
+          │
+          ▼
+┌─────────────────────┐
+│   Top-K Card Select  │  ← Returns the K best expert cards
+└─────────┬───────────┘
+          │
+          ▼
+┌─────────────────────┐
+│  Agent acts as expert │  ← Full instructions injected into prompt
+└─────────────────────┘
+```
+
+Each card contains: execution behavior, decision trees, anti-patterns, output contracts, and composability hints — everything the agent needs to act as a domain expert.
+
+## One-line MCP install (Claude Desktop / Claude Code)
+
+Add this to your Claude Desktop config (`claude_desktop_config.json`) or Claude Code MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "skillmesh": {
+      "command": "uvx",
+      "args": ["--from", "skillmesh[mcp]", "skillmesh-mcp"]
+    }
+  }
+}
+```
+
+No env vars. No file paths. No cloning. The bundled registry is included in the package.
+
+Requires [uv](https://docs.astral.sh/uv/getting-started/installation/) to be installed.
+
+## 60-Second Demo
+
+```bash
+git clone https://github.com/varunreddy/SkillMesh.git
+cd SkillMesh
+pip install -e .
+skillmesh emit \
+  --provider claude \
+  --registry examples/registry/tools.json \
+  --query "clean messy sales data, train a baseline model, and generate charts" \
+  --top-k 5
+```
+
+Output (truncated):
+
+```
+<context>
+  <card id="data.data-cleaning" title="Data Cleaning and Validation Expert">
+    # Data Cleaning and Validation Expert
+    Specialist in detecting and correcting data quality issues...
+  </card>
+  <card id="ml.sklearn-modeling" title="Scikit-learn Modeling and Evaluation">
+    ...
+  </card>
+  <card id="viz.matplotlib-seaborn" title="Visualization with Matplotlib and Seaborn">
+    ...
+  </card>
+</context>
+```
+
+Only the relevant experts are injected — the rest of the 90+ card catalog stays out of the prompt.
+
+## Integrations
+
+| Platform | Method | Status | Docs |
+|---|---|---|---|
+| **Claude Code** | MCP server | Supported | [Setup guide](docs/integrations/claude-code.md) |
+| **Claude Desktop** | MCP server | Supported | [Setup guide](docs/integrations/claude-desktop.md) |
+| **Codex** | Skill bundle | Supported | [Setup guide](docs/integrations/codex.md) |
+
+### Claude MCP Server
+
+The easiest way to run it is via `uvx` (see "One-line MCP install" above). For local development:
+
+```bash
+pip install -e .[mcp]
+skillmesh-mcp
+```
+
+The server auto-discovers the registry: env var `SKILLMESH_REGISTRY` → repo root → bundled registry.
+
+Exposes two tools via MCP:
+- `route_with_skillmesh(query, top_k)` — provider-formatted context block
+- `retrieve_skillmesh_cards(query, top_k)` — structured JSON payload
+
+Copy-ready config templates in `examples/mcp/`.
+
+### Codex Skill Bundle
+
+```bash
+$skill-installer install https://github.com/varunreddy/SkillMesh/tree/main/skills/skillmesh
+```
+
+## Quickstart
+
+### Install
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e .[dev]
+```
+
+Optional extras:
+
+```bash
+pip install -e .[dense]   # Dense reranking with sentence-transformers
+pip install -e .[mcp]     # Claude MCP server
+```
+
+### Retrieve top-K cards
+
+```bash
+skillmesh retrieve \
+  --registry examples/registry/tools.json \
+  --query "set up nginx reverse proxy with SSL" \
+  --top-k 3
+```
+
+### Emit provider-ready context
+
+```bash
+skillmesh emit \
+  --provider claude \
+  --registry examples/registry/tools.json \
+  --query "deploy container to GCP Cloud Run" \
+  --top-k 5
+```
+
+## Curated Registries
+
+Use domain-specific registries for tighter routing:
+
+| Registry | Domain | Cards |
+|---|---|---|
+| `tools.json` / `tools.yaml` | Full catalog | 90+ |
+| `ml-engineering.registry.yaml` | ML training & evaluation | 15 |
+| `data-engineering.registry.yaml` | Pipelines & data platforms | 10 |
+| `bi-analytics.registry.yaml` | BI & dashboards | 10 |
+| `devops.registry.yaml` | DevOps & infrastructure | 8 |
+| `web-apis.registry.yaml` | API design & patterns | 7 |
+| `cloud-gcp.registry.yaml` | Google Cloud Platform | 7 |
+| `cloud-bi.registry.yaml` | Cloud BI | 5 |
+| `roles.registry.yaml` | Role orchestrators | 10 |
+
+```bash
+skillmesh emit \
+  --provider claude \
+  --registry examples/registry/devops.registry.yaml \
+  --query "configure prometheus alerting and grafana dashboards" \
+  --top-k 3
+```
+
+## CLI Commands
+
+| Command | Description |
+|---|---|
+| `skillmesh retrieve` | Top-K retrieval payload (JSON) |
+| `skillmesh emit` | Provider-formatted context block |
+| `skillmesh index` | Index registry into Chroma for persistent retrieval |
+| `skillmesh-mcp` | Stdio MCP server for Claude |
+
+```bash
+skillmesh --help
+```
+
+## Repository Layout
+
+```
+src/skill_registry_rag/
+├── models.py          # Tool/role card models
+├── registry.py        # Registry loading + validation
+├── retriever.py       # BM25 + optional dense retrieval
+├── adapters/          # Provider formatters (codex, claude)
+└── cli.py             # skillmesh CLI
+
+examples/registry/
+├── tools.json         # Full tool catalog
+├── tools.yaml         # YAML version of full catalog
+├── instructions/      # Expert instruction files (90+)
+├── roles/             # Role orchestrator files
+└── *.registry.yaml    # Domain-specific registries
+
+skills/skillmesh/      # Codex-installable skill
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how to add expert cards, create registries, and submit PRs.
+
+## Troubleshooting
+
+### `skillmesh: command not found`
+
+```bash
+pip install -e .
+```
+
+### Missing registry path
+
+The CLI and MCP server auto-discover the registry. If auto-discovery fails, pass `--registry` or set:
+
+```bash
+export SKILLMESH_REGISTRY=/path/to/tools.json
+# or pass --registry on every command
+```
+
+### `skillmesh-mcp` fails to start
+
+```bash
+pip install -e .[mcp]
+```
+
+### Codex does not detect new skill
+
+Restart Codex after running `$skill-installer`.
+
+## Development
+
+```bash
+ruff check src tests
+pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+If SkillMesh helps your team, please **star the repo** — it directly improves discoverability and helps others find the project.

skillmesh-0.1.0/README.md

@@ -0,0 +1,271 @@
+# SkillMesh
+
+[![CI](https://github.com/varunreddy/SkillMesh/actions/workflows/ci.yml/badge.svg)](https://github.com/varunreddy/SkillMesh/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+
+**Stop stuffing hundreds of tools into your LLM prompt. Route to the right ones.**
+
+## The Problem
+
+LLM agents break when you load every tool into the prompt. Token counts explode, accuracy drops, and cost scales linearly with your catalog size. Teams with 50+ skills end up with bloated system prompts that confuse the model and burn budget.
+
+SkillMesh solves this with retrieval-based routing: given a user query, it selects only the top-K most relevant expert cards and injects them into the prompt — keeping context small, accurate, and cheap.
+
+## Before vs After
+
+| | Without SkillMesh | With SkillMesh |
+|---|---|---|
+| **Prompt tokens** | ~50,000+ (all tools loaded) | ~3,000 (top-K only) |
+| **Tool selection** | Model guesses from a huge list | BM25+Dense retrieval picks the best match |
+| **Cost per call** | High (full catalog every time) | Low (only relevant cards) |
+| **Accuracy** | Degrades as catalog grows | Stays consistent |
+| **Multi-domain tasks** | Confusing for the model | Routed precisely (clean + train + deploy) |
+
+## How It Works
+
+```
+User Query
+    │
+    ▼
+┌─────────────────────┐
+│  BM25 + Dense Index  │  ← Scores every card in your registry
+└─────────┬───────────┘
+          │
+          ▼
+┌─────────────────────┐
+│   RRF Fusion Rank    │  ← Merges sparse + dense rankings
+└─────────┬───────────┘
+          │
+          ▼
+┌─────────────────────┐
+│   Top-K Card Select  │  ← Returns the K best expert cards
+└─────────┬───────────┘
+          │
+          ▼
+┌─────────────────────┐
+│  Agent acts as expert │  ← Full instructions injected into prompt
+└─────────────────────┘
+```
+
+Each card contains: execution behavior, decision trees, anti-patterns, output contracts, and composability hints — everything the agent needs to act as a domain expert.
+
+## One-line MCP install (Claude Desktop / Claude Code)
+
+Add this to your Claude Desktop config (`claude_desktop_config.json`) or Claude Code MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "skillmesh": {
+      "command": "uvx",
+      "args": ["--from", "skillmesh[mcp]", "skillmesh-mcp"]
+    }
+  }
+}
+```
+
+No env vars. No file paths. No cloning. The bundled registry is included in the package.
+
+Requires [uv](https://docs.astral.sh/uv/getting-started/installation/) to be installed.
+
+## 60-Second Demo
+
+```bash
+git clone https://github.com/varunreddy/SkillMesh.git
+cd SkillMesh
+pip install -e .
+skillmesh emit \
+  --provider claude \
+  --registry examples/registry/tools.json \
+  --query "clean messy sales data, train a baseline model, and generate charts" \
+  --top-k 5
+```
+
+Output (truncated):
+
+```
+<context>
+  <card id="data.data-cleaning" title="Data Cleaning and Validation Expert">
+    # Data Cleaning and Validation Expert
+    Specialist in detecting and correcting data quality issues...
+  </card>
+  <card id="ml.sklearn-modeling" title="Scikit-learn Modeling and Evaluation">
+    ...
+  </card>
+  <card id="viz.matplotlib-seaborn" title="Visualization with Matplotlib and Seaborn">
+    ...
+  </card>
+</context>
+```
+
+Only the relevant experts are injected — the rest of the 90+ card catalog stays out of the prompt.
+
+## Integrations
+
+| Platform | Method | Status | Docs |
+|---|---|---|---|
+| **Claude Code** | MCP server | Supported | [Setup guide](docs/integrations/claude-code.md) |
+| **Claude Desktop** | MCP server | Supported | [Setup guide](docs/integrations/claude-desktop.md) |
+| **Codex** | Skill bundle | Supported | [Setup guide](docs/integrations/codex.md) |
+
+### Claude MCP Server
+
+The easiest way to run it is via `uvx` (see "One-line MCP install" above). For local development:
+
+```bash
+pip install -e .[mcp]
+skillmesh-mcp
+```
+
+The server auto-discovers the registry: env var `SKILLMESH_REGISTRY` → repo root → bundled registry.
+
+Exposes two tools via MCP:
+- `route_with_skillmesh(query, top_k)` — provider-formatted context block
+- `retrieve_skillmesh_cards(query, top_k)` — structured JSON payload
+
+Copy-ready config templates in `examples/mcp/`.
+
+### Codex Skill Bundle
+
+```bash
+$skill-installer install https://github.com/varunreddy/SkillMesh/tree/main/skills/skillmesh
+```
+
+## Quickstart
+
+### Install
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e .[dev]
+```
+
+Optional extras:
+
+```bash
+pip install -e .[dense]   # Dense reranking with sentence-transformers
+pip install -e .[mcp]     # Claude MCP server
+```
+
+### Retrieve top-K cards
+
+```bash
+skillmesh retrieve \
+  --registry examples/registry/tools.json \
+  --query "set up nginx reverse proxy with SSL" \
+  --top-k 3
+```
+
+### Emit provider-ready context
+
+```bash
+skillmesh emit \
+  --provider claude \
+  --registry examples/registry/tools.json \
+  --query "deploy container to GCP Cloud Run" \
+  --top-k 5
+```
+
+## Curated Registries
+
+Use domain-specific registries for tighter routing:
+
+| Registry | Domain | Cards |
+|---|---|---|
+| `tools.json` / `tools.yaml` | Full catalog | 90+ |
+| `ml-engineering.registry.yaml` | ML training & evaluation | 15 |
+| `data-engineering.registry.yaml` | Pipelines & data platforms | 10 |
+| `bi-analytics.registry.yaml` | BI & dashboards | 10 |
+| `devops.registry.yaml` | DevOps & infrastructure | 8 |
+| `web-apis.registry.yaml` | API design & patterns | 7 |
+| `cloud-gcp.registry.yaml` | Google Cloud Platform | 7 |
+| `cloud-bi.registry.yaml` | Cloud BI | 5 |
+| `roles.registry.yaml` | Role orchestrators | 10 |
+
+```bash
+skillmesh emit \
+  --provider claude \
+  --registry examples/registry/devops.registry.yaml \
+  --query "configure prometheus alerting and grafana dashboards" \
+  --top-k 3
+```
+
+## CLI Commands
+
+| Command | Description |
+|---|---|
+| `skillmesh retrieve` | Top-K retrieval payload (JSON) |
+| `skillmesh emit` | Provider-formatted context block |
+| `skillmesh index` | Index registry into Chroma for persistent retrieval |
+| `skillmesh-mcp` | Stdio MCP server for Claude |
+
+```bash
+skillmesh --help
+```
+
+## Repository Layout
+
+```
+src/skill_registry_rag/
+├── models.py          # Tool/role card models
+├── registry.py        # Registry loading + validation
+├── retriever.py       # BM25 + optional dense retrieval
+├── adapters/          # Provider formatters (codex, claude)
+└── cli.py             # skillmesh CLI
+
+examples/registry/
+├── tools.json         # Full tool catalog
+├── tools.yaml         # YAML version of full catalog
+├── instructions/      # Expert instruction files (90+)
+├── roles/             # Role orchestrator files
+└── *.registry.yaml    # Domain-specific registries
+
+skills/skillmesh/      # Codex-installable skill
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how to add expert cards, create registries, and submit PRs.
+
+## Troubleshooting
+
+### `skillmesh: command not found`
+
+```bash
+pip install -e .
+```
+
+### Missing registry path
+
+The CLI and MCP server auto-discover the registry. If auto-discovery fails, pass `--registry` or set:
+
+```bash
+export SKILLMESH_REGISTRY=/path/to/tools.json
+# or pass --registry on every command
+```
+
+### `skillmesh-mcp` fails to start
+
+```bash
+pip install -e .[mcp]
+```
+
+### Codex does not detect new skill
+
+Restart Codex after running `$skill-installer`.
+
+## Development
+
+```bash
+ruff check src tests
+pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+If SkillMesh helps your team, please **star the repo** — it directly improves discoverability and helps others find the project.

skillmesh-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "skillmesh"
+version = "0.1.0"
+description = "A retrieval-gated skill architecture for LLM agents that scales to hundreds of tools by exposing only the top-K relevant capabilities per request."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Open Skill Registry Contributors" }]
+dependencies = [
+  "numpy>=1.24",
+  "PyYAML>=6.0",
+  "rank-bm25>=0.2.2",
+  "jsonschema>=4.0",
+  "chromadb>=0.5.0"
+]
+
+[project.optional-dependencies]
+dense = ["sentence-transformers>=2.7.0"]
+mcp = ["mcp>=1.0.0"]
+dev = ["pytest>=8.0", "pytest-cov>=5.0", "ruff>=0.6.0"]
+
+[project.scripts]
+skillmesh = "skill_registry_rag.cli:main"
+skillmesh-mcp = "skill_registry_rag.mcp_server:main"
+
+[project.urls]
+Homepage = "https://github.com/varunreddy/SkillMesh"
+Repository = "https://github.com/varunreddy/SkillMesh"
+Issues = "https://github.com/varunreddy/SkillMesh/issues"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"skill_registry_rag.data" = ["*.json"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"

skillmesh-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

skillmesh-0.1.0/src/skill_registry_rag/__init__.py

@@ -0,0 +1,17 @@
+"""skill-registry-rag package."""
+
+from .backends import RetrievalBackend
+from .backends.memory import InMemoryBackend
+from .models import ExpertCard, RetrievalHit, ToolCard
+from .registry import load_registry
+from .retriever import SkillRetriever
+
+__all__ = [
+    "ExpertCard",
+    "InMemoryBackend",
+    "RetrievalBackend",
+    "RetrievalHit",
+    "SkillRetriever",
+    "ToolCard",
+    "load_registry",
+]

skillmesh-0.1.0/src/skill_registry_rag/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())